Crossplane: English for Platform Engineers Building Cloud APIs

Crossplane extends Kubernetes into a universal control plane, letting platform engineering teams expose cloud infrastructure as self-service APIs. If you work on a platform team or interact with one, you will quickly encounter a specialised vocabulary that blends Kubernetes concepts with Crossplane-specific abstractions. This guide explains the key terms and the phrases your colleagues use when designing and operating Crossplane-based platforms.

Key Vocabulary

Composition — a Crossplane resource that defines how a composite resource is assembled from one or more managed resources, specifying which cloud primitives to create and how their configuration maps together. “The Composition for a production database cluster creates an RDS instance, a parameter group, and a subnet group as a single unit.”

XRD (CompositeResourceDefinition) — a custom resource definition that registers a new composite resource type with the Kubernetes API, including its schema and the claim names that developers use to request it. “We published an XRD called XPostgresInstance so that application teams can request a database without knowing the underlying AWS details.”

Composite resource (XR) — an instance of a type defined by an XRD; it is created either directly by a platform engineer or indirectly when a developer creates a Claim. “The composite resource is reconciled by Crossplane, which creates all the managed resources described in the Composition.”

Claim — a namespace-scoped resource that a developer creates to request an instance of a composite resource, providing a simpler interface that hides infrastructure complexity. “The developer just applies a PostgresClaim in their application namespace and the platform team’s Composition handles the rest.”

ManagedResource — a Kubernetes object that represents a single external cloud resource, such as an S3 bucket or a GCP Cloud SQL instance, and is reconciled by a Crossplane Provider. “Each managed resource has an atProvider field that reflects the observed state from the cloud API.”

Provider — a Crossplane extension that installs the controllers and CRDs needed to manage resources on a specific cloud platform, such as provider-aws, provider-gcp, or provider-azure. “We upgraded the AWS provider to pick up support for the new RDS blue-green deployment managed resource.”

Patch — a transformation rule within a Composition that copies or converts a value from the composite resource’s spec into a field on one of its composed managed resources. “The patch copies the region field from the XR spec into each managed resource so developers only need to specify it once.”

Transform — an optional modifier applied within a patch to convert a value, for example by mapping a t-shirt size input such as small to a concrete instance type such as db.t3.micro. “We added a string transform so developers pick from small, medium, or large rather than typing AWS instance class names directly.”

Useful Phrases

“The XRD schema validation is rejecting the Claim because the storageGB field is below the minimum we defined — the developer needs to request at least twenty gigabytes.”

“We need to add a patch to propagate the backupRetentionDays field from the XR spec down into the RDS managed resource, otherwise it always defaults to seven.”

“The Provider pod is in CrashLoopBackOff — check that the ProviderConfig references a valid credentials secret in the crossplane-system namespace.”

“Let’s version the XRD so that application teams on the old schema keep working while we roll out the new fields to teams that are ready.”

“The Composition uses a fromCompositeFieldPath patch to pull the environment label off the XR and stamp it onto all the composed resources.”

Common Mistakes

Confusing Claims with composite resources. A Claim is a namespace-scoped shortcut that creates a composite resource; it is not the composite resource itself. Platform engineers work with composite resources directly, while application developers interact via Claims. Mixing up the two leads to confusion when discussing where to look for status conditions or troubleshooting reconciliation errors.

Using “patch” and “transform” interchangeably. A patch is the rule that moves a value from one place to another; a transform is an optional step that modifies the value during that move. You can have a patch without a transform, but you cannot have a transform without a patch. Saying “I added a transform to copy the region” is imprecise — the correct phrase is “I added a patch with a string transform to map the region value.”

Saying “install the resource” instead of “apply the Claim” or “provision the managed resource”. In Crossplane contexts, “install” typically refers to installing a Provider or a Composition into the cluster. Creating infrastructure means applying a Claim or a composite resource. Using “install” for both operations causes misunderstanding during incident response and platform onboarding sessions.

Getting these terms right will help you communicate clearly with platform and application teams, write accurate runbooks, and contribute meaningfully to Composition design reviews.