| name | krm-api-design |
| description | Design Kubernetes Resource Model (KRM) APIs - CRDs and XRDs. Use when designing, reviewing, or evolving custom resource schemas, composite resource definitions, OpenAPI v3 schemas for Kubernetes, or when the user mentions CRD design, XRD design, API schema design, or asks how to structure fields in a Kubernetes API. |
KRM API Design
Help users design Kubernetes Resource Model APIs that are future-proof, clear to
consume, and follow established conventions. This applies to CRDs and Crossplane
XRDs equally -- an XRD schema is a thin wrapper on a CRD schema.
The goal is a great user experience for API consumers. Think about what it's like
to write YAML against this API, read it back six months later, and evolve it
without breaking anyone.
Design for Evolution, Not Versioning
The most important principle: design APIs that never need a new version.
API designers see version strings like v1alpha1 and assume the path to
evolution is introducing v1alpha2 or v1beta1. This is a trap. CRD versions
are two views into the same stored data. All versions must be round-trippable
to the storage version and back without data loss. This means:
- You can rename or move a field across versions.
- You cannot add a new required field that doesn't exist in older versions.
- You cannot drop a field that was required by an older version.
Introducing a new version buys you surprisingly little. The better path is
designing an API that can evolve with purely additive, backward-compatible
changes. Kubernetes evolved Deployment v1 for 7+ years without needing v2.
The Core Rules
Use Required Fields Sparingly
Assume any required field can never be removed. Ask: does the user genuinely
need to express an opinion about this, or can the system pick a sensible default?
If a sensible default exists, make the field optional with an explicit default
value. Explicit defaults are important -- they make the full desired state
visible rather than hiding it behind "unspecified means default behavior".
