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
| Piece | What it is |
|---|---|
| Crossplane core | The controllers in crossplane-system: package manager, composition engine, RBAC manager. |
| Provider | A 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. |
| ProviderConfig | How a provider authenticates (which credentials, which account). |
| Function | A package that runs a step of a composition pipeline. |
| CompositeResourceDefinition (XRD) | Defines a new API kind of your own. |
| Composition | The 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/v2hasscope: Namespacedunless you sayCluster. A team createsDatabase/ordersin 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 (scopeLegacyCluster) still has them. - Crossplane's fields move under
spec.crossplane.compositionRef,compositionSelector,compositionUpdatePolicy,resourceRefslive there, so they never collide with your ownspecfields. - 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 nodeletionPolicy: what Crossplane may do is set bymanagementPolicies. - 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.