What is a Crossplane Composition and how does it define infrastructure templates?

Think of a Composition like a blueprint filed at an architecture firm. When a client (developer) requests a standard two-bedroom apartment (Composite Resource), the architect does not design from scratch every time. Instead, they pull the standard blueprint (Composition) that specifies exactly where the walls go, what materials to use, how the plumbing connects, and which electrical codes to follow. The client chooses the apartment size and floor, but the structural decisions are already made by the firm's experts. The blueprint is the single source of truth that guarantees every apartment meets building codes and the firm's quality standards.

A Composition resource in Crossplane connects a Composite Resource Definition (XRD) to the actual cloud resources that should be created when someone instantiates an XR. It contains a list of resource templates, each defining a Managed Resource with its full configuration. The Composition uses patches to map values from the XR's spec into the correct fields of each Managed Resource. For instance, when the payments-api team creates a PostgreSQLInstance XR with size set to large, the Composition patches that value into the RDS Instance's instanceClass as db.r5.xlarge, sets the allocatedStorage to 500 GB, enables multi-AZ deployment, and configures performance insights. The XR's region parameter gets patched into every Managed Resource that needs a region field.

Patches are the mechanism that makes Compositions dynamic rather than static. Crossplane supports several patch types. The FromCompositeFieldPath patch copies a value from the XR down to a Managed Resource, like mapping spec.parameters.region to spec.forProvider.region. The ToCompositeFieldPath patch copies a value from a Managed Resource back up to the XR's status, like surfacing the database endpoint. The Combine patch merges multiple fields, for example concatenating the service name and environment to generate a unique resource identifier. Transform patches apply functions to values, such as mapping the string large to the integer 500 for storage size. These patches give platform teams fine-grained control over how developer inputs translate to cloud configurations.

Compositions also handle the connection details pipeline, which automatically propagates secrets from Managed Resources up to the XR and eventually to the Claim. When an RDS Instance is created, AWS generates an endpoint hostname and the password is already stored in a Secret. The Composition defines connectionDetails entries that extract these values and publish them as a Kubernetes Secret that the checkout-service or user-auth-service application can mount as environment variables. This eliminates the manual step of copying connection strings between teams and systems, which is error-prone and a security risk.

A key design decision is that Compositions support selection through labels. A single XRD can have multiple Compositions, each targeting a different cloud provider or environment tier. The PostgreSQLInstance XRD might have an aws-production Composition that creates multi-AZ RDS with encryption and a gcp-development Composition that creates a basic Cloud SQL instance. The XR selects which Composition to use through a compositionSelector with label matching. This enables true multi-cloud support where the inventory-sync team can provision identical database abstractions on different clouds simply by changing a label. Platform teams can also set a default Composition on the XRD, so developers who do not specify a preference automatically get the production-ready configuration.