Skip to main content

Pod termination sequence

4 min read
AI documentation guide

Pod lifecycle overview · Checklist and references

Complete guide to graceful shutdown​

Graceful shutdown is a pattern that safely completes in-flight requests and stops accepting new requests when a Pod terminates. It is essential for zero-downtime deployments and data integrity.

Pod termination sequence in detail​

Pod termination in Kubernetes follows this sequence.

Figure 1. Sequence from Pod termination request to container termination

Expand the diagram to read labels and follow connections.
Diagram

Timing details:

These timings assume terminationGracePeriodSeconds: 60 and a preStop sleep 5; the actual times scale with the configured grace period and preStop wait.

  1. T+0 seconds: Pod deletion is requested through kubectl delete pod or a rolling update
  2. T+0 seconds: The API Server sets the Pod's deletionTimestamp (shown by kubectl as Terminating)
  3. T+0 seconds: Two operations start concurrently and asynchronously:
    • The Endpoint Controller removes the Pod IP from Service Endpoints
    • kubelet executes the preStop hook
  4. T+0~5 seconds: The preStop hook runs sleep 5 (waiting for Endpoints removal)
  5. T+5 seconds: After preStop completes, kubelet requests the container runtime to send SIGTERM to PID 1
  6. T+5 seconds: The application receives SIGTERM and starts graceful shutdown
  7. T+5~60 seconds: The application completes in-flight requests and performs cleanup
  8. T+60 seconds: SIGKILL (forced termination) is sent when terminationGracePeriodSeconds is reached
Why preStop sleep is necessary

Endpoint removal and preStop hook execution occur asynchronously. Adding a sleep to preStop (e.g. 5 seconds) buys time for the Endpoint Controller and kube-proxy to update iptables, which reduces the chance that new traffic reaches the terminating Pod. A fixed 5 seconds does not guarantee that propagation has completed, though: the delay actually needed depends on EndpointSlice and kube-proxy update latency and may be larger or smaller, so tune it to your environment. Without this pattern, traffic may continue to reach the terminating Pod and cause 502/503 errors.