9.7 Kubernetes Container State Progression

Kubernetes Container State Progression is the sequence of transitions an individual container within a Pod passes through, moving between the Waiting, Running, and Terminated states as it is created, executes, potentially fails, and is potentially restarted. Unlike Pod phase, which summarizes the entire Pod, this progression operates at the level of a single container and can differ across containers within the same Pod, since each container follows its own independent execution path governed by its own process lifecycle.

Initial Waiting State

Entry Upon Creation

Every container begins in the Waiting state the moment it is registered by the kubelet, before its underlying process has actually started executing. During this period, the reason field commonly reports ContainerCreating, reflecting that image pulls, volume mounts, or init container completion are still in progress.

Waiting States That Signal Problems

If a container cannot progress past Waiting, the reason field shifts to values such as ImagePullBackOff, indicating repeated failures to retrieve the container image, or CrashLoopBackOff, indicating the container has started and failed repeatedly, with the kubelet now applying an increasing backoff delay before each subsequent restart attempt.

Transition Into Running

Successful Process Start

A container moves from Waiting into Running once the container runtime successfully starts its main process. This transition, recorded with a startedAt timestamp, reflects only that the process has begun executing, not that the application inside it has finished its own internal initialization or is functioning correctly.

postStart Hook Interaction

If a postStart lifecycle hook is defined, it executes concurrently with the container entering the Running state. A failure in this hook is treated as a container failure, which can cause the container to be killed and moved back toward Waiting as the kubelet attempts a restart, depending on the Pod's restart policy.

Transition Into Terminated

Normal and Abnormal Exit

A container moves from Running into Terminated when its main process exits, whether cleanly with an exit code of zero or abnormally with a non-zero exit code, a signal-induced termination, or an OOM kill triggered by exceeding its memory limit. The Terminated state records the exitCode, reason, and both startedAt and finishedAt timestamps.

preStop Hook Execution Before Termination

When termination is initiated deliberately, such as during Pod deletion, any configured preStop hook is executed before the termination signal is sent to the container's main process, meaning the container remains technically Running throughout the hook's execution and only transitions to Terminated once both the hook and the subsequent shutdown have completed.

Restart Cycle Back to Waiting

restartPolicy-Driven Re-Entry

If the Pod's restartPolicy permits it, a container that has transitioned to Terminated re-enters the Waiting state as the kubelet attempts to restart it, incrementing the restartCount field each time this cycle occurs, with the delay before each restart attempt growing according to an exponential backoff schedule capped at a maximum interval.

Preservation of Prior Termination Data

As a container restarts, its previous Terminated state is preserved separately in the lastState field, ensuring that the exit code and reason from the most recent failure remain visible even after the container has successfully transitioned back into Running, which is essential for diagnosing intermittent or cyclical failures.

Independence Across Containers Within a Pod

Divergent Progression Paths

Because each container tracks its own state progression independently, one container within a Pod may be steadily Running while another cycles repeatedly through Waiting, Running, and Terminated due to a persistent crash, illustrating why Pod-level phase alone cannot substitute for inspecting individual container statuses when diagnosing partial failures within a multi-container Pod.