kubernetes-crd-author

Authoring Kubernetes CRDs and controllers

A CRD is a published API. Once someone has stored an object in it you cannot change your mind cheaply, so the schema and the versioning decision matter more than the controller does. Design the API first, generate everything else.

Preconditions

• This is Go and Kubernetes work, usually in a different repository from the Backstage portal. Confirm which repository you are in before writing anything; a controller does not belong in a Backstage monorepo.
• Toolchain versions read from the repository, not assumed: PROJECT file for the kubebuilder layout version, Makefile for the pinned controller-gen version, go.mod for sigs.k8s.io/controller-runtime. These three move independently and a mismatch between controller-gen and the runtime is a common source of "generation produces something that will not compile".
• The target cluster's Kubernetes minor, because CRD schema features (x-kubernetes-validations CEL rules, in particular) gate on it.
• Whether this API is new or already deployed. Everything about versioning and field changes below turns on that answer, and it is not recoverable later.
• Applying a CRD or an operator to a shared cluster is external mutation: prepare the manifests, stop, and return the exact kubectl or make command for authorization.

Procedure

1. Decide whether a CRD is the right shape at all. A CRD earns its place when something must be declaratively reconciled toward a desired state and observed by others. Configuration nobody reconciles is a ConfigMap. A one-off action is a Job. An operator that only templates YAML is a chart with extra failure modes.
2. Design the API before scaffolding. Group (<team>.<company>.com), Kind, and a spec/status split where spec is exclusively user intent and status is exclusively controller observation. Anything a user must set to make the object valid belongs in spec; anything the controller computes belongs in status and must survive being recomputed from scratch.
3. Start at v1alpha1. It signals instability and lets you break the schema without a conversion webhook. Promoting later is cheap; starting at v1 and discovering the schema is wrong is not.
4. Scaffold rather than hand-roll. kubebuilder init --domain <company.com> --repo <module path> then kubebuilder create api --group <group> --version v1alpha1 --kind <Kind>. It wires the scheme registration, the manager, RBAC markers, the Makefile targets and a test harness that are tedious and easy to get subtly wrong by hand.
5. Write the types with markers, not prose. On the root type, +kubebuilder:object:root=true and +kubebuilder:subresource:status. On fields, +kubebuilder:validation:* for bounds, enums, patterns and required, +kubebuilder:default= for defaults, and +optional for genuinely optional fields. Markers are the schema; validation written only in the controller is validation that runs after the object was already accepted. Read the marker set from the pinned controller-gen version — markers are added between minors.
6. Add printer columns. +kubebuilder:printcolumn:name=...,type=...,JSONPath=... for the two or three fields an operator would want from kubectl get. Without them the CR prints only name and age, which makes it useless at the terminal and is the most common complaint about a first CRD.
7. Model status as conditions. A Ready condition of the standard metav1.Condition shape, with observedGeneration, is what every other tool knows how to read. Ad-hoc status booleans are invisible to kubectl wait and to anything watching.
8. Generate, never edit generated files. make manifests generate produces the CRD YAML under config/crd/bases and the deepcopy functions. A hand-edited CRD is silently reverted on the next generation, and the symptom arrives later as a schema that does not match the types.
9. Write the reconcile loop to be idempotent and level-triggered. Reconcile reads current state and moves toward spec; it must produce the same result called once or twenty times, and must never depend on having seen the previous event. Return a requeue rather than sleeping. Set owner references so garbage collection cleans up what you created.
10. Add a finalizer only if there is external state to clean up. A finalizer with a bug makes objects undeletable, which is a worse failure than leaking the resource it was protecting. If you add one, make its removal path unconditional on the external system being reachable.
11. Keep RBAC markers next to the code that needs them. +kubebuilder:rbac:groups=... above the reconciler, then make manifests regenerates the role. Hand-written role YAML drifts from what the controller actually calls.
12. Test the reconcile loop with envtest, which runs a real API server, so schema validation and defaulting are exercised rather than mocked. Cover: the object is created and reaches Ready; a mutated child is corrected; deletion cleans up. make test runs it.
13. Plan the next version before you need it. Adding an optional field with a default is safe. Removing a field, tightening validation, or changing a type is breaking and needs a new version plus a conversion webhook, with exactly one storage version. Decide the hub-and-spoke conversion shape when you add the second version, not the third.
14. Then surface it in the portal. A CRD is only useful to a platform team if people can see it — see backstage-kubernetes for declaring it under kubernetes.customResources and the RBAC that needs.