OnCallReadyStart learning

Infrastructure as code Lesson 42.8 · Platform Engineering: Backstage & Crossplane · 11 min read

Your own API: CompositeResourceDefinitions

In plain words

An XRD is like designing a new form for the office: you decide which boxes people fill in (size, region), which answers are allowed, and what the office writes back on the form when the job is done. Once the form exists, anyone allowed to use forms in their own room can fill one in, and the office knows exactly what was asked.

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.name must be <plural>.<group>, exactly like a CRD's name. Crossplane names the CRD it generates the same way.
  • group is your API group; use a domain your organisation owns.
  • names: kind and plural (lowercase). Both are immutable: the XRD refuses an edit ("Value is immutable"); renaming a kind means a new XRD.
  • scope: Namespaced (the v2 default) or Cluster. Namespaced XRs let Kubernetes RBAC do the authorisation: a team may create Database objects in its own namespace and nowhere else.
  • versions: like a CRD's. Exactly one is referenceable: the version Compositions are written against. served: true exposes 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, so enum, required, pattern, minimum and defaults are your first line of defence. status fields 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 addsMeaning
spec.crossplane.compositionRefthe Composition this XR uses (chosen once, then kept)
spec.crossplane.compositionSelectorlabels to choose a Composition by
spec.crossplane.compositionRevisionRefthe exact revision in use
spec.crossplane.compositionUpdatePolicyAutomatic (follow new revisions) or Manual (stay pinned)
spec.crossplane.resourceRefsthe resources it composed
status.conditionsSynced 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 scopecluster (LegacyCluster)Namespaced (default) or Cluster
Team requestsa claim in its namespacethe XR, in its namespace
Crossplane's XR fieldsspec.compositionRef, ...spec.crossplane.compositionRef, ...
Connection secretswriteConnectionSecretToRef on the XRcompose 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: small ages well; instanceClass: db.t4g.micro ties every team to today's AWS catalogue.
  • Validate at the edge. An enum rejects size: tiny at kubectl 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) in status so 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.

Why it helps

The XRD is the part of a platform your users touch every day, and a badly designed one is hard to change because every field becomes a promise. Knowing what Crossplane generates from it, how scope and versions work, and why claims disappeared in v2 lets you design small, stable APIs, evolve them through versions, and read other teams' platforms without confusion.

Commands in this lesson

kubectl

FAQ

Why must the XRD name be plural dot group?

Crossplane generates a CRD for the new kind, and a CRD's name is always the plural followed by the group. The XRD uses the same name so the two match one to one; names and group are immutable once created.

Namespaced or Cluster scope?

Namespaced, the v2 default, lets Kubernetes RBAC decide who may make requests: a team creates Database objects in its own namespace and nowhere else, and the composed resources land there too. Cluster scope is for things that are not owned by one team.

What does ESTABLISHED mean?

That Crossplane created the CRD for the new kind and started watching it, with reason WatchingCompositeResource. The OFFERED column belongs to claims and stays empty for v2 XRDs, because v2 has no claims at all.

Where did claims go?

In v1 an XR was cluster-scoped and teams used a namespaced claim that pointed at it. v2 makes the XR itself namespaced, so there is nothing to proxy. The v2 XRD API refuses claimNames; the deprecated v1 XRD with scope LegacyCluster still offers them for older platforms.

How should I design the schema?

Ask for intent, not implementation (size: small rather than an instance class), validate at the edge with enum, required and pattern, keep the API small, version it starting at v1alpha1, and report useful outputs such as the address in status so teams never need to read managed resources.

In an interview Mid

How do you publish a self-service API with Crossplane?

Write a CompositeResourceDefinition in apiextensions.crossplane.io/v2: a group, kind and plural, scope Namespaced, and a versioned OpenAPI schema with only the fields teams should choose, validated with enum and required. Crossplane generates the CRD and its controller. Then a Composition says what to build for that kind, and each request is a composite resource in the team's namespace; RBAC on the namespace decides who may ask.

Also asked: What fields does Crossplane add to every composite resource? · Why did Crossplane v2 remove claims? · How would you version a platform API?

Practise this lesson in the terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.