Dockerのgraceful shutdown設計｜STOPSIGNALとstop_grace_periodでコンテナを安全に終了させる方法

この記事のポイント

・docker stopはSIGTERM→10秒待機→SIGKILLの順で終了させる
・PID 1問題でSIGTERMが届かないことが最多の原因
・STOPSIGNALとstop_grace_periodで終了挙動を制御する
・tiniとinit: trueでPID 1問題を根本解消できる

# docker stopの内部シーケンス
Step1: コンテナのPID 1プロセスにSIGTERMを送信
Step2: --time秒（デフォルト10秒）待機
         アプリがSIGTERMを受け取ってシャットダウン処理を実行
Step3: まだプロセスが残っていればSIGKILLで強制終了

# 猶予時間を30秒に延長してコンテナを停止する
$ docker stop --time 30 mycontainer
mycontainer

# 実行時間の計測（gracefulに終了した場合）
$ time docker stop --time 30 mycontainer
mycontainer

real    0m1.842s    # 2秒でgraceful exitできた例

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
# NG: shell形式 --- /bin/sh がPID 1になる
CMD python app.py

# コンテナ内でプロセスを確認（Ubuntu 24.04 LTS + Docker 26.1 での実測）
$ docker exec -it myapp ps aux
USER         PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root           1  0.0  0.0   2804  1408 ?        Ss   09:31   0:00 /bin/sh -c python app.py
root           8  0.1  0.9  38192 18432 ?        S    09:31   0:00 python app.py
root          15  0.0  0.0   7004  1408 pts/0    Rs+  09:31   0:00 ps aux

FROM python:3.12-slim
WORKDIR /app
COPY . .
# OK: exec形式 --- python自身がPID 1になる
CMD ["python", "app.py"]

# exec形式のCMDに変更後（Ubuntu 24.04 LTS + Docker 26.1 での実測）
$ docker exec -it myapp ps aux
USER         PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root           1  0.2  0.9  38192 18944 ?        Ss   09:45   0:00 python app.py
root          14  0.0  0.0   7004  1408 pts/0    Rs+  09:45   0:00 ps aux

# Dockerfileの例（Nginxのgraceful stop設定）
FROM nginx:1.26-alpine
# SIGTERMの代わりにSIGQUITを使う（Nginxのgraceful stop）
STOPSIGNAL SIGQUIT

$ docker inspect --format '{{.Config.StopSignal}}' mynginx
SIGQUIT

# 公式nginx:alpineイメージはもともとSIGQUITが設定されている
$ docker inspect --format '{{.Config.StopSignal}}' nginx:1.26-alpine
SIGQUIT

# compose.yml の例
services:
  web:
    image: nginx:1.26-alpine
    stop_signal: SIGQUIT        # docker stopで送るシグナル
    stop_grace_period: 30s      # SIGKILLまでの猶予時間（デフォルト10s）
    ports:
      - "80:80"

  app:
    build: .
    stop_signal: SIGTERM
    stop_grace_period: 60s      # 本番の長いリクエストに対応
    ports:
      - "8000:8000"

# 設定前（デフォルト --- 10秒でSIGKILL）
$ time docker compose stop
[+] Stopping 1/1
 ✔ Container myproject-web-1  Stopped    10.3s    # タイムアウト = SIGKILL発動

real    0m10.389s

# compose.ymlにstop_signal: SIGQUIT, stop_grace_period: 30sを設定後
$ time docker compose stop
[+] Stopping 1/1
 ✔ Container myproject-web-1  Stopped    1.8s     # 素早くgraceful exit

real    0m2.013s

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt

# tiniをインストールしてPID 1に据える
RUN apt-get update && apt-get install -y --no-install-recommends tini && \
    rm -rf /var/lib/apt/lists/*

ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["python", "app.py"]

# tini導入後のプロセス確認（Ubuntu 24.04 LTS + Docker 26.1 での実測）
$ docker exec myapp ps aux
USER         PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root           1  0.0  0.0   6576  1024 ?        Ss   10:02   0:00 /usr/bin/tini -- python app.py
root           7  0.3  0.9  38192 19200 ?        S    10:02   0:00 python app.py
root          21  0.0  0.0   7004  1408 pts/0    Rs+  10:02   0:00 ps aux

services:
  app:
    image: myapp:latest
    init: true              # dumb-initをPID 1として注入する
    stop_grace_period: 30s

# まずPID 1を確認する
$ docker exec myapp ps aux | head -5

# SIGTERMをアプリに直接送って反応するか確認する（ホストから実行）
$ docker kill --signal SIGTERM myapp
myapp
# アプリのログに終了メッセージが確認できれば正常にSIGTERMを受け取れている

# stop_grace_periodを30秒に延長して再テスト
# compose.yml の該当サービスに追記:
#   stop_grace_period: 30s