✦ For everyone, free.

Practical knowledge for real and everyday life

Home

Kubernetes Pod Lifecycle and Health

Understanding how Kubernetes manages pod states and ensures application health through lifecycle stages and readiness checks.

Kubernetes Pod Lifecycle and Health covers the sequence of states a Pod passes through from creation to termination, and the mechanisms Kubernetes uses to determine whether a Pod's containers are functioning correctly at each stage. Together, lifecycle tracking and health checking allow the platform to make automated decisions, restarting failed containers, withholding traffic from unready ones, and replacing Pods that can no longer be recovered, without requiring manual intervention.

Pod Phases

The Phase Field

A Pod's status.phase summarizes its coarse-grained state at a point in time:

  • Pending: The Pod has been accepted by the cluster but one or more of its containers is not yet running, commonly because it is waiting to be scheduled or its container images are still being pulled.
  • Running: The Pod has been bound to a node and at least one container is running, starting, or restarting.
  • Succeeded: All containers have terminated successfully and will not be restarted.
  • Failed: All containers have terminated, and at least one terminated in failure.
  • Unknown: The state of the Pod could not be obtained, typically due to a communication error with the node hosting it.

Container States

Within a Pod, each container independently tracks one of three states: Waiting, before it begins running, often while its image is being pulled; Running, once its process has started; and Terminated, once it has exited, along with an exit code and reason.

Waiting → Running → Terminated

Conditions

Pod Conditions

In addition to phase, a Pod reports a set of conditions, each with a status of True, False, or Unknown, providing finer-grained detail about its readiness:

  • PodScheduled: Indicates the Pod has been assigned to a node.
  • Initialized: Indicates all init containers have completed successfully.
  • ContainersReady: Indicates all containers in the Pod report ready.
  • Ready: Indicates the Pod is able to serve requests and should be added to matching Service endpoints.
kubectl get pod codartium-app-abc123 -o jsonpath='{.status.conditions}'

Health Probes

Liveness Probes

A liveness probe determines whether a container is still functioning correctly. If a liveness probe fails repeatedly, the kubelet kills and restarts the container according to its restart policy, allowing recovery from conditions such as deadlocks that a process cannot resolve on its own.

Readiness Probes

A readiness probe determines whether a container is currently able to serve traffic. Unlike a failed liveness probe, a failed readiness probe does not restart the container; instead, the Pod is removed from the set of endpoints backing any Service that selects it, until the probe succeeds again.

Startup Probes

A startup probe is used for containers with a slow initialization sequence. While a startup probe is defined and has not yet succeeded, liveness and readiness probes are disabled, preventing a slow-starting container from being killed prematurely by a liveness probe timeout.

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 15
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  periodSeconds: 5
startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  failureThreshold: 30
  periodSeconds: 2

Probe Mechanisms

Probes can be implemented as an HTTP GET request expecting a success status code, a TCP socket check confirming a port accepts connections, an executed command inside the container checked for a zero exit code, or, in more recent versions, a gRPC health check call.

Termination Lifecycle

Graceful Shutdown

When a Pod is deleted, the kubelet sends a SIGTERM signal to each container's main process and starts a termination grace period, during which the container is expected to shut down cleanly, finishing in-flight requests and releasing resources. If the container has not exited once the grace period elapses, the kubelet sends SIGKILL to force termination.

PreStop Hooks

A preStop lifecycle hook can be configured to run before SIGTERM is sent, commonly used to allow a Pod to deregister itself from external systems or drain connections before shutdown begins.

lifecycle:
  preStop:
    exec:
      command: ["sh", "-c", "sleep 5"]
terminationGracePeriodSeconds: 30

Removal from Service Endpoints

When a Pod is marked for deletion, it is simultaneously removed from the Endpoints of any Service that selects it, so that new traffic stops being routed to it while its containers are still completing their graceful shutdown sequence.

Restart Policy and Backoff

restartPolicy

The Pod-level restartPolicy field, Always, OnFailure, or Never, determines whether the kubelet restarts a container after it exits, and applies uniformly to every container in the Pod.

Exponential Backoff

When a container is repeatedly restarted due to failures, the kubelet applies an exponentially increasing delay between restart attempts, capped at a maximum interval, to avoid overwhelming the node or a failing dependency with rapid restart cycles. A Pod stuck in this state is reported with the status CrashLoopBackOff.

kubectl describe pod codartium-app-abc123
kubectl get pod codartium-app-abc123 -w

Related content