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.

  • Control plane = a reconcile loop for things outside the cluster : a cloud bucket, a database, a GitHub repo.
  • Declare it once. Hand edits in the cloud get reverted.
  • All of it is API objects, so kubectl, RBAC and GitOps (Argo CD, Flux) just work.
PartWhat it gives you
Managed resourcesOne object per cloud thing
CompositionYour own API from many parts
OperationsOne-off, cron or watch runs
Package managerProviders, 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.
XRD + Composition platform team XR (kind App) user, in a namespace defines reads watches crossplane pod XR controller Function pods RunFunction, :9443 gRPC apply (SSA) observed Composed resources MRs + any kind Provider pod e.g. provider-aws-s3 watches status cloud API S3 bucket, DB ... the provider reverts drift (AWS default poll 10m)

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 Delete out. Namespaced MRs have no deletionPolicy.
  • Import : set crossplane.io/external-name and start with ["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}
ProviderConfig serves MRs in its own namespace. ClusterProviderConfig serves any namespace. provider-aws-s3 pulls in provider-family-aws, which owns the ProviderConfig.

4.What v2 changed

AreaIn v2 (since Aug 2025)
XRsNamespaced by default. Cluster scope still allowed
ClaimsLegacy. Only with a v1 XRD, scope LegacyCluster
MRsNamespaced, in .m. groups. Cluster MRs are legacy
CompositionsPipeline mode only. May include any Kubernetes kind
OperationsNew, alpha : run a pipeline once, on cron or on watch
Provider CRDsBecome MRDs. With safe-start, an MRAP picks the CRDs
RemovedNative P&T, ControllerConfig, secret stores (use ESO)
Upgrading from v1
  1. One minor at a time, latest patch, up to v1.20.
  2. Run crossplane beta upgrade check (v1.20.9+ CLI only).
  3. Convert mode: Resources, drop --registry, fully qualify packages.
  4. Old claims and legacy MRs keep working.
In short : Crossplane turns Kubernetes into a control plane : providers keep managed resources in sync with the cloud, and functions build your own APIs on top.

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

ObserveXR + children, once
1. patch + transformadds the Deployment
2. more stepstemplates, KCL, Python
3. auto-readymarks ready
Applyserver-side apply
  • 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.
  • Children get an owner reference to the XR (GC), applied with SSA.
  • Namespaced XR : children stay in its namespace. Cluster-scoped kinds fail.
  • Functions do not run when an XR is deleted.

3.Composition functions

function-LatestInput kindGood for
patch-and-transformv0.11.2Resourcesv1-style patches, transforms, readiness checks. No loops or ifs
go-templatingv0.13.2GoTemplateGo templates with Sprig, inline or from files
kclv0.12.3KCLInputKCL programs, inline or oci://
pythonv0.6.0Scriptcompose() or operate(). Also runs in Operations
environment-configsv0.9.2InputLoads EnvironmentConfigs into the pipeline context
auto-readyv0.7.3InputMarks healthy composed resources ready. Put it last

Install as a pkg.crossplane.io/v1 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.
External resource in the cloud provider MR status atProvider, Ready observed Function pipeline auto-ready runs last READY_TRUE XR Ready, Synced, conditions legacy only Claim waits until XR Ready XR Ready rule all READY_TRUE : Ready=True, Available otherwise : Creating, Unready ... Warning result : event Fatal : Synced=False TTL (1m) requeues XR
In short : The XRD defines the API, functions build it, and nothing is Ready until a function says so.

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.defaultActivations={}, then write MRAPs.
  • Copy names from kubectl get mrds : the docs' *.aws.m.crossplane.io examples match nothing.
Provider package e.g. provider-aws-ec2 no safe-start : all Active at install each MR CRD MRD, Inactive safe-start default MRAP names, *.prefix matches yes no Active : real CRD about 3 MiB each Inactive : no CRD 197 cost about 20 MiB v2.4+ : provider pod at 0 replicas until one MRD is active

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 operation capability (function-python).
  • Force-applies, no owner refs, can't delete. retryLimit 5 if unset.

3.Packages

Provider, Function, Configuration : pkg.crossplane.io/v1, 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

CommandDoes
helm install crossplane --namespace crossplane-system --create-namespace crossplane-stable/crossplaneInstall core. Repo charts.crossplane.io/stable
curl -sfL "https://cli.crossplane.io/install.sh" | XP_VERSION=v2.5.0 shCLI crossplane (was crank), pinned. Own release train
kubectl get pkg ; kubectl get xrdPackages INSTALLED / HEALTHY, XRDs ESTABLISHED
kubectl get composite -A ; kubectl get managed -AEvery XR, every MR (slow with many CRDs)
kubectl get mrds ; kubectl get mrap -o yamlMRD state, and what each MRAP activated
crossplane resource trace app my-app -n default -o wideXR, children and MRs as a tree with status
crossplane composition render xr.yaml composition.yaml functions.yamlRun the pipeline locally (Docker)
crossplane cluster topCPU and memory of Crossplane pods. Needs metrics-server
crossplane xpkg build --package-root=package/ then xpkg pushBuild and push a package

5.Crossplane vs Terraform vs Cluster API

AspectCrossplaneTerraform / OpenTofu
ShapeAlways-on control planeA CLI you run
StateAn object per resourceOne locked state file
DriftReverted by the loopOnly when someone runs it
AbstractionXRD = a real API + RBACModules
Immutable fieldNever appliedPlans a replacement
Cluster API Clusters only, by design. Crossplane can compose a CAPI Cluster, but v1beta2 reports Available, not Ready : auto-ready needs a CEL check.
Gotchas
  • 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.
Good to know
  • Uninstall : XRDs, MRs, Providers, core, CRDs.
  • paused: "true" also blocks deletes.
  • Webhooks off = Usages silently off.
  • Many CRDs slow Argo CD : raise QPS.
In short : Activate only the MRDs you use, pin packages by digest, and debug with resource trace.