English for Crossplane Developers

Crossplane extends Kubernetes vocabulary into infrastructure provisioning, so a platform engineer needs to layer new terms — composition, claim, provider — on top of concepts already familiar from Terraform or plain Kubernetes.

Key Vocabulary

Provider — a Crossplane extension that adds support for a specific cloud or service, such as AWS or GCP, registering the custom resources needed to manage that platform’s infrastructure. “That resource type doesn’t exist yet because we haven’t installed the provider for it — check whether it’s covered by the AWS provider before writing a custom one.”

Composition — a template that defines how a higher-level, platform-team-defined resource maps to one or more underlying cloud resources, encapsulating implementation details from application teams. “Update the composition, not each team’s claim — that’s the whole point of centralizing the implementation in one place.”

Claim — a namespaced request from an application team for infrastructure, written against a simplified API the platform team defined, that Crossplane fulfills using a matching composition. “App teams just submit a claim for a database — they don’t need to know whether it provisions RDS or Cloud SQL underneath.”

Composite resource (XR) — the cluster-scoped resource Crossplane creates in response to a claim, representing the actual bundle of underlying cloud resources being managed. “Check the composite resource’s status, not just the claim — the claim can look healthy while the underlying XR is still reconciling.”

Reconciliation — Crossplane’s continuous process of comparing desired state, as declared in compositions and claims, against actual cloud state, and correcting any drift automatically. “Someone changed the instance size directly in the AWS console — reconciliation will revert it back to what’s declared, so make the change through the claim instead.”

Common Phrases

• “Is this provider actually installed, or is the resource type just not available yet?”
• “Should this change go in the composition, or does it only affect one team’s claim?”
• “Is the claim healthy, or is the underlying composite resource still stuck reconciling?”
• “Did someone modify this outside Crossplane? Reconciliation should catch and revert manual drift.”
• “Does this composition abstract enough detail, or are app teams still exposed to cloud-specific parameters?”

Example Sentences

Debugging a drift issue: “Someone resized the database directly in the cloud console, and reconciliation just reverted it — if that change was intentional, it needs to go through the claim, not the console.”

Explaining an architecture choice: “We built one composition for ‘standard database’ that app teams claim against, so they never have to know or care whether it’s backed by RDS or Cloud SQL.”

Reviewing a pull request: “This hardcodes a specific instance type inside the claim — that detail belongs in the composition so it can be tuned centrally without every team’s claim changing.”

Professional Tips

• Distinguish claim from composite resource precisely — the claim is the namespaced request, the XR is what actually got provisioned, and conflating them makes status debugging confusing.
• Say composition when describing where implementation details should live — it’s the platform team’s abstraction layer, and naming it correctly clarifies ownership.
• Reference provider explicitly when a resource type is missing — it’s usually a missing or outdated provider installation, not a Crossplane bug.
• Use reconciliation to explain automatic drift correction — it reframes “why did my manual change get reverted” from a bug report into expected behavior.

Practice Exercise

1. Explain the difference between a claim and a composite resource.
2. Describe what a composition abstracts away from application teams and why that matters.
3. Write a sentence explaining what reconciliation does when someone makes a manual change outside Crossplane.

Navigating Nuance: Common Challenges for Non-Native Speakers

Crossplane is a powerful tool, but like any complex technology, it’s often communicated with precision – and sometimes, that precision can be overwhelming for those still developing their fluency in English. The subtle differences in phrasing, the emphasis on specific terms, and the expectation of clear, concise communication are all areas where misunderstandings can easily arise. It’s not simply about knowing what something does; it’s about understanding how it’s being requested, reviewed, or explained. Let’s consider a few typical scenarios that frequently present challenges for developers whose first language isn’t English.

One common issue is the frequent use of “claim” in Crossplane. It’s not simply “requesting” something; you’re claiming resources through a declarative definition. A reviewer might leave a comment on your Pull Request like, “This claim could be more specific. Consider adding labels to clearly identify its purpose and dependencies.” This isn’t criticism of your work; it’s an invitation for clarification – a request for you to articulate the intent behind your claim with greater precision. Similarly, discussions around “compositions” often require careful consideration. It’s not just about assembling components; it’s about defining the relationships and dependencies that create a cohesive, functional whole within Crossplane. Communicating this effectively requires using language that emphasizes orchestration rather than simple concatenation.

Another area of potential confusion lies in the level of detail expected when describing changes to your deployments. A Slack message requesting updates might say: “Can you review the latest PR for the update to the Azure PostgreSQL provider? Ensure the scaling parameters are correctly configured and document any changes to the Kubernetes manifests.” The phrase “correctly configured” isn’t a casual observation; it’s a directive demanding demonstrable proof of adherence to established best practices. Similarly, “document any changes” shifts the burden onto you to explain why those changes were made, providing context for future maintainers – a crucial element often overlooked in initial communication.

Finally, understanding the difference between ‘provision’ and ‘deploy’ is frequently a stumbling block. While both relate to bringing resources online, ‘provision’ carries a stronger connotation of configuring the underlying infrastructure, whereas ‘deploy’ focuses on installing the application itself. Using the right term demonstrates a deeper understanding of the process and helps avoid ambiguity.

# Example: Using Crossplane to provision an AWS S3 bucket
apiVersion: crossplane.crossplane.sh/v1alpha1
kind: Bucket
metadata:
  name: my-s3-bucket
spec:
  storage:
    provisioner: busybox
    type: awsS3

This simple example demonstrates the core vocabulary in action—defining a resource (Bucket) and using a provisioner to bring it into existence within your cloud provider (here, AWS S3). The clarity of this YAML definition is paramount; any ambiguity will be flagged during validation.