9.19 Kubernetes Container Lifecycle Hooks

Kubernetes Container Lifecycle Hooks is the set of two configurable event handlers, postStart and preStop, that Kubernetes invokes at specific points in a container's lifecycle, allowing an application to execute custom logic immediately after it starts and immediately before it is terminated, without requiring that logic to be built directly into the application's own entrypoint or shutdown handling.

postStart Hook

Invocation Timing

The postStart hook is executed by the kubelet immediately after a container is created, running concurrently with the container's main process rather than blocking its execution, which means there is no strict guarantee that the hook runs strictly before the main process begins performing its own work.

Guarantee of At-Least-Once Delivery

Kubernetes guarantees that the postStart hook is called at least once for every container start, but does not guarantee it completes before the container's ENTRYPOINT executes, meaning applications that require setup to happen strictly prior to their own startup logic should not rely on this hook for strict ordering guarantees.

Effect of Hook Failure

If the postStart hook fails, whether by returning a non-zero exit code for an exec-based hook or receiving a non-success HTTP response for an HTTP-based hook, the container is considered to have failed its startup, and the kubelet kills it, triggering the standard restart behavior dictated by the Pod's restartPolicy.

preStop Hook

Invocation Timing

The preStop hook is executed by the kubelet immediately before a termination signal is sent to the container's main process, and critically, this execution is synchronous: the kubelet waits for the hook to complete, or for the Pod's grace period to expire, before proceeding to signal the process itself.

Common Use Cases

A frequent use of the preStop hook is to introduce a deliberate short delay before shutdown begins, allowing time for the Pod's removal from Service endpoints to propagate across the cluster, which helps prevent in-flight requests from being routed to a Pod that is already in the process of terminating.

Consumption of the Grace Period

Because the preStop hook runs within the bounds of the Pod's overall termination grace period, a long-running hook reduces the time remaining for the application's own graceful shutdown after receiving its termination signal, meaning hook duration and application shutdown time must be balanced against the total configured grace period.

Hook Handler Types

Exec-Based Hooks

An exec-based hook runs a specified command inside the container, similar in mechanism to an exec-based probe, and is commonly used for lightweight scripts that perform tasks such as deregistering from a service registry or writing a final log entry.

HTTP-Based Hooks

An HTTP-based hook issues a request to a specified endpoint within the container, allowing the hook logic to be implemented as part of the application's own HTTP interface rather than as a separate script, which can simplify hooks for applications that already expose administrative HTTP endpoints.

Relationship to Probes

Distinct Purpose From Health Checks

Unlike probes, which continuously assess ongoing health and readiness, lifecycle hooks fire only once per relevant event, either at container start or at the beginning of termination, serving a fundamentally different purpose oriented around one-time setup and teardown actions rather than repeated health evaluation.

No Direct Interaction With Probe Timing

Lifecycle hooks operate independently of probe scheduling; a postStart hook running long does not delay when liveness or readiness probes begin, though a poorly designed postStart hook that fails can indirectly trigger a restart that resets probe evaluation for the newly restarted container instance.

Failure Visibility

Event Reporting

Failures in either hook are recorded as Kubernetes events associated with the Pod, providing visibility into hook-related failures separately from application-level log output, which is particularly useful since a failing preStop hook might otherwise be mistaken for slow application shutdown rather than a distinct hook execution problem.