Kubernetes Status Definition

Kubernetes Status Definition is the precise characterization of the status field present on most Kubernetes objects: a system-populated record of an object's observed, actual condition, formally distinct from and never authoritative over the user-declared intent carried in spec. Where spec answers what should be true, status answers what a controller has determined is currently true, and the relationship between the two is the mechanism through which Kubernetes implements its declarative, self-healing behavior.

Formal Role of Status

Written by Controllers, Not Users

By convention and API server enforcement for most resource types, status is written exclusively by the controller responsible for a given object, typically through a dedicated status subresource, and is not intended to be set directly by the user who created the object's spec. A user proposes; the responsible controller observes and reports.

The Status Subresource

Many resource kinds expose status as a distinct API subresource, updated through a separate endpoint from the rest of the object. This separation allows RBAC to grant permission to update an object's spec without granting permission to update its status, and vice versa, formally enforcing the asymmetry between who declares intent and who reports observed state.

kubectl get --raw /apis/apps/v1/namespaces/codartium-team/deployments/codartium-api/status

Common Structural Patterns

Conditions

A widely adopted convention represents status as a list of conditions, each identifying a specific aspect of an object's state, a status of True, False, or Unknown, and a timestamp and reason explaining the current value, allowing status to be extended with new dimensions of observed state without altering the top-level schema.

status:
  conditions:
    - type: Available
      status: "True"
      lastTransitionTime: "2024-05-12T09:14:03Z"
      reason: MinimumReplicasAvailable
    - type: Progressing
      status: "False"
      lastTransitionTime: "2024-05-12T09:15:41Z"
      reason: NewReplicaSetAvailable

Observed Generation

Many kinds include an observedGeneration field within status, recording the value of metadata.generation that was last successfully reconciled, allowing a client to determine whether the reported status reflects the most recently submitted spec or a stale, earlier version still being processed.

metadata:
  generation: 7
status:
  observedGeneration: 7

Summary Fields

Beyond conditions, many kinds report simple summary fields directly, such as a Deployment's status.readyReplicas or a Node's status.capacity, giving clients a quick, structured answer to common questions without requiring interpretation of a full conditions list.

status:
  replicas: 4
  readyReplicas: 4
  availableReplicas: 4
  updatedReplicas: 4

Status as the Input to Further Reconciliation

Chained Observation

Because status reflects a controller's own observation, other controllers, or the same controller on its next reconciliation pass, treat it as an input alongside the live state of the systems it governs, forming a chain in which one controller's output status can influence another controller's subsequent decisions, such as a HorizontalPodAutoscaler reading a Deployment's status to inform scaling decisions.

Status Does Not Drive Desired State

Formally, status never overwrites or influences spec; the flow of authority runs strictly from spec to status, never the reverse, which is what preserves the guarantee that a user's declared intent remains stable and recoverable even after arbitrary sequences of observed state changes.

kubectl get deployment codartium-api -o jsonpath='{.status.conditions[?(@.type=="Available")].status}'
kubectl describe deployment codartium-api

Distinguishing Status from Events

Status represents an object's current, standing condition, continuously overwritten as new observations arrive, whereas Events represent discrete, timestamped occurrences retained only briefly; the two are formally distinct mechanisms serving different purposes, status for "what is true now," Events for "what happened recently," and neither substitutes for the other in a complete accounting of an object's history and present condition.