Skip to content

PATTERN Cited by 1 source

Crossplane composition (XRDs + Compositions)

Pattern

Package N cloud primitives behind one high-level Kubernetes custom resource via Crossplane's two-part mechanism:

  • Composite Resource Definition (XRD) — declares a new CRD the platform wants to expose (e.g. DatabaseStack) with its schema (fields app teams fill in).
  • Composition — the recipe that, given an XRD claim, instantiates a set of managed resources (RDS instance + IAM role + Secrets Manager entry + VPC SG + CloudWatch alarm + …) with their fields patched from the claim.

Application teams kubectl apply a 10-line DatabaseStack; the Composition expands it into 30+ cloud resources; Crossplane's controllers reconcile each resource continuously. Drift correction, RBAC, admission control, and GitOps all work on the XRD surface identically to how they work on any K8s resource (concepts/universal-resource-provisioning).

Load-bearing properties

  1. One high-level CR hides many primitives. Complexity lives with the platform team; app teams see one object.
  2. The Composition is the platform's IP. Best-practice AWS configurations, regulated-industry defaults, cost / tagging / security guardrails are all encoded in the Composition, not copy-pasted into every tenant's manifest.
  3. Versioning through labels. Multiple Compositions can back the same XRD (v1, v2, v3-experimental); app teams select via label selector without seeing the underlying migration.
  4. Claims feel like GCP / Azure / SaaS abstractions. An XRD like DatabaseStack can stay the same while its Composition flips from AWS RDS to GCP Cloud SQL to Azure Database for PostgreSQL, enabling the multi-cloud story Crossplane is marketed on.

Relationship to patterns/golden-path-with-escapes

Crossplane Composition is the golden path pattern applied to cloud infrastructure instead of K8s service definitions:

  • Figma's single-source-service-definition (Bazel config → CI → K8s YAMLs) is the golden path for one service's K8s resources.
  • A Crossplane XRD + Composition is the golden path for one environment's cloud infrastructure.

Same posture (opinionated defaults with explicit escape hatches), different layer.

Relationship to other fan-out patterns

Pattern Substrate Fan-out shape
patterns/crossplane-composition Kubernetes + cloud APIs XRD claim → N cloud resources reconciled continuously
patterns/fan-out-stackset-deployment AWS Organizations Single CloudFormation StackSet → N target accounts
patterns/reusable-subscriber-constructs AWS CDK One CDK construct → N AWS resources at synthesis time

All three reduce N-primitives-per-change to 1-API-call-per-change. Crossplane Composition is uniquely continuously reconciled (controller loop) rather than run-triggered (CloudFormation deploy / cdk deploy).

Caveats

  • XRD design is load-bearing. A too-narrow XRD (one per service) defeats the point; a too-broad XRD becomes a dependency-graph nightmare. Picking the right granularity is the platform team's hardest call.
  • Composition complexity compounds. Nested XRDs (XRDs that instantiate other XRDs) are powerful but make the blast radius of a bad Composition update proportional to the depth of the tree.
  • Controller latency + provider-API rate limits become infrastructure-provisioning SLOs — bad Compositions can hammer downstream clouds.
  • Versioning is a live problem. "Can we retire Composition v1 when 200 tenants still reference it?" is the platform team's daily question.

Seen in

  • sources/2026-02-26-aws-santander-catalyst-platform-engineering — Santander Catalyst's stacks catalog is explicitly "a library of composite resource definitions and Compositions enabling quick and standardized creation of complex environments." The stacks catalog is the unit of reuse behind Catalyst's headline provisioning collapse (90 days → hours / minutes) and the substrate under the three named workloads (generative AI agents stack, modern data platform with Databricks + data lakes + ETL, cloud process orchestration on Step Functions).
Last updated · 200 distilled / 1,178 read