5.11 Kubernetes Spec and Status Model

Kubernetes Spec and Status Model is the architectural convention at the heart of the entire control loop paradigm, dividing every reconciled object into a spec section expressing desired state authored by a user or higher-level controller, and a status section expressing observed state authored exclusively by the controller responsible for reconciling that object, establishing a strict, one-directional flow of intent that every controller in the ecosystem is built around.

The Core Principle of Separation

Intent Versus Observation

spec answers the question of what should be true, while status answers the question of what is actually true as last observed by the controller responsible for that object; this separation exists so that the party expressing intent and the party reporting outcome never write to the same location, avoiding the ambiguity of a single field trying to serve both purposes.

Directionality of Writes

In the idealized model, users and higher-level controllers only ever write to spec, and the object's own controller only ever writes to status, a discipline that, when followed consistently, prevents feedback loops where a controller might accidentally treat its own status write as a new desired state change requiring further action.

The Reconciliation Loop in Practice

Watching for Spec Changes

A controller watches for changes to objects it is responsible for, and when it observes a difference between the current spec and what the corresponding real-world or dependent-object state reflects, it performs whatever actions are necessary to bring reality into alignment with the newly declared spec.

Writing Back Observed Outcomes

After acting, the controller updates status to reflect what it actually achieved or observed, which might match the desired spec exactly, or might reflect a partial or failed state if the desired state could not yet be fully realized, such as a Deployment reporting fewer readyReplicas than the replicas count requested in its spec.

Convergence, Not Instant Transition

Because reconciliation is a loop rather than a single transaction, status commonly lags behind spec during a transition period; a client updating an object's spec should not expect status to reflect the new desired state immediately, but rather converge to it as the controller processes the change over subsequent reconciliation cycles.

observedGeneration as a Convergence Signal

Correlating Status to a Specific Spec Version

Many status structures include an observedGeneration field, which a controller sets to the value of metadata.generation that was current at the time it last processed the object, allowing a client to determine whether the status they are viewing reflects the very latest spec change or an older one the controller has not yet caught up to.

Detecting Staleness

Comparing status.observedGeneration against the current metadata.generation lets automated tooling and human operators distinguish between a controller that is still catching up to a recent change versus a controller that has already processed the latest change and is reporting a genuinely converged, or genuinely failed, outcome.

Conditions as a Status Sub-Pattern

The Conditions Array Convention

A widely adopted convention within status is a conditions array, each entry specifying a condition type, a status of True, False, or Unknown, and typically a reason, message, and lastTransitionTime, giving structured, extensible detail beyond a single flat status field.

Why Conditions Scale Better Than Flat Fields

Because conditions are an array of independently evolving entries rather than a fixed set of top-level fields, new condition types can be introduced by a controller over time without requiring a schema change, and clients can select the specific conditions relevant to their concerns without needing to understand the full status structure.

Status as a Protected Subresource

Separate Update Permissions

Because status carries authoritative observed state, most built-in resources expose status as a distinct API subresource with its own update endpoint, allowing RBAC policy to grant a controller permission to update status without granting it permission to modify spec, and vice versa for clients that should only express intent.

Preventing Status Spoofing

This subresource separation prevents a workload's own application code, or an unrelated actor with only spec-level write access, from fabricating a false status, which is important for any automation, such as autoscalers or rollout gating logic, that trusts status as ground truth.

Custom Resources and the Same Convention

Voluntary Adoption by CRD Authors

Custom Resource Definitions are not required to follow the spec-and-status pattern, but the overwhelming majority of well-designed custom resources do, since doing so allows them to integrate naturally with generic tooling, RBAC subresource conventions, and operator patterns that the rest of the ecosystem already expects.