4.16 Kubernetes Pod Status Reporting

Kubernetes Pod Status Reporting is the process by which the kubelet observes the actual state of a pod's sandbox and containers on its node and synchronizes that observed state back to the pod object's status subresource in the API server, giving the rest of the cluster, including controllers, the scheduler, and human operators, an accurate, near-real-time view of what is actually happening with a pod's execution.

The Pod Status Object

Phase

Every pod status includes a coarse-grained phase field, one of Pending, Running, Succeeded, Failed, or Unknown, representing a high-level summary of where the pod is in its lifecycle, though the phase alone is not sufficient to determine detailed container-level health.

Conditions

Pod status carries its own conditions array, distinct from node conditions, including types such as PodScheduled, Initialized, ContainersReady, and Ready, each independently tracked and transitioned as the pod progresses through scheduling, initialization, and container startup.

Container Statuses

For each container in the pod, a containerStatuses entry reports the container's current state, one of Waiting, Running, or Terminated, along with restart count, image and image ID, and, for terminated containers, exit code and termination reason.

The Status Manager

Internal Buffering of Status Updates

The kubelet's status manager component receives status updates generated internally by other kubelet subsystems, such as the pod worker responsible for syncing a given pod, and buffers them before pushing updates to the API server, decoupling the rate of internal state changes from the rate of API writes.

Deduplication and Change Detection

Before issuing an API update, the status manager compares the newly computed status against the last status it successfully wrote, avoiding redundant API calls when nothing meaningful has actually changed, which reduces unnecessary load on the API server across a cluster with many pods.

Retry Behavior

If a status update to the API server fails, the status manager retries, since accurate status reporting is important for correct behavior of controllers that depend on it, such as ReplicaSet controllers deciding whether a replacement pod is needed.

Deriving Status from Runtime State

Polling the Container Runtime

The kubelet periodically queries the container runtime through CRI calls such as PodSandboxStatus and ListContainerStatuses to obtain the ground truth about sandbox and container state, which it then translates into the Kubernetes-level status representation.

PLEG-Driven Updates

Rather than polling every pod on every cycle, the kubelet's Pod Lifecycle Event Generator detects meaningful state transitions, such as a container starting or exiting, and triggers a targeted status resync for the affected pod, improving responsiveness without incurring the cost of constantly re-evaluating every pod on the node.

Probe Result Integration

Results from liveness, readiness, and startup probes feed directly into container and pod status: a failing readiness probe flips the ContainersReady and Ready conditions to False without necessarily changing the container's underlying Running state, since the container process itself may still be alive even though it is not yet ready to serve traffic.

Status Propagation to Higher-Level Objects

Endpoint and Service Membership

A pod's Ready condition directly determines whether it is included as an active backend in the EndpointSlice objects associated with any Service selecting it, meaning pod status reporting has a direct and immediate effect on live traffic routing decisions made by kube-proxy and other Service implementations.

Controller Reconciliation

Controllers such as Deployments, ReplicaSets, and Jobs watch pod status to determine whether a pod has failed, succeeded, or is still progressing, using this information to decide whether to create replacement pods, mark a Job as complete, or roll back a Deployment that is producing failing pods.

Termination and Deletion Status

Graceful Termination Reporting

When a pod is being deleted, its status reflects a deletionTimestamp alongside the pod's ongoing container statuses, allowing observers to distinguish a pod that is in the process of gracefully terminating from one that is simply still starting up or running normally.

Reason and Message Fields

Failure and waiting states are accompanied by reason and message fields, such as CrashLoopBackOff, ImagePullBackOff, or OOMKilled, giving operators immediately actionable diagnostic information without needing to inspect raw logs or events first.

Interaction with Events

Complementary Event Stream

Alongside status updates, the kubelet emits Kubernetes Event objects describing specific occurrences, such as image pull failures or probe failures, which provide a time-ordered history of what led to the current status, complementing the point-in-time snapshot that the status object itself represents.

Status as the Queryable Summary

While events provide history, the pod status object remains the canonical, queryable summary of current pod state, which is why tools like kubectl get pods and kubectl describe pod both rely heavily on it as their primary data source.