6.7 Kubernetes Manifest Status Handling

Kubernetes Manifest Status Handling is the set of practices and tooling behaviors surrounding the fact that a manifest, as an author-submitted artifact, should never contain a status section, and that any status information appearing in a manifest retrieved from a live cluster must be deliberately excluded before that manifest is reapplied, treated as a source, or committed to version control.

Why Status Should Never Be Authored

Status Is Not Expressible Intent

Since status represents observed, controller-reported state rather than desired configuration, it has no meaningful role in a manifest expressing intent; an author including a status block in a manifest is, at best, providing information the API server will ignore, and at worst, creating confusion about what the manifest is actually meant to declare.

The API Server's Handling of Submitted Status

For resources where status is exposed as a distinct subresource, a create or update request against the main resource endpoint that includes a status field typically has that field ignored entirely, since status subresource protection means only requests specifically targeting the /status endpoint can modify it, regardless of what appears in a request to the main endpoint.

The Problem of Capturing Live Objects as Manifests

Retrieved Objects Include Status

When an object is exported directly from a live cluster, such as through kubectl get -o yaml, the resulting document includes the full status block alongside spec and system-managed metadata, meaning this raw export is not itself a clean, reusable manifest without further editing.

Stripping Status Before Reuse

Tooling and manual workflows that turn a live object back into a reusable manifest need to explicitly strip status, along with system-managed metadata fields like resourceVersion and uid, to produce a manifest suitable for version control or reapplication elsewhere, a step some kubectl export-oriented commands and third-party tools automate.

Status Handling During Apply Operations

Server-Side Apply's Status Behavior

When using server-side apply, a field manager submitting to the main resource endpoint has no ability to affect status even if it were included in the submitted document, since server-side apply, like other subresource-protected operations, requires a request specifically targeted at the status subresource to modify observed state.

Controllers as the Only Legitimate Status Writers

In practice, the only manifests that legitimately interact with status at all are those submitted programmatically by controllers targeting the status subresource endpoint directly, a fundamentally different operation from a human or CI pipeline applying a configuration manifest through the main resource endpoint.

GitOps and Status Exclusion

Reconciliation Tools Ignoring Live Status

GitOps reconciliation tools that continuously compare a Git repository's manifests against live cluster state are designed to exclude status from their diffing logic entirely, since a mismatch in status, which is expected to differ from any static manifest by its very nature, should never be treated as configuration drift requiring correction.

Diffing Spec Versus Full Object

Careful diffing implementations in deployment tooling compare only the fields a manifest actually manages, generally within spec and select metadata fields, explicitly ignoring status and other system-managed fields, to avoid generating false-positive drift reports or attempting to overwrite status via what should be a spec-only reconciliation.

Practical Guidance for Manifest Authors

Treating Status as Read-Only Output

The most reliable mental model for manifest authors is to treat status purely as read-only output for inspection, using commands like kubectl describe or kubectl get -o jsonpath to view it, while never including it in any file destined to be committed, templated, or reapplied as a manifest.

Version Control Hygiene

Repositories storing manifests for GitOps or general infrastructure-as-code workflows benefit from linting or pre-commit checks that reject any committed manifest containing a status field, catching accidental inclusion, typically from a careless copy-paste of a live object export, before it becomes a source of confusion for later readers of the repository.