8.21 Kubernetes Container Status Model

Kubernetes Container Status Model is the structured representation Kubernetes maintains for the current state of each container within a Pod, exposed through the Pod's status subresource and used by the kubelet, control plane components, and operators to reason about whether a container is running correctly, has failed, or is still starting up. This model captures not just a single state value but a rich set of fields describing the container's lifecycle state, restart history, and readiness, forming the basis for scheduling decisions, health monitoring, and troubleshooting.

Container State

Waiting

A container in the Waiting state has not yet started running and is not currently terminated. This state includes a reason field, such as ContainerCreating, ImagePullBackOff, or CrashLoopBackOff, along with an optional message providing further detail. This is often the state an operator inspects first when diagnosing a Pod that fails to become ready, since the reason field typically points directly at the underlying cause.

Running

A container in the Running state is currently executing without issues from the kubelet's perspective, with the state including a startedAt timestamp indicating when the container transitioned into this state. Being in the Running state does not by itself guarantee the application inside the container is functioning correctly, which is why readiness probes exist as a separate signal layered on top of this raw state.

Terminated

A container in the Terminated state has finished execution, either successfully or due to an error, and includes fields such as exitCode, reason, message, startedAt, and finishedAt. An exitCode of zero indicates a clean exit, while non-zero values indicate the process exited due to an error, a signal, or an explicit failure condition raised by the application.

Restart Count and History

restartCount

The restartCount field tracks how many times the container has been restarted by the kubelet, incrementing each time the container terminates and is subsequently restarted according to the Pod's restartPolicy. A consistently increasing restart count is one of the clearest indicators of an unstable workload and is commonly used as an alerting signal in cluster monitoring.

lastState

The lastState field preserves the state information from the container's previous termination, even after it has been restarted and moved into a new state. This allows an operator to inspect the exit code and reason for the most recent failure even while the container is currently running again, which is essential for diagnosing intermittent crashes that would otherwise be lost once the container restarts.

Readiness and Startup Signals

ready

The ready boolean field indicates whether the container has passed its configured readiness probe, if one is defined, or is otherwise considered ready by default. This field directly feeds into whether the Pod as a whole is marked ready and therefore whether it is included as an endpoint behind any Services that select it.

started

The started field indicates whether the container has passed its startup probe, if one is configured. Until this field becomes true, liveness and readiness probes are not executed against the container, preventing slow-starting applications from being prematurely killed or marked unready during a legitimately long initialization phase.

Image and Identification Fields

image and imageID

The image field records the image name as specified in the Pod spec, while imageID records the resolved, immutable identifier of the actual image that was pulled, typically including a digest. This distinction matters because a mutable tag such as latest in the image field can correspond to different underlying images over time, whereas imageID pins down exactly which image content was used.

containerID

The containerID field records the unique identifier assigned by the container runtime to the running container instance, prefixed with the runtime name, and is used internally to correlate the Kubernetes-level container status with the actual runtime-level container process.

Aggregation Into Pod Phase

Pod Phase Derivation

The overall Pod phase, such as Pending, Running, Succeeded, or Failed, is derived in part from the aggregate container status model of all containers within the Pod. For instance, a Pod only reaches the Running phase once at least one container is running, and only reaches Succeeded once all containers have terminated successfully.

Container Statuses Versus Init Container Statuses

The Pod status maintains separate lists for regular container statuses and init container statuses, since init containers follow a distinct lifecycle that must complete entirely before regular containers begin, and their individual status entries are preserved separately to allow tracking of each init container's own state and exit behavior.