Custom Stop Signals for Containers in Kubernetes v1.33 (Alpha Feature)

When running critical workloads such as stateful services, background daemons, or applications that require long‑living connections, containers need to stop gracefully. Historically Kubernetes relied entirely on the base image’s configuration (the Dockerfile STOPSIGNAL instruction) to decide which signal to send on termination.

In Kubernetes v1.33 an Alpha feature gate called ContainerStopSignals is introduced. It adds a new field lifecycle.stopSignal to the PodSpec, allowing platform teams to define the termination signal for each container directly at the Pod level, without depending on the image.

Example configuration:

apiVersion: v1
kind: Pod
metadata:
  name: graceful-nginx
spec:
  os:
    name: linux
  containers:
    - name: nginx
      image: nginx:latest
      lifecycle:
        stopSignal: SIGUSR1

The Kubelet will send SIGUSR1 instead of the default SIGTERM when the container is stopped. Note that the spec.os.name field must be set (e.g., linux ) so Kubernetes can validate that the chosen signal is supported on the target OS.

Signal selection follows this priority order:

If lifecycle.stopSignal is defined, use that signal.

Otherwise, use the signal defined in the image via STOPSIGNAL .

If neither is present, fall back to the container runtime’s default signal (usually SIGTERM ).

Operating‑system limitations:

Linux containers support most standard signals such as SIGTERM , SIGINT , SIGUSR1 , etc.

Windows containers only support SIGTERM and SIGKILL . Attempting to set an unsupported signal on a Windows pod results in a validation error.

The feature is currently Alpha and disabled by default. To enable it, the following flag must be added to both the kube‑apiserver and kubelet:

--feature-gates=ContainerStopSignals=true

Runtime support (e.g., containerd, CRI‑O) may lag behind the API implementation, but if a runtime does not yet support the feature, Kubernetes will gracefully fall back to the image‑defined or default signal, ensuring workload stability.

Practical impact: applications like Redis that prefer SIGINT for graceful shutdown can now specify that signal directly in the Pod spec, eliminating the need to rebuild images or add wrapper scripts. This gives platform operators finer control over container lifecycle behavior and aligns container actions with operational requirements.

In summary, the ContainerStopSignals Alpha feature reflects a broader Kubernetes trend of moving control from the image layer to the orchestration layer, providing more precise lifecycle management and laying a solid foundation for production‑grade systems.