Kubernetes Container Status Model

Kubernetes Container Status Model is the structured representation the kubelet and API server maintain to describe the current and historical execution state of every container within a Pod. This model is exposed through status.containerStatuses (and the analogous initContainerStatuses and ephemeralContainerStatuses fields) on the Pod object, and it captures not only whether a container is running, but its readiness, restart history, exit conditions, and the specific image digest that was actually pulled and executed.

The Three Container States

Waiting

A container in the Waiting state has not yet begun running and is not terminated. Common reasons surfaced in state.waiting.reason include ContainerCreating, ImagePullBackOff, and CrashLoopBackOff, each paired with a human-readable message describing the underlying cause.

Running

A container in the Running state is currently executing. The state.running.startedAt timestamp records when the container transitioned into this state, which is used by liveness and startup probes to compute elapsed uptime.

Terminated

A container in the Terminated state has stopped, either successfully or due to failure. This state records exitCode, reason (such as Completed, Error, or OOMKilled), startedAt, finishedAt, and optionally signal if the process was killed by a Unix signal.

status:
  containerStatuses:
    - name: app
      state:
        terminated:
          exitCode: 137
          reason: OOMKilled
          startedAt: "2026-07-18T09:12:03Z"
          finishedAt: "2026-07-18T09:14:51Z"
      lastState:
        terminated:
          exitCode: 0
          reason: Completed
      restartCount: 3
      ready: false

Readiness Versus Running

The ready Field

The boolean ready field is distinct from the Running state. A container can be Running while ready is false if its readiness probe has not yet succeeded, which prevents the Pod from being added to Service endpoints even though its process is alive.

restartCount

restartCount increments each time the kubelet restarts a container under the Pod's restartPolicy. A rapidly increasing count combined with short intervals between terminations is the signal that triggers the CrashLoopBackOff waiting reason and an exponential backoff delay before the next restart attempt.

Image Resolution Fields

image and imageID

The status model separates the requested image reference (as written in the PodSpec, which may be a mutable tag) from the resolved imageID, a content-addressable digest that uniquely identifies the exact image bytes that were pulled onto the node.

kubectl get pod runtime-status-example -o jsonpath='{.status.containerStatuses[0].imageID}'

This distinction matters for auditability: two Pods referencing the same tag can still be running different digests if the tag was repointed between pulls.

Container ID and Runtime Linkage

containerID

The containerID field links the Kubernetes-level status back to the underlying container runtime (containerd, CRI-O), formatted as <runtime>://<id>. This identifier is what the kubelet uses when issuing exec, log retrieval, or termination calls through the Container Runtime Interface.

Probe-Driven Transitions

Startup, Liveness, and Readiness Probes

Three probe types influence the status model independently:

• A startup probe delays liveness and readiness checks until an application has finished initializing.
• A liveness probe failure causes the kubelet to kill and restart the container, incrementing restartCount.
• A readiness probe failure only flips ready to false, without restarting the container.

containers:
  - name: app
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
      periodSeconds: 10
      failureThreshold: 3
    readinessProbe:
      httpGet:
        path: /ready
        port: 8080
      periodSeconds: 5

Status Aggregation to Pod Phase

The Pod's overall status.phase is derived from the aggregate of its container statuses: a Pod remains Pending until every container reaches Running or Terminated with success, transitions to Running once all containers have started, and moves to Succeeded or Failed based on the terminal exit codes recorded in each container's terminated state.