Kubernetes Pods: Lifecycle Phases, Init Containers, and Restart Policies
Phase versus container state, ordered init containers that rerun on restart, native sidecars, and the exit codes behind CrashLoopBackOff. How to read a pod's status in the order that answers the question.

Quick Summary
A Pod is the smallest schedulable unit in Kubernetes: one or more containers sharing a network namespace, an IPC namespace, and volumes, scheduled together onto one node. Its lifecycle is described at two levels. The pod status.phase is a coarse summary — Pending, Running, Succeeded, Failed, Unknown — while each container has a state (Waiting, Running, Terminated) with a reason such as ImagePullBackOff, CrashLoopBackOff, or OOMKilled. The phase is almost never the useful diagnostic; the container state reasons are.
Init containers run before any app container, one at a time, each to completion, with their own image and their own volume mounts. They exist for setup that must not run concurrently with the app: waiting for a database, cloning a config repository, fixing volume permissions, or generating a TLS key. Because they run in the same pod, they see the same network and the same volumes, and their logs are readable with -c.
restartPolicy is per pod, not per container: Always (default, for workloads), OnFailure, or Never (for one-shot jobs). The kubelet applies it with exponential backoff capped at five minutes, which is why a crashing container shows CrashLoopBackOff with growing gaps rather than a tight loop. This guide covers the phase and condition model, init containers and native sidecars, restart and termination semantics, and the status queries that answer "why is this pod not running".
Basic Syntax & Core Signatures
apiVersion: v1
kind: Pod
metadata:
name: api
labels: { app: api }
spec:
restartPolicy: Always # Always | OnFailure | Never
terminationGracePeriodSeconds: 30
activeDeadlineSeconds: 600 # hard cap on total runtime
initContainers:
- name: wait-for-db
image: busybox:1.36
command: ['sh', '-c', 'until nc -z db 5432; do echo waiting; sleep 2; done']
- name: fix-perms
image: busybox:1.36
command: ['sh', '-c', 'chown -R 1000:1000 /data']
volumeMounts: [{ name: data, mountPath: /data }]
containers:
- name: api
image: ghcr.io/acme/api:1.4.2
ports: [{ containerPort: 8080 }]
volumeMounts: [{ name: data, mountPath: /data }]
volumes:
- name: data
emptyDir: {}# Lifecycle and state
kubectl get pod api -o wide
kubectl get pod api -o jsonpath='{.status.phase}{"\n"}{range .status.containerStatuses[*]}{.name}={.state}{"\n"}{end}'
kubectl describe pod api # events at the bottom: the real story
kubectl logs api -c wait-for-db # init container log
kubectl logs api --previous # the container that died
# Conditions
kubectl get pod api -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\n"}{end}'
# PodScheduled=True Initialized=True ContainersReady=True Ready=True
# Wait helpers
kubectl wait --for=condition=Ready pod/api --timeout=120s
kubectl wait --for=jsonpath='{.status.phase}'=Succeeded job/migrate --timeout=300s# Native sidecar (Kubernetes 1.29+, stable in 1.33): an init container that never exits
initContainers:
- name: log-shipper
image: fluent/fluent-bit:3.0
restartPolicy: Always
volumeMounts: [{ name: logs, mountPath: /var/log/app }]# Lifecycle hooks
lifecycle:
postStart:
exec: { command: ["/bin/sh", "-c", "curl -sf localhost:8080/ready || true"] }
preStop:
exec: { command: ["/bin/sh", "-c", "sleep 5; /app/drain.sh"] }Key Comparison Table
| Phase | Meaning | Typical cause |
|---|---|---|
Pending | Accepted, not yet running | Unschedulable, image pulling, init container running |
Running | Bound to a node, at least one container running | May still be Ready=False |
Succeeded | All containers exited 0, and will not restart | Job, OnFailure/Never |
Failed | All containers terminated, at least one failed | Bad command, activeDeadlineSeconds |
Unknown | Node not reporting | Node NotReady, kubelet unreachable |
| Container state / reason | Meaning | First thing to check |
|---|---|---|
Waiting / ImagePullBackOff | Cannot pull the image | Image name, tag, registry secret |
Waiting / CrashLoopBackOff | Keeps exiting, backoff applied | logs --previous, exit code |
Running / Ready=False | Failing readiness | Readiness probe, dependency health |
Terminated / OOMKilled | Exceeded memory limit | resources.limits.memory, heap settings |
Terminated / Completed | Exit code 0 | Normal for a job |
Terminated / Error | Nonzero exit | Entrypoint, config, missing file |
| Restart policy | Applies to | Exit 0 | Exit nonzero |
|---|---|---|---|
Always | Deployments, StatefulSets, DaemonSets | Restarts | Restarts |
OnFailure | Jobs | Stays Completed | Restarts |
Never | Jobs, debugging pods | Stays Completed | Stays Failed |
| Field | Effect |
|---|---|
terminationGracePeriodSeconds | Time between SIGTERM and SIGKILL |
activeDeadlineSeconds | Kills the pod after this many seconds |
shareProcessNamespace | Containers see each other's processes |
initContainers[].restartPolicy: Always | Sidecar that starts first and stays running |
Practical Edge Cases & Deep Dives
1. Pending with no events: the scheduler has nothing to say
$ kubectl describe pod api | tail -5
Events:
Warning FailedScheduling 30s (x5) default-scheduler
0/3 nodes are available: 3 Insufficient cpu.Pending splits into two causes. Either the scheduler cannot place the pod (FailedScheduling, with a reason such as insufficient CPU/memory, no matching node selector or affinity, taints without tolerations, or an unbound PVC), or it is placed and something else blocks start (ImagePullBackOff, a volume that cannot attach, or a long init container). The event text names which. Scheduling problems repeat with the same reason and only appear when the pod is re-queued; wait for the second event if the first is empty.
kubectl get events --field-selector involvedObject.name=api --sort-by=.lastTimestamp
kubectl describe node | grep -A5 'Allocated resources'2. Init containers: ordered, blocking, and re-run on restart
$ kubectl get pod api -o jsonpath='{.status.initContainerStatuses[*].name}'
wait-for-db fix-perms
$ kubectl logs api -c wait-for-db
waiting
waitingInit containers run strictly in order and the pod does not start app containers until all have succeeded. Two consequences: a bad init container makes the pod look stuck with no application logs, and if the pod restarts, every init container runs again (restartPolicy: Always re-runs them on each pod restart, not on container restart within the pod). A long-running init container (waiting for a database) therefore delays every restart, which is why activeDeadlineSeconds on the pod or a bounded retry loop inside the init container is worth adding. Init containers support a subset of fields — no lifecycle, no readinessProbe, no ports — and consume resources in the pod's scheduling calculation based on the largest request of any single container.
3. Native sidecars, and why they are init containers
initContainers:
- name: proxy
image: envoyproxy/envoy:v1.31.0
restartPolicy: AlwaysBefore native sidecars, a sidecar was an ordinary container in the pod, which meant it could start after the app, could be the only thing keeping a completed Job's pod alive, and could not be ordered relative to init containers. A restartPolicy: Always init container starts in init order, keeps running, stays alive with the pod, does not block job completion in the same way, and stops in reverse order at shutdown. Istio and other meshes moved to this form; it requires a cluster at 1.29+ (beta) or 1.33+ (stable), and kubectl older than that version will show it puzzlingly.
4. CrashLoopBackOff and the exit code that explains it
$ kubectl get pod api
NAME READY STATUS RESTARTS AGE
api 0/1 CrashLoopBackOff 5 6m
$ kubectl get pod api -o jsonpath='{.status.containerStatuses[0].lastState.terminated}'
{"exitCode":1,"reason":"Error","startedAt":"...","finishedAt":"..."}Exit 1 is the application's own failure; 137 means SIGKILL (an OOM kill or a probe-forced restart); 143 means SIGTERM (graceful termination, normal during rollout); 139 is a segfault. CrashLoopBackOff itself is just an event count — the backoff starts at 10 seconds, doubles, and caps at 5 minutes, and the container is recreated regardless until kubectl delete or the spec changes. Always read --previous logs: the current container may have produced no output yet.
kubectl logs api --previous --tail=100
kubectl get pod api -o jsonpath='{.status.containerStatuses[0].lastState.terminated.exitCode}{"\n"}'5. Termination order and the requests that never finish
spec:
terminationGracePeriodSeconds: 60
containers:
- name: api
lifecycle:
preStop:
exec: { command: ["/bin/sh", "-c", "sleep 10"] }On deletion the pod goes to Terminating: the endpoint is removed from the Service (in parallel), preStop runs, then SIGTERM is sent, then SIGKILL after the grace period. The classic bug is a preStop sleep longer than the grace period, which guarantees SIGKILL, or an app that ignores SIGTERM and relies on grace that other containers already used. A preStop sleep of a few seconds is a pragmatic way to cover the window between endpoint removal and the proxy updating, but the correct pattern is an application that drains on SIGTERM and exits well inside terminationGracePeriodSeconds.
Note that a pod stuck in Terminating for hours is usually a node-level problem (a volume that will not unmount, or a kubelet that stopped responding); kubectl delete pod --grace-period=0 --force leaves the volume attached and should be the last resort.
6. Debugging without modifying the workload
# Ephemeral debug container: shares the pod's namespaces
kubectl debug -it pod/api --image=nicolaka/netshoot --target=api
# A copy of the pod with a different command, without touching the original
kubectl debug pod/api --copy-to=api-dbg --container=api -- sh -c 'sleep 3600'
# From a node's namespaces
kubectl debug node/worker-1 -it --image=busyboxkubectl debug --target requires the target container's process namespace and a distribution image with the tools; --copy-to is the safer route when the pod spec is immutable or managed by a controller. Both leave objects behind, so delete the debug pod and the ephemeral container's effects explicitly.
Common Runtime & Configuration Mistakes
| Symptom | Cause | Fix |
|---|---|---|
Pending forever, no events | Scheduler has not re-queued, or a webhook blocks creation | Check describe, validatinog webhooks, ResourceQuota |
FailedScheduling: Insufficient cpu | Requests exceed the node's allocatable | Lower requests, add nodes, check Allocated resources |
ImagePullBackOff | Wrong tag or missing imagePullSecrets | Fix the reference, create the secret in the namespace |
CreateContainerConfigError | Referenced ConfigMap/Secret key missing | Create the key or the object |
Init:CrashLoopBackOff | Init container failing repeatedly | logs -c <init>, its exit code |
| App never starts, init container slow | Ordered, blocking init | Bound the wait, add activeDeadlineSeconds |
OOMKilled (exit 137) | Memory limit below the working set | Raise the limit, set runtime heap/max-old-space |
| Pod restarts read as a deployment bug | restartPolicy: Always with a failing app | Fix the app; restartPolicy is a pod-level policy |
| Job pod never completes | Sidecar never exits | Native sidecar or restartPolicy: Never |
Long Terminating, then SIGKILL | preStop longer than the grace period | Shorten preStop, raise the grace period |
Terminating stuck for hours | Volume unmount or node problem | Drain the node; do not force-delete first |
| Exec into a distroless container fails | No shell in the image | kubectl debug --target with a tool image |
A pod's status is a story in layers: the phase says whether the scheduler and kubelet moved it, the container states name the reason, the events carry timestamps and messages, and the logs (including --previous and per-init-container) carry the application's side. Reading them in that order resolves almost every "it's not starting" question without changing a single line of the manifest.
Try matching browser tools
All toolsSmall utilities that fit Kubernetes work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Kubernetes guides
All Kubernetes guideskubectl Output: jsonpath, custom-columns, and the Debugging Commands Worth Knowing
jsonpath for one value in a script, custom-columns for tables people read, and kubectl debug when the container has no shell. Includes the three quoting layers that break jsonpath.
Kubernetes Namespaces, ResourceQuotas, and LimitRanges
A namespace is only a boundary when quota and limit range make it one. Aggregate caps, per-pod defaults, the admission errors they produce, and namespaces stuck Terminating.
Kubernetes StatefulSets: Ordinal Identities, Headless Services, and PVC Lifecycle
Why each StatefulSet pod keeps a name, a DNS record, and its own PVC; how OrderedReady gates startup on readiness; and how partition-based updates canary a single quorum member.
Kubernetes securityContext, Capabilities, and Pod Security Standards
The five fields that remove most container escapes, which of them only exist at container level, and how the restricted profile enforces the same settings at admission.
More in Kubernetes
All Kubernetes guidesThe guides filed next to this one in Kubernetes, in library order.