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.

Navigating Nuances: Addressing Common Communication Challenges

As a non-native English speaker delving into the world of Crossplane and building cloud APIs, you’ll quickly realize that technical vocabulary is only half the battle. The real challenge lies in how you communicate your ideas – whether it’s crafting a clear pull request description, participating in code reviews, or collaborating with team members. Subtle differences in phrasing can lead to misunderstandings, delays, and frustration. Let’s look at some common scenarios and how to approach them effectively.

One frequent hurdle is articulating the reasoning behind your Crossplane configurations. Simply stating “I created this ManagedResource” isn’t enough. A reviewer needs to understand why you chose that specific configuration – what problem it solves, what constraints it addresses, and how it aligns with overall architectural goals. Phrases like “To ensure consistent naming conventions across our infrastructure,” or “This ManagedResource allows us to leverage the latest security patches automatically” are far more informative and demonstrate a deeper understanding of the system. Similarly, when explaining a complex XRD (Crossplane Resource Definition), avoid jargon without context. Instead of saying “I’ve applied a patch transform,” explain: “The patch transform ensures our Kubernetes clusters always run with the most recent version of Helm charts, mitigating potential security vulnerabilities.” It’s about conveying intent and demonstrating that you’re thinking critically about the implications of your changes. Another area where nuance matters is in Slack discussions. A terse message like “Fixing this” needs to be expanded upon – “Investigating a transient error preventing deployments; suspecting an issue with the underlying provider configuration.” This provides valuable context for colleagues who need to assist you.

Furthermore, remember that documentation isn’t just about providing instructions; it’s a form of communication. Writing clear, concise PR descriptions and adding comments within your Crossplane configurations is crucial. These documents serve as a record of your decisions and provide valuable information for future developers. Focus on the “why” alongside the “what.”

Let’s illustrate this with a practical example. A reviewer might leave a comment in your pull request like: “Can you elaborate on why you’re using terraform as the provider here? Seems a bit verbose compared to native Kubernetes providers.” Your response should go beyond simply stating, “It’s required by the configuration.” Instead, you’d respond with something like, “Using Terraform provides greater control over infrastructure-as-code best practices and allows us to easily integrate with our existing CI/CD pipeline for validation. While native Kubernetes Providers are suitable in many cases, the flexibility offered by Terraform is essential for managing this specific resource’s lifecycle.”

# Example: Applying a patch transform using Crossplane CLI

crossplane apply -f my-patch-transform.yaml --revision=1

This simple command demonstrates how you might discuss patching – the intention to update resources, the tool used (the CLI), and the specific input file (my-patch-transform.yaml). It’s a building block for more complex discussions about infrastructure management.