Platform Engineering: Backstage & Crossplane: glossary
60 terms, in plain words, with where each one is taught.
- Backstage (backstage.io)
- An open-source framework for building a developer portal, created at Spotify and now a CNCF project: a software catalog, Software Templates, TechDocs and plugins. Lesson 42.16
- backstage.io/kubernetes-id (Kubernetes plugin, kubernetes-id)
- The label the Backstage Kubernetes plugin uses to find an entity's objects in each cluster; pods need it in the pod template too. Lesson 42.20
- catalog-info.yaml (catalog-info)
- The file in a repository that describes its entities for the Backstage catalog - by convention at the repository root. Lesson 42.16
- claim (claims, claimNames, XRC)
- The Crossplane v1 namespaced proxy for a cluster-scoped XR. Gone in v2, where the XR itself is namespaced; only deprecated v1 XRDs with scope LegacyCluster still offer them. Lesson 42.8
- cognitive load
- How much a team has to keep in its head to do its work: the business domain plus every tool and convention. Team Topologies uses it as the limit a team design must respect. Lesson 42.1
- composed resource garbage collection (garbage collection, rename trap)
- Crossplane deletes composed resources the pipeline no longer returns, so removing or renaming a resource in a Composition deletes the old one for every XR on Automatic updates. Lesson 42.14
- composite resource (XR, XRs)
- One request made with your own API kind, such as a Database in a team's namespace. Crossplane runs its Composition and keeps what it composed in line. Lesson 42.8
- CompositeResourceDefinition (XRD, XRDs, apiextensions.crossplane.io/v2)
- The Crossplane object that defines a new API kind of your own: group, kind, versions with an OpenAPI schema, and scope. Crossplane generates the CRD and starts a controller for it. Lesson 42.8
- Composition (Compositions, compositeTypeRef, mode: Pipeline)
- Says what to build for one XR kind: a pipeline of function steps whose output is the list of resources the XR should have. compositeTypeRef names the kind it serves. Lesson 42.9
- composition render (crossplane render, --observed-resources)
- crossplane composition render: runs a composition locally, functions in Docker, and prints the XR and the resources it would produce - the test before you apply a change. Lesson 42.9
- CompositionRevision (compositionRevisionRef, CompositionRevisions)
- An immutable, numbered copy of a Composition created at every change. XRs point at the revision they use. Lesson 42.14
- compositionUpdatePolicy (Automatic, Manual update policy)
- Whether an XR moves to the newest CompositionRevision on its own (Automatic, the default) or stays put until someone changes its revision reference (Manual). Lesson 42.14
- connect failed (observe failed, create failed, CannotConnectToProvider)
- Prefixes of a managed resource's Synced message that say which reconcile step broke: connect (config or credentials), observe, create, update or delete. Lesson 42.12
- control plane (control loop)
- Software that keeps comparing what you asked for with what exists and corrects the difference, forever. Kubernetes is one for containers; Crossplane extends it to cloud resources. Lesson 42.2
- Crossplane
- A CNCF project that turns a Kubernetes cluster into a control plane for infrastructure: providers manage cloud resources as Kubernetes objects, and platform teams publish their own APIs on top. Lesson 42.2
- crossplane CLI (crossplane resource trace, crossplane composition render, crossplane beta trace)
- The crossplane command for your laptop: resource trace prints an XR and everything it composed as a tree, composition render runs a composition locally. Older articles say beta trace and render. Lesson 42.2
- crossplane-init (init container crossplane-init)
- The init container of the Crossplane pod that installs Crossplane's own CRDs before the main container starts. That is why the Helm chart has no CRDs and helm uninstall leaves them behind. Lesson 42.2
- crossplane.io/paused (ReconcilePaused, paused annotation)
- An annotation that stops Crossplane reconciling an object until it is removed; Synced shows False with reason ReconcilePaused. Lesson 42.12
- DeploymentRuntimeConfig (runtimeConfigRef)
- A Crossplane object that shapes the Deployment of a provider or function: resources, arguments and a fixed ServiceAccount name, so RBAC survives upgrades. Lesson 42.4
- entity (entities, Component, System)
- One thing in the catalog with apiVersion, kind, metadata and spec: Component, API, Resource, System, Domain, Group, User, Location, Template. Lesson 42.16
- entity reference (entity ref, kind:namespace/name)
- How entities point at each other: kind:namespace/name, where kind and namespace may be left out when the field has a default (owner: Group, namespace: default). Lesson 42.16
- Established (ESTABLISHED, WatchingCompositeResource, OFFERED)
- The XRD condition that says Crossplane created the CRD for the new kind and watches it. OFFERED is the old claims column, empty in v2. Lesson 42.8
- external name (crossplane.io/external-name, external-name)
- The annotation with the resource's name or ID in the external system. Defaults to the object's name for many kinds; setting it to an existing resource is how you import it. Lesson 42.6
- forProvider (atProvider, initProvider)
- The fields of a managed resource: spec.forProvider is what you want, status.atProvider what the provider observed, spec.initProvider values only used when creating. Lesson 42.6
- Function (composition function, functions.pkg.crossplane.io)
- A Crossplane package that runs as a gRPC server and is called by composition pipelines to produce or change the resources an XR should have; function-patch-and-transform is the common one. Lesson 42.4
- function-patch-and-transform (patch-and-transform, P&T, Resources input)
- The function that does classic compositions: base manifests plus patches that copy values between the XR and its resources, with transforms on the way. Lesson 42.9
- golden path (golden paths, paved road)
- A supported, opinionated and optional way to do a common task, such as creating a new service, with the company's defaults built in. Optional is the point: teams choose it because it is easier. Lesson 42.1
- Healthy condition (Installed condition, HealthyPackageRevision, ActivePackageRevision)
- The two conditions of a Crossplane package: Installed (a revision is active) and Healthy (its controller runs and its CRDs are in place). Both True means the package works. Lesson 42.4
- InjectedIdentity
- A credentials source where the provider uses the identity its pod already has - for provider-kubernetes, its ServiceAccount, which needs RBAC for every kind it manages. Lesson 42.4
- internal developer platform (IDP, developer platform)
- The self-service layer a platform team runs for the company's product teams: a portal, platform APIs and golden paths that let a team get a service, a database or a pipeline without opening tickets. Lesson 42.1
- LastAsyncOperation (AsyncOperation)
- Conditions on Terraform-based (Upjet) managed resources that report the long create, update or delete running in the background, and its error if it failed. Lesson 42.6
- location (Location entity, dryRun, locations)
- A registered URL the catalog reads entities from, again and again. Registering a location is how a catalog-info.yaml gets into Backstage; ?dryRun=true only checks it. Lesson 42.16
- managed resource (MR, managed resources, kubectl get managed)
- A Kubernetes object that stands for exactly one external resource (a bucket, a database) and is reconciled by a provider. kubectl get managed lists all of them. Lesson 42.6
- managed resource finalizer (finalizer.managedresource.crossplane.io)
- The finalizer a provider puts on its managed resources so the object stays until the external resource is deleted. With the provider gone, nobody removes it and the object hangs. Lesson 42.6
- ManagedResourceDefinition (MRD, ManagedResourceActivationPolicy, MRAP)
- The Crossplane v2 object a provider ships for each kind it manages; it only becomes a real CRD once a ManagedResourceActivationPolicy activates it. The default policy activates everything. Lesson 42.4
- managementPolicies (management policies, Observe)
- The list of what Crossplane may do to an external resource: Observe, Create, Update, Delete, LateInitialize; ["*"] is all. Without Delete, deleting the object leaves the resource in place. Lesson 42.6
- patch (FromCompositeFieldPath, ToCompositeFieldPath, CombineFromComposite)
- A rule in function-patch-and-transform that copies a field from the XR into a composed resource or back. A missing source field is skipped silently unless the policy says Required. Lesson 42.9
- platform engineering (platform team)
- Building and running an internal developer platform as a product, with the product teams as its customers: talk to them, measure adoption, and make the supported way the easiest one. Lesson 42.1
- Policy check failed (InputError, FieldFormatEntityPolicy)
- The catalog's error when an entity breaks a rule, such as a metadata.name with spaces or a missing required field. A new entity that fails never appears. Lesson 42.16
- Provider (Crossplane provider, providers.pkg.crossplane.io)
- A Crossplane package that adds managed resource kinds for one external API (AWS S3, Kubernetes...) and runs the controller that reconciles them. Lesson 42.4
- provider family (provider-family-aws, family provider)
- The parent package of the split AWS providers: it owns the ProviderConfig kinds, and every provider-aws-<service> depends on it, so the package manager installs it automatically. Lesson 42.4
- ProviderConfig (ClusterProviderConfig, providerConfigRef)
- Tells a provider how to authenticate: a Secret with credentials, an injected identity, IRSA. Managed resources reference one; by default the ClusterProviderConfig named default. Lesson 42.4
- ProviderRevision (FunctionRevision, package revision)
- An immutable record of one installed package version, named after the package and 12 hex characters of its digest. One is Active; one inactive revision is kept for rollback. Lesson 42.4
- readinessChecks (MatchCondition, readiness check)
- How function-patch-and-transform decides a composed resource is ready. Default: its Ready condition is True; objects without one (Deployments, Services) need an explicit check. Lesson 42.9
- Ready condition (READY, Available, Creating)
- The condition that says whether the external resource (or, for an XR, everything it composed) is usable. Independent of Synced. Lesson 42.6
- relation (ownedBy, ownerOf, dependsOn)
- A link the catalog derives from spec fields, stored in both directions: ownedBy / ownerOf, partOf / hasPart, dependsOn / dependencyOf, providesApi / apiProvidedBy. Lesson 42.16
- resource trace (crossplane trace, trace -o wide)
- crossplane resource trace: the XR and everything under it as a tree with SYNCED, READY and STATUS per object; -o wide shows the full messages. Lesson 42.12
- scaffolder action (fetch:template, publish:gitlab, publish:github)
- A step a template can run: fetch:template renders a skeleton, publish:* creates a repository, catalog:register adds its catalog-info.yaml to the catalog. Lesson 42.18
- skeleton (template skeleton, values.)
- The folder of files fetch:template renders. Expressions in it read only values, the inputs the step passes in - anything else renders as empty. Lesson 42.18
- software catalog (Backstage catalog, catalog)
- Backstage's database of the company's software and its owners, filled from catalog-info.yaml files the teams keep in their repositories. Lesson 42.16
- Software Template (Template, scaffolder, scaffolder.backstage.io/v1beta3)
- A Backstage catalog entity that turns a form into steps - render a skeleton, create a repository, register it in the catalog. The scaffolder runs it as a task with a log. Lesson 42.18
- spec.crossplane (compositionRef, compositionSelector, resourceRefs)
- Where Crossplane v2 keeps its own fields on an XR: which Composition and revision it uses, the update policy, and the references to the resources it composed. Lesson 42.8
- Synced (SYNCED, ReconcileSuccess, ReconcileError)
- The condition that says whether Crossplane's last reconcile of an object succeeded. False means it cannot manage the object right now, even if the external resource works. Lesson 42.6
- Team Topologies (stream-aligned team, enabling team, complicated-subsystem team)
- A book and model by Skelton and Pais with four team types (stream-aligned, platform, enabling, complicated-subsystem) and three ways they interact (collaboration, X-as-a-Service, facilitating). Lesson 42.1
- TechDocs (techdocs-ref, backstage.io/techdocs-ref, docs like code)
- Backstage's docs-like-code system: Markdown in the repository, built with MkDocs and the techdocs-core plugin, shown on the entity's Docs tab. Lesson 42.20
- techdocs-cli (@techdocs/cli, techdocs-core, mkdocs.yml)
- The command that builds (generate) and uploads (publish) TechDocs sites, usually in CI. It runs MkDocs in the spotify/techdocs container unless told --no-docker. Lesson 42.20
- thinnest viable platform (TVP)
- The smallest platform that removes real work for teams - sometimes a documented template, not a new system. A warning against platforms that grow into a second bureaucracy. Lesson 42.1
- transform (map transform, string Format, convert transform)
- A step applied to a patched value: map (look a key up), string (format, convert case, trim), math, convert (change type). A map transform fails on an unknown key. Lesson 42.9
- Usage (protection.crossplane.io, nousages, replayDeletion)
- A Crossplane object that marks a resource as in use; the API server refuses to delete the used resource while a Usage points at it. Lesson 42.14
- X-as-a-Service (as a service)
- The interaction mode where one team uses what another provides with little talking - a form or an API instead of a meeting. The normal mode between a platform team and product teams. Lesson 42.1