kubernetes-crd-authorlisted

# 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 declarative