Kubernetes Container Lifecycle Hooks

Kubernetes Container Lifecycle Hooks are user-defined actions the kubelet executes at specific points in a container's life, independent of the container's own entrypoint or main process, configured through the lifecycle field on a container spec. The two supported hooks, postStart and preStop, let operators inject setup or cleanup behavior around a container's execution without modifying the container image itself.

postStart Hook

Execution Timing

postStart runs immediately after a container is created, asynchronously and without any guaranteed ordering relative to the container's own entrypoint process starting. Kubernetes does not wait for the container's main process to reach any particular state before firing this hook; the two can execute concurrently.

containers:
  - name: app
    lifecycle:
      postStart:
        exec:
          command: ["sh", "-c", "echo starting >> /var/log/lifecycle.log"]

Blocking Container Readiness

Although asynchronous relative to the main process, postStart does block the container from being reported as started until the hook itself completes. If the hook hangs or fails, the container is considered to have failed startup, which can prevent the Pod from ever leaving Pending.

preStop Hook

Execution Timing

preStop runs synchronously immediately before the kubelet sends SIGTERM to the container's main process, as part of the termination sequence. The kubelet waits for preStop to finish (or time out) before delivering the termination signal.

containers:
  - name: app
    lifecycle:
      preStop:
        exec:
          command: ["sh", "-c", "sleep 5 && /app/drain-connections.sh"]

Common Use: Draining In-Flight Requests

Because Service endpoint removal and container shutdown are not perfectly synchronized, a brief preStop sleep is a common pattern to absorb the propagation delay before endpoint removal takes effect across all kube-proxy instances, preventing new connections from arriving at a container that is about to stop.

Handler Types Available to Hooks

exec and httpGet

Both postStart and preStop support two handler types: exec, running a command inside the container, and httpGet, issuing an HTTP request to an endpoint on the container. Unlike probes, lifecycle hooks do not support tcpSocket or grpc handlers.

lifecycle:
  preStop:
    httpGet:
      path: /shutdown
      port: 8080

Failure Behavior

Hook Errors Are Treated as Fatal Events

If a postStart hook fails, the associated container is killed. If a preStop hook fails, the kubelet proceeds to send SIGTERM anyway once the hook's execution completes or times out, but the failure is recorded as a Pod event, FailedPostStartHook or FailedPreStopHook, visible through kubectl describe pod.

kubectl describe pod lifecycle-hooks-example

Warning  FailedPreStopHook  12s  kubelet  Exec lifecycle hook failed: command exited with code 1

Interaction With terminationGracePeriodSeconds

Hook Time Counts Against the Grace Period

The time preStop takes to execute is deducted from the Pod's overall terminationGracePeriodSeconds budget, not added on top of it. A preStop hook that runs long can leave little or no remaining time for the application to respond to SIGTERM before SIGKILL is issued, so the grace period must be sized to accommodate both.

spec:
  terminationGracePeriodSeconds: 45
  containers:
    - name: app
      lifecycle:
        preStop:
          exec:
            command: ["sh", "-c", "sleep 10"]

Lifecycle Hook Diagram

Because both hooks run outside the container's normal signal-handling path, they provide a way to attach setup and teardown behavior even to containers whose images cannot be modified to handle these concerns internally.