references/crd_design.md
CRD design
Custom Resource Definitions (CRDs) define the API surface of your operator. A bad CRD design locks you into hard-to-evolve schemas, forces wrapper APIs, and creates user-facing UX problems via kubectl.
Anatomy of a production CRD
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: myapps.apps.example.com # plural.group
spec:
group: apps.example.com
names:
kind: MyApp # PascalCase
plural: myapps # lowercase
singular: myapp # lowercase
listKind: MyAppList # KindList
shortNames: [ma] # optional
scope: Namespaced # or Cluster (justify)
versions:
- name: v1alpha1
served: true
storage: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
required: [version]
properties:
version:
type: string
pattern: '^[0-9]+\.[0-9]+\.[0-9]+$'
replicas:
type: integer
minimum: 1
maximum: 100
default: 3
status:
type: object
properties:
phase:
type: string
enum: [Pending, Running, Failed]
conditions:
type: array
items:
type: object
required: [type, status, lastTransitionTime]
properties:
type: { type: string }
status: { type: string, enum: ["True", "False", "Unknown"] }
reason: { type: string }
message: { type: string }
lastTransitionTime: { type: string, format: date-time }
observedGeneration: { type: integer }
subresources:
status: {} # CRITICAL — see below
scale: # if scaling is meaningful
specReplicasPath: .spec.replicas
statusReplicasPath: .status.readyReplicas
additionalPrinterColumns:
- name: Phase
type: string
jsonPath: .status.phase
- name: Ready
type: string
jsonPath: .status.conditions[?(@.type=="Ready")].status
- name: Age
type: date
jsonPath: .metadata.creationTimestamp
Required structural elements
1. Status subresource — subresources.status: {}
Without it:
r.Status().Update(ctx, obj)doesn't work — falls back tor.Update- Status updates re-trigger spec reconcile → loop
- RBAC can't be split between spec writers and status writers
Always declare it.
2. Conditions array
Use the standard metav1.Condition shape. Required fields: type, status, lastTransitionTime. Recommended: reason, message, observedGeneration.
Conventional condition types:
Ready— overall readinessReconciling— controller is actively workingDegraded— operating but with reduced capabilityProgressing— change in progress (mostly for Deployments-style flows)
Use meta.SetStatusCondition() from k8s.io/apimachinery/pkg/api/meta — don't write to the slice directly.
3. observedGeneration
Track which spec generation the controller has acted on:
status.ObservedGeneration = obj.Generation
Lets users tell whether status reflects the latest spec or a previous one.
4. Printer columns
kubectl get myapp UX is determined by additionalPrinterColumns. Always include:
PhaseorReady(status)Age(so users know when it was created)
Optionally: replicas, version, key spec field.
5. Validation in the schema, not the controller
Express constraints declaratively:
| Constraint | OpenAPI |
|---|---|
| Range | minimum/maximum |
| String pattern | pattern: '^...$' |
| Enum | enum: [Pending, Running] |
| Required field | required: [...] |
| Default value | default: 3 |
| Min/max length | minLength/maxLength |
Reserve controller validation for cross-field rules and external dependencies (e.g., "this name is taken in our DB").
6. Avoid x-kubernetes-preserve-unknown-fields: true
It disables structural validation. Sometimes needed (e.g., raw kubectl apply patches), but never at the spec root. Use it sparingly on a single sub-tree.
Versioning strategy
CRDs evolve. Plan from day 1:
| Stage | Version | Stability | Allowed changes |
|---|---|---|---|
| Internal preview | v1alpha1 | None | Anything; document breaking changes |
| Beta | v1beta1 | Some | Additive only; deprecate fields |
| GA | v1 | Strong | Additive only; never remove fields |
Conversion webhook required when:
- Multiple versions are served simultaneously
- A field's shape changed between versions
For simple field renames, x-kubernetes-conversion-strategy: None works.
Scope: Namespaced vs Cluster
Default to Namespaced. Cluster-scoped CRDs:
- Can't be RBAC-restricted by namespace
- Can't have
OwnerReferencesfrom namespaced parents - Are appropriate only for cluster-wide resources (
StorageClass-like things)
If your operator manages namespace-bound things (apps, databases, queues), use Namespaced.
Naming
- Group:
<domain>.<reverse-domain>— e.g.,apps.example.com. Don't use generic groups (com,io). - Kind: PascalCase, singular, descriptive —
MyApp,Database,Cache. AvoidMyAppResource(theResourcesuffix is implicit). - Plural: lowercase, plural —
myapps,databases,caches. - Short name: 2-3 letters; check for conflicts with built-in resources.
Validation tooling
kubectl apply --dry-run=server— validates against your CRDkubectl explain <kind>.<field>— shows what your schema documentscrd_validator.py— this skill's tool, structural rules
Documentation in the schema
Use the description field on every property. kubectl explain reads it:
properties:
replicas:
type: integer
minimum: 1
description: |
Number of replicas to run. Production deployments should use ≥3.
Increases above 100 require quota approval.
Anti-patterns
- Top-level
x-kubernetes-preserve-unknown-fields: true— defeats validation - No
scope:declared — defaults to namespaced but make intent explicit - No printer columns —
kubectl getshows onlyNAME AGE - Conditions written by hand (not via
SetStatusCondition) — easy to loselastTransitionTime - Status fields that duplicate spec — keep them separate
- Using
metadata.annotationsto encode operator state — use status fields - Single huge CRD with 50+ fields — split into multiple CRDs (e.g., MyApp + MyAppBackup + MyAppRestore)