Graceful shutdown is a timed protocol across routing, lifecycle, and workload ownership.
Infrastructure · YAML
Kubernetes Drain Budget
A termination grace period budgets routing convergence and owned-work drainage.
spec:
terminationGracePeriodSeconds: 40
containers:
- name: api
lifecycle:
preStop:
httpGet: { path: /begin-drain, port: 8080 }
readinessProbe:
httpGet: { path: /ready, port: 8080 }
# /begin-drain returns quickly, fails readiness, and stops new claims.
# Budget = routing convergence + maximum drain + safety margin.
# preStop and process shutdown share the same 40 seconds.Invariant: Owned work exits or becomes safely reclaimable before termination grace expires.
Use when: A pod must stop admission and drain before forced termination.
Why this boundary matters
Endpoint withdrawal, connection drainage, and process exit happen concurrently. One measured budget prevents dropped work and immortal termination.
Failure policy
| Boundary | Action |
|---|---|
| SIGTERM received | Fail readiness and stop claiming work |
| Existing request | Drain inside its deadline |
| Claimed background work | Finish, checkpoint, or release its lease |
| Telemetry flush fails | Bound the flush |
| Grace nearly exhausted | Exit so recovery can proceed |
Trade-offs
Long grace preserves work but slows rollouts. Short grace increases ambiguity and lease recovery. A preStop hook consumes the same window.
Decision rule: Set grace from measured routing propagation plus maximum drain time and a safety margin; verify under load.