api-design

First decide whether the change is a field, an action on an existing Ops kind, or a new kind, based on whether it has its own lifecycle and is watched or referenced. Then apply the standard marker set: subresource:status, printcolumns, typed enums, and observedGeneration in status.

Use the +k8s:immutable marker, which controller-gen turns into CEL validation rules. On an optional field it means immutable once set; on a required field it means immutable from creation. A doc comment saying immutable enforces nothing.

Create a new CRD only when something watches it or references it by name and it has its own lifecycle and status. A thing with no independent lifecycle belongs as a field or nested struct on its owner, since each CRD costs a controller, RBAC, and a chart entry.

Spec is the user's desired state and is never written by a controller; status is the controller's reconstructable record of progress, including phase, observedGeneration, and restart state. A field both parties set must be split into separate spec and status fields.

Removing or renaming a field, removing an enum value, narrowing validation, tightening a default, or changing a field's type or meaning are breaking. Adding optional fields, enum values, printcolumns, or status fields is safe.

Run the check-crds.py script with --changed to audit only the type files modified against HEAD, or --design to audit Go types in a design document's appendix. It reports errors like untyped phases and unenforced immutability, exiting non-zero so it can gate a change.