In this article
preStop runs within terminationGracePeriodSeconds. A hook does not receive an unlimited separate allowance before TERM. If it consumes most of the window, the main process has little time left and may reach forced termination.
preStop runs within terminationGracePeriodSeconds. A hook does not receive an unlimited separate allowance before TERM. If it consumes most of the window, the main process has little time left and may reach forced termination.
Draw a termination timeline
Preserve deletionTimestamp and logs marking hook start and completion. Then record signal handling and actual process exit. Kubernetes has implementation details, including a small one-off extension for an unfinished hook, but that should not become planned operating headroom. Calculate from the explicit configuration. Publishing terminating network state happens alongside local shutdown; it does not establish a strict ordering of every event for every client.
Define the hook’s responsibilities
preStop can coordinate local shutdown, but a sleep alone does not prove that the entire traffic path has stopped selecting the Pod. Separate rejection of new work, completion of accepted work and process resource cleanup. Give each action an observable marker. Avoid network commands without their own timeout: an unavailable dependency could consume the grace period before the application receives TERM.
Work through a bounded example
Suppose the grace period is 40 seconds and the hook normally consumes 25 seconds. Roughly 15 seconds remain in the shared window, rather than another 40. This is arithmetic, not a production measurement. If a test shows that the TERM handler needs 20 seconds, the configuration does not match its intention. A correction might shorten the hook, redistribute responsibilities or increase the overall allowance when the operational consequences are acceptable.
| Timeline marker | Diagnostic question |
|---|---|
| Deletion begins | When did the shared countdown start? |
| preStop completes | How much time has already been consumed? |
| TERM is handled | Did the process receive its shutdown instruction? |
| Process exits | Did shutdown fit inside the allowance? |
Include the process tree
If PID 1 is a wrapper, inspect forwarding to children and reaping. More grace time does not repair a lost TERM signal. For sidecars, follow the documented shutdown ordering of the installed Kubernetes version. Do not rely on an arbitrary ordering of ordinary Pod containers. Final-state writes need an accessible path and a bounded duration; otherwise correct signals can still leave the process waiting for an unavailable file or service.
Test graceful deletion
Delete a test workload both while idle and under work, retaining the same configuration. The artifact should contain the event table, each action’s allowance and expected exit conditions. Success means the hook completed, the process received its signal and the intended exit path finished. A Terminating object does not establish completed cleanup. These checks concern Pod lifecycle. Streaming API behavior, request replay and usage accounting need their own separate specifications and cannot be inferred from the termination timeline alone.
Retain logs beyond Pod deletion. Without final markers, forced termination can erase the distinction between completed cleanup and a process stopped while handling its signal.
Related operational reading: gpu exit plan; kubernetes gpu scheduling.