Crossplane Vocabulary: English for Control Plane as Code Discussions

When you join a platform engineering team that uses Crossplane, you quickly realize that the vocabulary is dense — and that even experienced engineers sometimes struggle to explain these concepts clearly in English. This post focuses on the English you need: the precise terms, the natural collocations, and the phrases your teammates actually use in architecture discussions and code reviews.

Core Vocabulary: The Building Blocks

Composite Resource (XR)

A composite resource (shortened to XR) is an abstraction layer that combines multiple managed resources into a single, higher-level resource that application teams can consume.

“We exposed a composite resource called XPostgresInstance so that dev teams don’t have to touch the underlying RDS and security group configs directly.”

In conversation, engineers often say “the XR” or “a composite.” You’ll hear phrases like “define an XR,” “claim an XR,” and “the XR is reconciling.”

Claim

A claim is what an application developer submits to request a composite resource. Claims are namespace-scoped, while XRs are cluster-scoped — this distinction matters for how you explain the architecture.

“The backend team just filed a claim for a new database. Once the composition reconciles, they’ll get their connection secret automatically.”

Notice the verb file a claim — borrowed from insurance/legal English, it’s commonly used in platform engineering contexts.

Composition

A composition is the template that defines how Crossplane should build a composite resource — which managed resources to create, how to configure them, and how to patch values between them.

“We updated the composition to patch the region from the claim into all three managed resources. It took a while to get the patching logic right.”

Key verbs: write a composition, update the composition, the composition defines, patch values.

Managed Resource

A managed resource is a Kubernetes custom resource that represents a single external infrastructure object — an S3 bucket, a VPC subnet, an IAM role. Crossplane’s provider controls its lifecycle.

“Each managed resource maps one-to-one to an object in AWS. If you delete the managed resource, Crossplane deletes the actual bucket.”

The phrase maps one-to-one is very useful here for explaining the relationship in architecture reviews.

Provider

A provider is a Crossplane package that knows how to talk to a specific external API — AWS, GCP, Azure, Helm, etc. It installs the CRDs and the controller logic.

“We’re running the AWS provider at version 0.47. Before we upgrade, we need to check if any managed resource APIs changed.”

Engineers say install a provider, configure a provider, the provider is healthy/degraded.

Control Plane

The control plane in Crossplane’s context means the Kubernetes cluster (or managed control plane) that runs Crossplane itself and acts as the source of truth for your infrastructure.

“We treat our control plane cluster as a read-only source of truth. Nobody applies resources manually — everything goes through Git and Crossplane.”

Reconciliation Loop

The reconciliation loop is the core mechanism: Crossplane continuously compares the desired state (what your YAML says) with the observed state (what actually exists in the cloud), and acts to close any gap.

“The reconciliation loop caught the drift immediately — someone had modified the security group in the console, and Crossplane reverted it within 30 seconds.”

Common collocations: the loop detects drift, reconciliation fails, the resource is reconciling, stuck in reconciliation.

Real IT Context: Phrases Engineers Actually Use

Here are natural phrases you’ll encounter — and need to produce — in real platform engineering conversations:

In architecture discussions:

• “The claim abstracts away all the implementation details from the developer.”
• “We compose three managed resources under that XR — a subnet, a security group, and an RDS instance.”
• “The composition uses patches to propagate values from the claim spec into each managed resource.”

In code reviews:

• “This composition is missing a readiness check — the XR will show as ready before the database is actually available.”
• “You should use a FromCompositeFieldPath patch here, not a hardcoded value. That way the region stays configurable.”

In incident postmortems:

• “The provider lost its credentials and the reconciliation loop started failing silently. We didn’t catch the drift for two hours.”
• “We found that the composition had a bug in the patch logic — it was overwriting the storage size with the default every time the loop ran.”

Key Collocations

Learning words in pairs and phrases makes them stick faster:

Collocation	Meaning
expose a composite resource	make an XR available for teams to claim
file / submit a claim	request infrastructure via a claim object
the composition reconciles	Crossplane applies the template and syncs state
managed resource drifts	real infra diverges from desired YAML state
install / configure a provider	set up the Crossplane package for a cloud API
detect / correct drift	find and fix differences between desired and actual state
the loop is stuck	reconciliation is not making progress
patch a field	copy a value from one resource spec to another

H3: Explaining Crossplane to Non-Platform Engineers

One common challenge is explaining Crossplane’s model to developers who only know Terraform or plain Kubernetes. Here are two useful English patterns:

The analogy pattern:

“Think of Crossplane like Terraform, but instead of running terraform apply from your laptop, the control plane cluster is always running it for you — continuously.”

The layers pattern:

“There are two layers. Platform engineers write compositions that define how infrastructure is built. Application developers file claims that say what they need. The two layers are deliberately decoupled.”

Practice

Pick one concept from this post — for example, reconciliation loop or composition — and write a short Slack message (3-4 sentences) explaining it to a new backend developer joining your team. Focus on using natural collocations rather than translating word-for-word from Ukrainian. Then try writing a one-sentence code review comment that uses the term correctly in context. This kind of deliberate practice in real IT formats is far more effective than reading definitions alone.

Mastering the Control Plane – Vocabulary & Practical Application

Crossplane itself is a powerful concept – but truly unlocking its value comes from understanding how to talk about it effectively. This isn’t just about technical jargon; it’s about communicating clearly with your team, documenting decisions, and ultimately driving successful infrastructure-as-code deployments. This section focuses on refining that communication, particularly for those new to the world of XRs (eXtended Resources) and compositions – all core elements within Crossplane’s control plane.

Let’s be honest, a lot of the initial discussions around Crossplane can feel abstract. People talk about “stateful sets,” “declarative infrastructure,” and “composable architecture” without always connecting it to tangible outcomes. The key is translating those concepts into language that resonates with everyone involved – from developers building applications to operations teams managing deployments. A common mistake is getting bogged down in overly technical details, leading to misunderstandings and delays. Clear communication about the why – why a particular change is being made, what problem it solves, and how it aligns with overall business goals – is paramount. Furthermore, remember that terminology evolves; actively seeking clarification when needed—asking “Can you explain that in simpler terms?”—is always more productive than silently struggling to grasp a concept.

Let’s look at a realistic scenario: Sarah, a developer, is creating a new PR for a Crossplane composition deploying a database. She writes the PR description like this: “This PR adds a new PostgreSQL XR to our ‘Data Lake’ Composition. It leverages a declarative approach to provisioning and managing database resources, aligning with our broader strategy of automating infrastructure deployments. We’re using [Specific Kubernetes label] for targeting and have implemented monitoring via Prometheus.”

Now, imagine David, an operations engineer, reads that description. He might be confused by terms like “declarative approach” without understanding the underlying implications. Or he may not immediately grasp the connection between the Kubernetes labels and the actual deployment process. A more effective PR description might say: “This PR adds a new PostgreSQL database to our ‘Data Lake’ Composition, automating its creation according to defined specifications. This will reduce provisioning time by [estimated percentage] compared to manual methods. We’re targeting this database with [Specific Kubernetes label], ensuring it integrates correctly with existing monitoring systems using Prometheus.”

This revised description uses simpler language and explicitly connects the technical details to their benefits – faster provisioning and integration with existing monitoring. It’s also more action-oriented, focusing on what is being achieved rather than just how.

Here’s a simple kubectl apply example demonstrating how Crossplane manages a resource:

apiVersion: crossplane.io/v1alpha1
kind: Secret
metadata:
  name: my-secret
spec:
  parameters:
    username: "myuser"
    password: "mypassword"
  # This example doesn't actually create a resource - it demonstrates the format of how Crossplane manages secrets

This simple example illustrates the core principle – Crossplane manages the lifecycle of resources, rather than you directly creating them in Kubernetes. The kubectl apply command is used to instruct Crossplane on how to perform this management. Understanding that distinction is crucial for effective communication and collaboration within a Crossplane environment.