OnCallReadyStart learning

Infrastructure as code Lesson 42.2 · Platform Engineering: Backstage & Crossplane · 13 min read

Crossplane v2: the Kubernetes API as a control plane

In plain words

A thermostat does not heat the room once and walk away. You set the temperature you want, and it keeps checking and switching the heating on and off forever. Crossplane is a thermostat for cloud resources: you write down the bucket or database you want as a Kubernetes object, and a controller keeps checking the cloud and fixing it until the real thing matches what you wrote.

Crossplane: the Kubernetes API as a control plane

You already know the pattern from the Kubernetes chapters: you write the desired state as an object, a controller watches it and works, forever, to make the world match. A Deployment controller makes Pods exist. Crossplane extends that loop to things outside the cluster: an S3 bucket, an RDS database, a DNS record, a GitHub repository. You kubectl apply a Bucket object; a controller calls the AWS API until a bucket with that spec exists, and keeps checking that it still does.

Why put infrastructure behind the Kubernetes API instead of running Terraform?

  • It never stops reconciling. Terraform changes the world when someone runs apply. Crossplane notices drift (someone deleted the bucket's tags in the console) on its next poll and puts them back.
  • It reuses what you already have: RBAC decides who may create what, in which namespace; GitOps (Argo CD) syncs the YAML; kubectl get, events and conditions are the status. No state file to lock or lose.
  • It composes. The real reason platform teams use it: you can define your own API (Database, StorageBucket, App) and decide what it builds.

Crossplane is a CNCF project (it graduated in November 2025). Version 2.0 (August 2025) changed the model in ways that matter for anything you read online: much of the material from before 2025 describes v1.

The pieces

PieceWhat it is
Crossplane coreThe controllers in crossplane-system: package manager, composition engine, RBAC manager.
ProviderA package that adds managed resource kinds for one API (AWS S3, Kubernetes objects, Helm releases) and runs their controller.
Managed resource (MR)One external thing, as a Kubernetes object: Bucket, Instance, Object.
ProviderConfigHow a provider authenticates (which credentials, which account).
FunctionA package that runs a step of a composition pipeline.
CompositeResourceDefinition (XRD)Defines a new API kind of your own.
CompositionThe recipe: which resources to create for that kind, and how.
Composite resource (XR)One instance of your kind (Database/orders).

What changed in v2

If you read a tutorial, check which major version it uses. The v2 changes you will see in this chapter:

  • Composite resources are namespaced by default. An XRD in apiextensions.crossplane.io/v2 has scope: Namespaced unless you say Cluster. A team creates Database/orders in its own namespace and the composed resources land in the same namespace.
  • No claims. v1 had two objects per request: a cluster-scoped XR and a namespaced claim pointing at it. v2 drops claims: the namespaced XR is the request. The v2 XRD API refuses claimNames ("Claims aren't supported in apiextensions.crossplane.io/v2"); the deprecated v1 XRD (scope LegacyCluster) still has them.
  • Crossplane's fields move under spec.crossplane. compositionRef, compositionSelector, compositionUpdatePolicy, resourceRefs live there, so they never collide with your own spec fields.
  • Namespaced managed resources. Providers ship a second set of kinds in a .m. API group (s3.aws.m.upbound.io, kubernetes.m.crossplane.io). These have no deletionPolicy: what Crossplane may do is set by managementPolicies.
  • Compose anything. A Composition can create plain Kubernetes objects (Deployments, Services) directly, not only managed resources.
  • Only pipeline compositions. mode: Resources (the old built-in patch and transform) is gone; every Composition is a pipeline of functions.
  • Managed resource definitions. A provider's kinds arrive as ManagedResourceDefinitions; an activation policy decides which become real CRDs, so you do not need 900 AWS CRDs to use three.

Installing with Helm

Crossplane is installed with its Helm chart. The Crossplane docs' commands:

helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update
helm install crossplane --namespace crossplane-system --create-namespace crossplane-stable/crossplane

The chart's NOTES are short. What matters is the version line:

NAME: crossplane
NAMESPACE: crossplane-system
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None
NOTES:
Release: crossplane

Chart Name: crossplane
Chart Description: Crossplane is an open source Kubernetes add-on that enables platform teams to assemble infrastructure from multiple vendors, and expose higher level self-service APIs for application teams to consume.
Chart Version: 2.4.2
Chart Application Version: 2.4.2

Kube Version: v1.37.1

Two Deployments start. Each pod first runs an init container (crossplane-init): the core one installs Crossplane's own CRDs and the default activation policy; then the main containers start.

$ kubectl get pods -n crossplane-system
NAME                                       READY   STATUS    RESTARTS   AGE
crossplane-pk56lw7dsd-k8sj7                1/1     Running   0          29s
crossplane-rbac-manager-6nn9bb6bdr-tdrpn   1/1     Running   0          29s

The RBAC manager gives Crossplane permission to manage every kind a provider or an XRD adds, through ClusterRoles labelled rbac.crossplane.io/aggregate-to-crossplane: "true" that are aggregated into the crossplane ClusterRole. Remember that label: it comes back when you compose a kind Crossplane is not allowed to touch yet.

What the install added

$ kubectl get crds | grep crossplane.io
clusterusages.protection.crossplane.io                          2026-10-22T09:14:03Z
compositeresourcedefinitions.apiextensions.crossplane.io        2026-10-22T09:14:03Z
compositionrevisions.apiextensions.crossplane.io                2026-10-22T09:14:03Z
compositions.apiextensions.crossplane.io                        2026-10-22T09:14:03Z
configurationrevisions.pkg.crossplane.io                        2026-10-22T09:14:03Z
configurations.pkg.crossplane.io                                2026-10-22T09:14:03Z
cronoperations.ops.crossplane.io                                2026-10-22T09:14:03Z
deploymentruntimeconfigs.pkg.crossplane.io                      2026-10-22T09:14:03Z
environmentconfigs.apiextensions.crossplane.io                  2026-10-22T09:14:03Z
functionrevisions.pkg.crossplane.io                             2026-10-22T09:14:03Z
functions.pkg.crossplane.io                                     2026-10-22T09:14:03Z
imageconfigs.pkg.crossplane.io                                  2026-10-22T09:14:03Z
locks.pkg.crossplane.io                                         2026-10-22T09:14:03Z
managedresourceactivationpolicies.apiextensions.crossplane.io   2026-10-22T09:14:03Z
managedresourcedefinitions.apiextensions.crossplane.io          2026-10-22T09:14:03Z
operations.ops.crossplane.io                                    2026-10-22T09:14:03Z
providerrevisions.pkg.crossplane.io                             2026-10-22T09:14:03Z
providers.pkg.crossplane.io                                     2026-10-22T09:14:03Z
usages.apiextensions.crossplane.io                              2026-10-22T09:14:03Z
usages.protection.crossplane.io                                 2026-10-22T09:14:03Z
watchoperations.ops.crossplane.io                               2026-10-22T09:14:03Z

Grouped by API: pkg.crossplane.io is the package manager (Providers, Functions, Configurations and their revisions), apiextensions.crossplane.io is composition (XRDs, Compositions) and resource activation, protection is Usages (deletion protection, later in this chapter), ops is Operations (one-off and scheduled tasks, new in v2; not covered here). No AWS or GCP kinds yet: those come with providers.

Many kinds are cluster-scoped and carry the crossplane category, so one command lists the core objects: kubectl get crossplane. Providers' kinds add the categories managed and providerconfig, and every XR kind gets composite.

The crossplane CLI

The crossplane command-line tool lives in its own repository (github.com/crossplane/cli) and has its own versions. Its install script is served from cli.crossplane.io; the lab has v2.5.0 in /usr/local/bin.

$ crossplane version
Client Version: v2.5.0
Server Version: v2.4.2

Two of its commands matter on call and you will use both: crossplane resource trace (a tree of an XR and everything it composed, with the status of each) and crossplane composition render (run a composition locally, without a cluster, to see what it would create). Older articles write crossplane beta trace and crossplane render (or the even older crossplane beta render): in CLI v2.3 and later the commands are grouped as crossplane resource trace and crossplane composition render. The top-level render still works as a hidden alias; crossplane beta trace does not exist any more.

In an interview: Crossplane turns the Kubernetes API into a control plane for external infrastructure: providers add managed resources that controllers reconcile against cloud APIs, and XRDs + Compositions let a platform team publish its own higher-level APIs. In v2 composite resources are namespaced, claims are gone, and compositions are always function pipelines.

Why it helps

Crossplane is how many platform teams offer infrastructure as an API, and the v2 release changed the model in ways that make much older material misleading. Knowing the pieces (core, providers, managed resources, functions, XRDs, Compositions) and the v2 changes lets you read a cluster you have never seen, install the control plane correctly, and avoid following a v1 tutorial into claims that no longer exist.

Commands in this lesson

kubectl crossplane

FAQ

Why use the Kubernetes API instead of Terraform?

Crossplane reconciles continuously and corrects drift without anyone running apply, it reuses Kubernetes RBAC to decide who may create what, GitOps tools sync its YAML like any other object, and there is no state file to lock or lose. Its real strength is publishing your own higher-level APIs.

What changed in Crossplane v2?

Composite resources are namespaced by default and claims are gone, Crossplane's own XR fields moved under spec.crossplane, providers ship namespaced managed resources with managementPolicies instead of deletionPolicy, compositions are always function pipelines and can compose any Kubernetes object, and provider kinds arrive as ManagedResourceDefinitions.

Where do the CRDs come from if the Helm chart has none?

The core pod's init container, crossplane-init, installs Crossplane's own CRDs and the default activation policy before the main container starts. That is why helm template shows no CRDs and why helm uninstall does not remove them: Crossplane owns them itself.

What does the RBAC manager do?

It gives Crossplane permission to manage every kind a provider or an XRD adds, by creating ClusterRoles labelled rbac.crossplane.io/aggregate-to-crossplane that aggregate into the crossplane ClusterRole. Anything else Crossplane should compose needs a ClusterRole with that label as well.

Which crossplane CLI commands matter on call?

crossplane resource trace, which prints an XR and everything it composed with each object's Synced, Ready and status, and crossplane composition render, which runs a composition locally to show what it would create. Older articles call them crossplane beta trace and crossplane render.

In an interview Mid

What is Crossplane and how does it work?

Crossplane turns the Kubernetes API into a control plane for external infrastructure. Providers add managed resource kinds and run controllers that reconcile them against one external API, authenticated by a ProviderConfig. A platform team defines its own kinds with an XRD and says what to build for them in a Composition, a pipeline of functions; each request is a composite resource. It is installed with Helm into crossplane-system, and in v2 XRs are namespaced and claims are gone.

Also asked: What is the difference between a managed resource and a composite resource? · Why does the Crossplane Helm chart contain no CRDs? · What changed between Crossplane v1 and v2?

Practise this lesson in the terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.