1.8 Kubernetes Status Definition
Kubernetes Status Definition explains how the system tracks and reports cluster resource states for reliable containerized operations.
Kubernetes Status Definition is the precise characterization of the status field carried by Kubernetes objects, defined as the record of an object's last observed actual state, written exclusively by controllers rather than by the clients that create or update the object's spec, and used to reflect reality rather than to declare intent.
Status as Observed, Not Desired
A One-Way Report
Status is defined by its direction of information flow: it flows from the system's observation of reality back toward the API, whereas spec flows from client intent into the system. This directionality is what separates status from every other part of an object's definition.
Written by Controllers, Not Clients
By convention and, in many cases, by API server enforcement through a dedicated status subresource, only controllers are expected to write to an object's status, while ordinary clients are expected to write only to its spec, preserving the clean separation between intent and observation.
Common Structural Patterns in Status
Conditions
Many object types express part of their status as a list of conditions, each with a type, a boolean or ternary value, and a reason, representing distinct aspects of the object's health or progress, such as whether a Pod is ready or whether a Deployment's rollout has completed.
Phase and Summary Fields
Some object types include a coarse summary field, such as a Pod's phase, intended to give a quick, high-level read of overall status without requiring inspection of every individual condition.
Why Status Must Be Treated as Advisory
Always Potentially Stale
Because status reflects the last observation made by a controller, and observations happen periodically rather than instantaneously, status is inherently a snapshot that may already be out of date by the time it is read, a property that is part of its very definition rather than an implementation flaw.
Not a Command Channel
Status fields are never intended to be written by clients to influence system behavior; doing so is inconsistent with the definition of status and is typically rejected or ignored, since clients are expected to express intent only through an object's spec.
Distinguishing Status from Metadata
Not Identity, But Condition
Status should not be confused with metadata: metadata identifies what an object is, while status describes the condition that object is currently observed to be in, a distinction that matters when reasoning about which part of an object changes for which reason.