Kubernetes Object Status Observation

Kubernetes Object Status Observation is the practice of reading and interpreting the status subresource that nearly every Kubernetes API object maintains, reflecting the object's current, controller-reported state as distinct from its user-declared spec. Because Kubernetes' reconciliation model continuously drives actual state toward desired state, status observation is the primary way to determine whether that convergence has succeeded, is still in progress, or has stalled.

The Spec-Status Pattern

Declared Intent Versus Observed Reality

Every standard Kubernetes resource separates spec (what the user or a higher-level controller wants) from status (what the responsible controller currently observes to be true), and this separation is fundamental to how Kubernetes reconciliation works — a controller's job is precisely to drive status toward matching spec, never the reverse.

spec:
  replicas: 5
status:
  replicas: 5
  readyReplicas: 4
  availableReplicas: 4

Status Is Controller-Owned

Only the controller responsible for a resource type writes to its status subresource (enforced by RBAC separating the main resource and its status subresource as distinct API endpoints); a user editing status directly, where permitted, has no lasting effect since the controller will overwrite it on its next reconciliation pass.

Common Status Fields Across Workload Types

Replica Counts

Deployment, ReplicaSet, and StatefulSet status all report replicas (total), readyReplicas (passing readiness checks), availableReplicas (ready for a minimum stability duration), and updatedReplicas (running the latest template version), together giving a precise picture of rollout progress during an update.

kubectl get deployment api-service -o jsonpath='{.status}'

Pod Phase and Container Status

A Pod's status includes a phase (Pending, Running, Succeeded, Failed, Unknown) and per-container status detailing the container's current state (Waiting, Running, Terminated), restart count, and the specific reason for any non-running state.

kubectl get pod api-service-7d4f9 -o jsonpath='{.status.containerStatuses}'

Status Conditions

The Conditions Array Pattern

Beyond simple fields, many resources express status through a conditions array, each entry providing a type (a specific aspect being reported on), a status (True, False, Unknown), a reason, and a human-readable message, allowing a resource to report on multiple independent aspects of its health simultaneously.

status:
  conditions:
  - type: Available
    status: "True"
    reason: MinimumReplicasAvailable
  - type: Progressing
    status: "False"
    reason: ProgressDeadlineExceeded
    message: "ReplicaSet has timed out progressing"

Reading Conditions for Diagnosis

A Progressing condition set to False with a ProgressDeadlineExceeded reason indicates a rollout has stalled — a distinct and more actionable signal than simply observing that readyReplicas has not reached the desired count, since the condition explains why the reconciliation is stuck rather than just that it has not yet succeeded.

Observing Status Programmatically and Interactively

kubectl describe as a Human-Readable View

kubectl describe renders an object's status, conditions, and related events together in a single human-readable summary, making it the standard first step for interactively diagnosing why a resource is not behaving as expected.

kubectl describe deployment api-service

Watching Status Changes Over Time

kubectl get --watch or kubectl rollout status stream status changes as they occur, useful for observing a rollout or scaling operation in progress rather than only inspecting a single point-in-time snapshot.

kubectl rollout status deployment/api-service

Programmatic Consumption for Automation

Automation and custom controllers read status fields and conditions the same way, using them to make downstream decisions (whether to proceed with a dependent deployment step, for instance) — designing custom resources with a clear, well-structured status and conditions model makes them properly interoperable with the broader Kubernetes ecosystem's expectations.

Limitations of Status Observation

Status Reflects the Controller's Last Reconciliation, Not Real-Time Truth

Because status is updated by a controller's reconciliation loop rather than continuously streamed, there is always some lag between actual state and reported status; a resource's true condition can change between reconciliation passes without status yet reflecting it, particularly under high controller load or during a controller restart.