Your own API: the CompositeResourceDefinition
Managed resources are cloud-shaped: an RDS Instance has more than eighty fields. A product team does not want to choose a caCertIdentifier; it wants "a small PostgreSQL database for orders". The platform team writes that smaller API with a CompositeResourceDefinition (XRD), and Crossplane turns it into a real Kubernetes kind.
apiVersion: apiextensions.crossplane.io/v2
kind: CompositeResourceDefinition
metadata:
name: databases.platform.lab
spec:
group: platform.lab
names:
kind: Database
plural: databases
scope: Namespaced
versions:
- name: v1alpha1
served: true
referenceable: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
properties:
size:
type: string
enum: [small, medium, large]
storageGB:
type: integer
required: [size]
status:
type: object
properties:
address:
type: string
Piece by piece:
metadata.namemust be<plural>.<group>, exactly like a CRD's name. Crossplane names the CRD it generates the same way.groupis your API group; use a domain your organisation owns.names:kindandplural(lowercase). Both are immutable: the XRD refuses an edit ("Value is immutable"); renaming a kind means a new XRD.scope:Namespaced(the v2 default) orCluster. Namespaced XRs let Kubernetes RBAC do the authorisation: a team may createDatabaseobjects in its own namespace and nowhere else.versions: like a CRD's. Exactly one isreferenceable: the version Compositions are written against.served: trueexposes it in the API.schema.openAPIV3Schema: the fields a user may set. This is your API contract; the API server validates every request against it, soenum,required,pattern,minimumand defaults are your first line of defence.statusfields are what your composition reports back.
Notice what is not in the schema: instance classes, regions, backup windows. Those decisions belong to the platform team and live in the Composition.
What Crossplane generates
Apply the XRD and Crossplane's definition controller creates a CRD for the new kind and starts a controller for it:
$ kubectl get xrd
NAME ESTABLISHED OFFERED AGE
databases.platform.lab True 3s
ESTABLISHED True (reason WatchingCompositeResource) means the CRD exists and Crossplane watches the new kind. OFFERED is about claims and stays empty in v2: there are none.
The generated CRD is more than your schema. Crossplane adds its own fields under spec.crossplane and the usual status, and gives the kind printer columns and the category composite:
$ kubectl get databases
NAME SYNCED READY COMPOSITION AGE
orders True True database-rds 3m24s
| Field Crossplane adds | Meaning |
|---|---|
spec.crossplane.compositionRef | the Composition this XR uses (chosen once, then kept) |
spec.crossplane.compositionSelector | labels to choose a Composition by |
spec.crossplane.compositionRevisionRef | the exact revision in use |
spec.crossplane.compositionUpdatePolicy | Automatic (follow new revisions) or Manual (stay pinned) |
spec.crossplane.resourceRefs | the resources it composed |
status.conditions | Synced and Ready, rolled up from the composed resources |
The RBAC manager also creates four ClusterRoles per XRD: crossplane:composite:databases.platform.lab:aggregate-to-crossplane (so Crossplane itself may manage the new kind) and ...:aggregate-to-edit, ...:aggregate-to-view, ...:aggregate-to-browse. Their labels aggregate them into the chart's own crossplane-edit, crossplane-view and crossplane-browse ClusterRoles - not into Kubernetes' built-in edit and view. To let a team create Database objects in its namespace, bind it to a role that grants the new kind there (a RoleBinding to crossplane-edit, or a narrower Role of your own).
Claims, and why v2 dropped them
In Crossplane v1 the XR was always cluster-scoped. To let teams request resources from their namespace, an XRD could offer a claim: a namespaced kind (DatabaseClaim, say) that created and pointed at a cluster-scoped XR. Two objects per request, two places to look, confusing names. v2 makes the XR itself namespaced, so there is nothing to proxy:
v1 (apiextensions.crossplane.io/v1, deprecated) | v2 | |
|---|---|---|
| XR scope | cluster (LegacyCluster) | Namespaced (default) or Cluster |
| Team requests | a claim in its namespace | the XR, in its namespace |
| Crossplane's XR fields | spec.compositionRef, ... | spec.crossplane.compositionRef, ... |
| Connection secrets | writeConnectionSecretToRef on the XR | compose a Secret yourself |
Applying a v1 XRD still works, with a warning from the API server:
Warning: CompositeResourceDefinition v1 is deprecated and will be removed in a future release; consider migrating to v2
and claimNames in a v2 XRD is refused by the CRD's validation:
The CompositeResourceDefinition "databases.platform.lab" is invalid: spec: Invalid value: "object": Claims aren't supported in apiextensions.crossplane.io/v2
(simulator) The lab models v1 XRDs only up to that warning; claims are not simulated.
Designing the API
The schema is the part of the platform your users touch every day. A few rules the Crossplane community converged on:
- Ask for intent, not implementation.
size: smallages well;instanceClass: db.t4g.microties every team to today's AWS catalogue. - Validate at the edge. An
enumrejectssize: tinyatkubectl apply, with a clear message, instead of a confusing composition error later. - Keep it small. Every field you add is a field you must support forever, in every Composition.
- Version it. Start at
v1alpha1. When you must make an incompatible change, add a new version rather than breaking the old one. - Report back. Put the useful outputs (
address,bucketName,arn) instatusso teams never need to look at the managed resources.
In an interview: an XRD defines a new API kind (group, names, scope, versioned OpenAPI schema) and Crossplane generates its CRD; a Composition says what to build for it; each instance is a composite resource (XR). In v2 XRs are namespaced and claims are gone.