What is a CompositeResourceDefinition (XRD) in Crossplane?

Think of an XRD like a form template that an HR department creates for employee requests. The template defines which fields exist (employee name, department, request type), which fields are required versus optional, what valid values look like (department must be one of engineering, marketing, or finance), and what the form is called (Time Off Request). The HR team designs the form once, and then every employee fills in their own copy. The form structure never changes between employees; only the values they enter differ. In Crossplane, the XRD is that form template, defining the API structure that developers use to request infrastructure.

An XRD registers two Kubernetes Custom Resource Definitions (CRDs) with the API server. The first is the Composite Resource (XR), which is cluster-scoped and typically used by platform teams or automation. The second is the Claim (XRC), which is namespace-scoped and designed for application developers. The XRD specifies the API group, kind names for both the XR and Claim, the supported versions, and an OpenAPI v3 schema that defines all the configurable parameters. When the payments-api team needs a database, they create a PostgreSQLClaim in their namespace, and Crossplane validates it against the schema defined in the XRD before accepting it.

The schema section of the XRD is where platform engineers make critical design decisions about what to expose to developers and what to hide. For a database XRD, the platform team might expose parameters like size with an enum of small, medium, and large, region with a list of allowed regions, and engineVersion with supported PostgreSQL versions. They would not expose parameters like subnet IDs, security group rules, or encryption algorithms, because those are standardized across the organization and encoded in the Composition. This schema acts as the contract between the platform team and the application teams. The checkout-service developers know exactly what they can configure, and the platform team knows exactly what guardrails are in place.

The XRD also defines which connection detail keys the Composite Resource publishes. When a database XR is created, it generates connection information like hostname, port, username, and password. The XRD's connectionSecretKeys field declares which of these keys are part of the published API. This is important because it determines what information ends up in the Kubernetes Secret that the application Pod reads for database connectivity. If the platform team adds a new connection detail, like a read replica endpoint for the order-processing-service to use for read-heavy queries, they update both the XRD and the Composition to expose it.

XRDs support multiple versions with conversion, allowing platform teams to evolve their APIs over time without breaking existing consumers. If the platform team decides to rename the size parameter to tier in version v1alpha2, they can define both v1alpha1 and v1alpha2 schemas in the XRD with appropriate defaults and conversion logic. Existing Claims from the inventory-sync team that use v1alpha1 continue to work, while new Claims can use the updated v1alpha2 schema. This versioning strategy mirrors how Kubernetes itself evolves its built-in APIs, moving from alpha to beta to stable, and ensures that platform APIs are treated with the same rigor as any other production API.