8.22 Kubernetes Pod Status Model

Kubernetes Pod Status Model is the structured set of fields Kubernetes maintains to describe the current observed condition of a Pod as a whole, distinct from the Pod's desired specification. This status is continuously updated by the kubelet and control plane components as the Pod progresses through its lifecycle, and it serves as the primary interface through which controllers, operators, and monitoring systems determine whether a Pod is functioning as intended.

Pod Phase

The Five Phase Values

The phase field summarizes the Pod's overall position in its lifecycle using one of five values: Pending, Running, Succeeded, Failed, or Unknown. Pending indicates the Pod has been accepted by the cluster but one or more of its containers is not yet running, often because images are still being pulled or the Pod is awaiting scheduling. Running indicates the Pod has been bound to a node and at least one container is executing.

Terminal Phases

Succeeded indicates all containers in the Pod have terminated successfully and will not be restarted, a phase typically associated with Jobs rather than long-running workloads. Failed indicates all containers have terminated and at least one terminated in failure. Unknown indicates the Pod's state could not be determined, commonly due to a communication failure with the node on which the Pod resides.

Phase Limitations

The phase field alone is a coarse-grained summary and does not by itself indicate whether the Pod is ready to serve traffic, which is why the status model includes additional, more granular fields such as conditions and per-container statuses that must be consulted for a complete picture of Pod health.

Pod Conditions

Standard Condition Types

The conditions field is a list of condition objects, each describing a specific aspect of the Pod's state, including PodScheduled, which indicates whether the Pod has been assigned to a node, Initialized, which indicates whether all init containers have completed successfully, ContainersReady, which indicates whether all containers report as ready, and Ready, which indicates the Pod as a whole is able to serve requests.

Condition Structure

Each condition includes a status field of True, False, or Unknown, along with lastProbeTime, lastTransitionTime, reason, and message fields. This structure allows tooling to determine not only the current state of a given aspect of the Pod but also when that state last changed and why, which is essential for diagnosing transient versus persistent issues.

DisruptionTarget Condition

Kubernetes also surfaces a DisruptionTarget condition that is set when a Pod has been selected for eviction due to a voluntary disruption, such as node draining, allowing controllers such as the Job controller to distinguish disruption-caused failures from application-level failures when deciding whether to count the failure against retry limits.

Host and Network Assignment

hostIP and podIP

The hostIP field records the IP address of the node the Pod has been scheduled onto, while podIP records the Pod's own assigned IP address within the cluster network. The podIPs field additionally supports dual-stack clusters by listing both IPv4 and IPv6 addresses when applicable.

nominatedNodeName

The nominatedNodeName field is set by the scheduler when it has tentatively identified a node for the Pod, often after triggering preemption of lower-priority Pods, providing visibility into scheduling decisions that are in progress but not yet finalized.

Quality of Service Class

qosClass Field

The qosClass field records the Quality of Service class Kubernetes has assigned to the Pod, one of Guaranteed, Burstable, or BestEffort, determined at admission time based on the relationship between the requests and limits defined across the Pod's containers. This classification directly influences the order in which the kubelet reclaims resources or evicts Pods under node pressure.

Timestamps and Lifecycle Markers

startTime

The startTime field records the timestamp at which the kubelet first acknowledged the Pod, marking the beginning of its observed lifecycle, and is distinct from the point at which individual containers within the Pod actually begin running.

Container and InitContainer Status Lists

The Pod status embeds the containerStatuses and initContainerStatuses lists, each entry following the Container Status Model, allowing the aggregate Pod-level phase and conditions to be derived from and cross-referenced against the individual state of every container within it.

Message and Reason Fields

Top-Level message and reason

When the Pod as a whole cannot proceed normally, such as when it cannot be scheduled, the status includes top-level message and reason fields providing human-readable and machine-readable explanations respectively, which are frequently the first fields inspected when triaging a Pod stuck outside the Running phase.