What changes about a Kubernetes custom resource when you enable `subresources: {status: {}}` on its CustomResourceDefinition, and why do controllers want it?

## The two-endpoint model By default a custom resource is a single document at one endpoint: whatever a client PUTs replaces the whole object, `status` included. Adding ```yaml subresources: status: {} ``` to a version entry in the CRD creates a second endpoint, `.../<name>/status`, and changes how both behave: - **Main endpoint** (create, update, patch, apply): the `status` field of the submitted object is discarded. On create, `status` is dropped entirely; on update, the stored status is preserved. - **Status endpoint**: everything except `status` is discarded — spec and most metadata changes submitted there are ignored. This is not a convenience; it is the mechanism that makes the declarative contract safe. ## Why the split matters Kubernetes objects follow a strict division: **`spec` is desired state written by the user**, **`status` is observed state written by the controller**. Without the subresource, that division is only a convention, and it breaks in ordinary use: - A user runs `kubectl apply -f db.yaml` from a manifest with no status. Without the subresource, the apply erases the conditions and observed fields the controller just wrote; the controller writes them back; and every apply causes a spurious update event. - A buggy controller doing a full-object update to report status can silently overwrite a spec change made a moment earlier — a lost-update bug that is very hard to see. With the subresource, both classes of accident are impossible at the API level rather than by discipline. ## generation and observedGeneration A second, easily missed effect: with the status subresource enabled, the API server increments **`metadata.generation`** only when the **spec** changes. Status writes do not bump it. That makes the standard reconciliation-progress idiom work: ```yaml status: observedGeneration: 7 conditions: - type: Ready status: "True" observedGeneration: 7 lastTransitionTime: "2026-08-12T10:04:11Z" reason: Provisioned message: Instance is serving ``` The controller copies `metadata.generation` into `status.observedGeneration` when it finishes reconciling. Anyone — a human, a CI job, a progressive-delivery tool — can then distinguish "the API accepted my change" from "the controller has acted on my change" by comparing `metadata.generation` with `status.observedGeneration`. Without the subresource, generation churns on every status write and the comparison is meaningless. Conditions themselves should follow the standard shape (`type`, `status` of True/False/Unknown, `reason`, `message`, `lastTransitionTime`, `observedGeneration`), because that is what `kubectl wait --for=condition=Ready`, `kubectl describe` and most tooling understand. ## RBAC separation The subresource is a distinct RBAC target named `<plural>/status`. So you can write: - controller ServiceAccount: `get, list, watch` on `databases` and `update, patch` on `databases/status` — it can report, but cannot rewrite users' intent; - application teams: full verbs on `databases` and nothing on `databases/status` — they declare intent but cannot fake readiness. That is a meaningful least-privilege boundary, and it is only available once the subresource exists. ## The scale subresource, briefly The sibling `subresources.scale` maps three JSONPaths (`specReplicasPath`, `statusReplicasPath`, optional `labelSelectorPath`) onto a `/scale` endpoint. Once present, `kubectl scale` works on your custom resource and — importantly — a HorizontalPodAutoscaler can target it, because the HPA drives whatever exposes `/scale`. Custom workload kinds that own replicas should declare it. ## Practical consequences for controller code - Two API calls: `Update(obj)` for spec/metadata and `Status().Update(obj)` (controller-runtime) or `UpdateStatus` (client-go) for status. Mixing them up is the most common reason "my status never persists" — the write went to the main endpoint and was dropped. - Server-side apply has a distinct field manager for status; use `Status().Patch(..., client.Apply, ...)` with its own owner name. - Conflicts are still possible: status writes use the same `resourceVersion` optimistic concurrency, so controllers must handle 409 by re-reading and retrying. - Status should be **reconstructible**. Because it is observed state, a controller must be able to rebuild it from the world; never store the only copy of something important there. ## Enabling it later Adding the subresource to an existing CRD is safe and takes effect immediately for all objects, but any client that was writing status through the main endpoint silently stops working — the write is accepted and dropped, with no error. Migrate controllers first, then enable it, and grep for status writes in tooling that touches the resource.