Kubernetes Manifest Status Handling

Kubernetes Manifest Status Handling is the set of practical conventions and tooling behaviors surrounding the fact that a manifest, despite representing the full shape of an object's schema, is never meant to author the status field, and that any status content appearing in a manifest — whether written accidentally by a human or included in output copied from a live object — is silently ignored or explicitly stripped by the tools and API paths that process it. This gap between what a manifest can theoretically contain and what it should ever actually specify is a direct consequence of the object model's spec/status separation, made concrete in day-to-day manifest authoring and tooling behavior.

Why Status Never Belongs in an Authored Manifest

Status Is Not Declarable

Status represents a controller's observation of reality, not something a client can bring into existence by writing it down; a manifest declaring status.readyReplicas: 3 for a Deployment has no effect on whether three replicas are actually ready, since that value is entirely overwritten by whatever the Deployment controller next observes and reports, regardless of what a submitted manifest said.

The status Subresource Bypasses Main-Path Writes

Even where the API technically accepts a full object body including a status field on a create request, most built-in types route status writes through the dedicated status subresource, which ordinary create and update requests against the main resource path do not touch, meaning any status content in a manifest applied through the standard path is effectively discarded rather than persisted.

Tooling Behavior Around Manifest Status Content

kubectl apply and Status Fields

kubectl apply and similar declarative clients do not submit status content from a manifest as part of a normal apply operation; even if a manifest file happens to contain a status block (commonly because it was generated by copying kubectl get -o yaml output from a live object), that block is not sent to the status subresource and has no bearing on the resulting object's actual status.

Exported Manifests and Status Pollution

When exporting a live object's configuration for reuse as a manifest — via kubectl get -o yaml or similar — the output includes the object's current status, system-managed metadata, and other server-populated fields, which is why such exports are generally considered a starting point requiring cleanup rather than a manifest ready for direct reapplication; status, resourceVersion, uid, and similar fields are conventionally stripped before the result is treated as a reusable manifest.

Status Fields in CustomResourceDefinitions

Enabling the status Subresource

A CustomResourceDefinition must explicitly opt into having a status subresource; without that configuration, a custom resource has no special status/spec write separation at the API level at all, and any status-like field a controller wants to report must instead be treated as an ordinary part of the object updated through the main resource path, without the isolation the subresource provides.

Consequences of Omitting the Status Subresource

Custom resources that skip the status subresource lose the RBAC-enforceable boundary between who can declare desired state and who can report observed state, meaning any client with write access to the object at all can, intentionally or not, overwrite status-like fields that a controller was relying on to reflect its own authoritative observations.

Observing Status Without Attempting to Set It

Reading Status for Operational Visibility

Manifest authors and operators interact with status purely as a read path — through kubectl get, kubectl describe, or watching an object — using it to verify that a declared spec has actually been realized, rather than as something to include in the next version of a manifest intended for reapplication, keeping the write path (manifests declaring spec) and the read path (status inspection) cleanly separated in normal operational practice.