Pod Lifecycle & State Machine: Pending, Running, Succeeded, Failed, and graceful shutdown sequencing.
Pod State Machine & Graceful Shutdown
A Pod passes through a well-defined sequence of phases in its lifecycle. Understanding the exact termination order is essential for building zero-downtime microservices.
+---------------+
| Pending | (Image pull, scheduling, init containers)
+---------------+
|
v
+---------------+
| Running | (Containers running, healthchecks active)
+---------------+
/ \
/ \
v v
+---------------+ +---------------+
| Succeeded | | Failed |
| (Jobs, code 0)| | (CrashLoop, OOM)|
+---------------+ +---------------+
Graceful Pod Termination Timeline
When a Pod is deleted (via kubectl delete pod or during a rolling update):
Time 0s:
1. API Server marks Pod status as "Terminating".
2. Pod is simultaneously removed from the Service Endpoints list (no new traffic sent).
3. Kubelet invokes the container's `preStop` hook (if configured).
Time +Ts:
4. Kubelet sends `SIGTERM` to the container's PID 1.
5. Application finishes processing in-flight requests and stops accepting new connections.
Time +30s (terminationGracePeriodSeconds):
6. If the container process has not exited, Kubelet sends `SIGKILL` to force-kill it.
7. Object is permanently removed from etcd.
Production preStop Pattern
Network iptables rules take 2–5 seconds to propagate across all cluster worker nodes. If your app shuts down instantly upon receiving SIGTERM, incoming traffic in transit will hit closed sockets (generating HTTP 502/504 errors).
lifecycle:
preStop:
exec:
command: ["/bin/sh", "-c", "sleep 10"]
The sleep 10 keeps the application alive while the load balancers and Kube-proxy drain in-flight requests.