Kubernetes pod lifecycle: Phases, states and transitions explained

When you create a pod, it does not immediately start running. It moves through a series of phases as Kubernetes schedules it, pulls the container image, starts the container, and eventually terminates it. Understanding these phases helps you diagnose problems and reason about pod behaviour.

Pod phases at a glance

What happens when you create a pod

When you run kubectl apply -f pod.yaml or kubectl create -f pod.yaml, the following sequence happens:

1kubectl apply -f pod.yaml

1. kubectl converts the YAML to JSON and sends it to the API server
2. The API server authenticates the request using your kubeconfig credentials
3. The API server checks whether the user is authorised to create a pod
4. Admission controllers run any cluster-level policy checks
5. The pod object is persisted to etcd and enters Pending state
6. The scheduler watches for unscheduled pods, finds the best available node based on resource requirements and constraints, and updates the pod spec with the node name
7. The updated pod object is stored in etcd
8. The API server notifies the kubelet on the selected node
9. The kubelet instructs the container runtime to pull the image from the registry
10. The CNI plugin assigns an IP address to the pod and reports it back to the API server
11. The pod moves to ContainerCreating then Running once the container starts

Watch the phase transitions in real time:

1kubectl get pods -w

Observing pod state

Check the current state of all pods:

1kubectl get pods

Expected output:

1NAME         READY   STATUS    RESTARTS   AGE
2sample-pod   1/1     Running   0          2m

Get detailed information including events:

1kubectl describe pod sample-pod

The Events section at the bottom shows each step: node assignment, image pull, container creation, and start. When a pod is stuck in any state, the Events section usually explains why.

Restart policies

The restart policy controls what Kubernetes does when a container inside a pod exits. Set it in the pod spec under spec.restartPolicy.

Example pod with OnFailure restart policy:

1apiVersion: v1
2kind: Pod
3metadata:
4  name: batch-job
5spec:
6  restartPolicy: OnFailure
7  containers:
8  - name: worker
9    image: busybox
10    command: ["sh", "-c", "echo processing && exit 0"]

CrashLoopBackOff

If a container crashes and restarts too many times in quick succession, Kubernetes puts it into CrashLoopBackOff. This is not a phase but a status that indicates Kubernetes is backing off restart attempts with increasing delays to prevent overwhelming the system.

1kubectl get pods

Example output showing CrashLoopBackOff:

1NAME         READY   STATUS             RESTARTS   AGE
2broken-pod   0/1     CrashLoopBackOff   5          3m

Diagnose the cause:

1kubectl logs broken-pod

If the container has already restarted, check the previous container's logs:

1kubectl logs broken-pod --previous

Hooks

Kubernetes supports two lifecycle hooks that run commands at specific points in the container lifecycle.

PostStart runs immediately after the container starts. It runs concurrently with the container's main process. If it fails, the container is killed.

PreStop runs immediately before the container receives a SIGTERM signal. Use it to gracefully drain connections or flush in-flight requests before shutdown. Without it, a rolling update may drop in-flight requests.

1spec:
2  containers:
3  - name: nginx
4    image: nginx
5    lifecycle:
6      postStart:
7        exec:
8          command: ["sh", "-c", "echo container started"]
9      preStop:
10        exec:
11          command: ["sh", "-c", "nginx -s quit && sleep 5"]

Init containers and probes

Init containers run to completion before the main container starts. They are useful for pre-conditions like waiting for a dependency to be ready. See Kubernetes init containers for working examples.

Liveness and readiness probes tell Kubernetes whether a container is healthy and ready to receive traffic. A failed liveness probe causes the container to be restarted. A failed readiness probe removes the pod from service endpoints without restarting it. See Kubernetes container probes for a full guide.