Cloud infrastructure
Crossplane
1.What is Crossplane ?
A control plane framework for platform engineering. You define your own Kubernetes APIs and Crossplane runs the controllers behind them : custom resources without writing an operator.
| Part | What it gives you |
|---|---|
| Managed resources | One object per cloud thing |
| Composition | Your own API from many parts |
| Operations | One-off, cron or watch runs |
| Package manager | Providers, functions, configs |
Use all four or only some. CNCF graduated 2025-10-28. Latest core v2.4.3 (2026-10-22), a new minor every quarter, the three newest supported.
2.How the parts fit
Helm installs two Deployments in crossplane-system. Packages add more pods.
- crossplane : core. Installs core CRDs, starts an XR controller per XRD, calls functions.
- rbac-manager : grants core access to XRs and MRs. Others may need a ClusterRole.
- Provider pod : one per provider, syncs MRs with a cloud API.
- Function pod : Deployment + Service, gRPC on 9443.
3.Providers and managed resources
A provider package adds MR CRDs and runs a controller. One managed resource (MR) = one external thing, like one S3 bucket.
- forProvider : desired settings, enforced. initProvider : used only at create. atProvider : what the cloud reports.
- managementPolicies : Observe, Create, Update, Delete, LateInitialize. Default
["*"]. - Keep the cloud resource on delete : leave
Deleteout. Namespaced MRs have no deletionPolicy. - Import : set
crossplane.and start withio/ external-name ["Observe"].
apiVersion: s3.aws.m.upbound.io/v1beta1 kind: Bucket # namespaced MR metadata: namespace: default generateName: crossplane-bucket- spec: forProvider: region: us-east-2 # providerConfigRef defaults to # {kind: ClusterProviderConfig, name: default}
4.What v2 changed
| Area | In v2 (since Aug 2025) |
|---|---|
| XRs | Namespaced by default. Cluster scope still allowed |
| Claims | Legacy. Only with a v1 XRD, scope LegacyCluster |
| MRs | Namespaced, in .m. groups. Cluster MRs are legacy |
| Compositions | Pipeline mode only. May include any Kubernetes kind |
| Operations | New, alpha : run a pipeline once, on cron or on watch |
| Provider CRDs | Become MRDs. With safe-start, an MRAP picks the CRDs |
| Removed | Native P&T, ControllerConfig, secret stores (use ESO) |
- One minor at a time, latest patch, up to v1.20.
- Run
crossplane beta upgrade check(v1.20.9+ CLI only). - Convert
mode: Resources, drop--registry, fully qualify packages. - Old claims and legacy MRs keep working.
1.XRD and Composition
XRD = schema of a new API, turned into a CRD plus an XR controller. Composition = how to build each XR.
apiVersion: apiextensions.crossplane.io/v2
kind: CompositeResourceDefinition
metadata: { name: apps.example.crossplane.io }
spec:
scope: Namespaced # default; or Cluster. Immutable
group: example.crossplane.io
names: { kind: App, plural: apps }
versions: # openAPIV3Schema trimmed
- { name: v1, served: true, referenceable: true }
---
apiVersion: example.crossplane.io/v1
kind: App # the XR
metadata: { namespace: default, name: my-app }
spec: { image: nginx } # + spec.crossplane fields
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata: { name: app-yaml }
spec:
compositeTypeRef: # immutable
apiVersion: example.crossplane.io/v1
kind: App
mode: Pipeline # the only mode in v2
pipeline: # 1 to 99 steps
- step: deployment
functionRef: { name: function-patch-and-transform }
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources # base Deployment + patches
- step: mark-ready # last, bar a sequencer
functionRef: { name: function-auto-ready }
2.How the pipeline runs
- Each step gets the snapshot, the desired state so far and a context.
- Pass on all desired state. Anything dropped is deleted.
- A step may set XR status, never the XR's own spec.
3.Composition functions
| function- | Latest | Input kind | Good for |
|---|---|---|---|
| patch-and-transform | v0.11.2 | Resources | v1-style patches, transforms, readiness checks. No loops or ifs |
| go-templating | v0.13.2 | GoTemplate | Go templates with Sprig, inline or from files |
| kcl | v0.12.3 | KCLInput | KCL programs, inline or oci:// |
| python | v0.6.0 | Script | compose() or operate(). Also runs in Operations |
| environment-configs | v0.9.2 | Input | Loads EnvironmentConfigs into the pipeline context |
| auto-ready | v0.7.3 | Input | Marks healthy composed resources ready. Put it last |
Install as a pkg. Function. SDKs : Go, Python. function-sequencer (v0.6.1) orders creation, after auto-ready.
4.Readiness and status
- A composed resource is ready only when a function returns
READY_TRUE. Unset = not ready. Crossplane never guesses. - auto-ready has checks for core kinds (Deployment, Service, Job ...). Others, MRs too, need
Ready=True. - No Ready condition at all (a composed Provider, a Cluster API v1beta2 Cluster) = XR stuck. Add an alpha CEL check.
- XR status : a function returns a partial XR with only
status.
1.CRD count and MRD activation
About 3 MiB of API server memory per CRD (docs estimate). provider-upjet-aws v2.9.0 ships 1063 namespaced + 1063 legacy service CRDs.
- Families : one provider per cloud service.
- MRDs (alpha API) : each MR CRD becomes an MRD. Only an active one makes a real CRD. One-way.
- Helm activates all by default. Install with
--set provider., then write MRAPs.defaultActivations={} - Copy names from
kubectl get mrds: the docs'*.examples match nothing.aws. m. crossplane. io
2.Operations (alpha)
A pipeline that runs to the end, like a Job for API objects. Off until --enable-operations.
- Operation : once. CronOperation : schedule. WatchOperation : on change.
- Functions need the
operationcapability (function-python). - Force-applies, no owner refs, can't delete. retryLimit 5 if unset.
3.Packages
Provider, Function, Configuration : pkg., fully qualified OCI images.
- Configuration : XRDs, Compositions,
dependsOn. - Each change = a new revision, one active.
- DeploymentRuntimeConfig shapes the pod, ImageConfig rewrites registries.
- Pin by
@sha256:. With signature checks on, tags could be swapped before v2.2.3 / v2.3.3.
4.Commands
| Command | Does |
|---|---|
helm install crossplane --namespace crossplane-system --create-namespace crossplane-stable/crossplane | Install core. Repo charts.crossplane.io/stable |
curl -sfL "https:// | CLI crossplane (was crank), pinned. Own release train |
kubectl get pkg ; kubectl get xrd | Packages INSTALLED / HEALTHY, XRDs ESTABLISHED |
kubectl get composite -A ; kubectl get managed -A | Every XR, every MR (slow with many CRDs) |
kubectl get mrds ; kubectl get mrap -o yaml | MRD state, and what each MRAP activated |
crossplane resource trace app my-app -n default -o wide | XR, children and MRs as a tree with status |
crossplane composition render xr.yaml composition.yaml functions.yaml | Run the pipeline locally (Docker) |
crossplane cluster top | CPU and memory of Crossplane pods. Needs metrics-server |
crossplane xpkg build --package-root=package/ then xpkg push | Build and push a package |
5.Crossplane vs Terraform vs Cluster API
| Aspect | Crossplane | Terraform / OpenTofu |
|---|---|---|
| Shape | Always-on control plane | A CLI you run |
| State | An object per resource | One locked state file |
| Drift | Reverted by the loop | Only when someone runs it |
| Abstraction | XRD = a real API + RBAC | Modules |
| Immutable field | Never applied | Plans a replacement |
- No
READY_TRUE, no Ready XR. Read events too. - P&T paths are Optional : typos are silent.
- Modern XRs publish no connection Secret.
- A Provider delete is never refused. MRs first.
- Uninstall : XRDs, MRs, Providers, core, CRDs.
paused: "true"also blocks deletes.- Webhooks off = Usages silently off.
- Many CRDs slow Argo CD : raise QPS.