Shutdown hooks

Controlling container shutdown with custom scripts

This page describes how to configure and use Webscale’s shutdown hook mechanism so your application servers can finish in-flight work cleanly before they are destroyed.

The goal: when Webscale needs to terminate a server (scale in, rolling deploy, or manual destroy), your application gets a clear signal, some time to react, and the platform waits (up to a limit) before terminating the server.

Scope: This applies to managed or unmanaged clusters running a web-server image of version 2025.44 or later.

High-level behavior

When a server is selected for termination:

  1. Webscale initiates termination of the server instance through its cloud provider.
  2. A systemd shutdown unit on the host runs the Webscale container shutdown handler.
  3. The handler iterates over all running application containers on that host.
  4. For each container:
  • It runs /hooks/shutdown inside the container if that file exists and is executable.
  • It waits for the hook to exit, subject to a time out of 10 minutes for all hooks.
  1. Once all hooks have completed or timed out, the platform proceeds with normal shutdown and destroys the server.

The actions performed by the shutdown hook are entirely determined by the application containers that are run on the web-server container host as determined by the “bootstrap” configuration.

Important:

The shutdown hook is triggered when the server is actually being destroyed, not when a deployment becomes “old” or is no longer receiving primary traffic. Old deployments may still perform work until their destruction is requested. If it is necessary to begin the shutdown for deployments in managed clusters as soon as they are no longer needed, a destroy delay of 0 must used.

What the shutdown hook is for

Use the hook to:

  • Stop accepting new work.
  • Let in-flight requests complete.
  • Drain queues / background jobs.
  • Persist state that would otherwise be lost.
  • Emit final logs / metrics for the node.

Do not use the hook to:

  • Keep the server alive indefinitely.
  • Perform long-running maintenance that should be done elsewhere.
  • Start new long-lived background jobs.

If all hooks do not finish within 10 minutes, Webscale will continue shutdown anyway and the instance will be terminated. The cloud provider may terminate the instance sooner, so it is best for a hook to complete work within a minute or less to ensure that it is not forcibly terminated.

Implementing a hook inside a container

On each container, if /hooks/shutdown exists and is executable, it will be run as root. Standard output and error are written to the container-shutdown service unit logs.

Minimal example

A very simple shutdown hook that terminates a scheduler process and then waits for it to complete:

#!/bin/sh

# Shutdown hook to terminate the scheduler process. The scheduler responds to
# SIGTERM causing it to stop scheduling new work and only exits when all
# in-flight work is done.

PID="$(pidof scheduler)"
if [ -n "$PID" ]; then
  kill $PID

  while kill -0 $PID; do
    sleep 1
  done
fi

Make shutdown.sh executable in your repository and ensure it is copied in your Dockerfile to the correct location.

COPY shutdown.sh /hooks/shutdown

FAQ

Q: Will this hook run when the deployment is made inactive but not destroyed?

A: No. It runs when the server is being terminated (scale-in, deployment expired, or manual destroy), not when a deployment just becomes non-current.

Q: Can I rely on SSH / network / Docker being available during the hook?

A: Yes, during the controlled shutdown window the host is still in a normal running state: Docker, networking, and SSH remain available while your hook runs. Once the hook finishes or times out, shutdown continues and these services go away. Any SSH sessions are terminated at the initiation of shutdown, however, so any diagnosis must be done on a new session.

Q: Can I keep the instance alive indefinitely by never exiting the hook?

A: No. The process of terminating the server with the cloud provider has already begun to terminate the server. All cloud providers will eventually power off hosts that do not shutdown promptly.

Q: Can I run different shutdown behavior per container type?

A: Yes. Each container image can provide its own hook implementation. Containers without the script will simply be terminated normally.


Last modified November 19, 2025