DockerコンテナのPID 1問題を解決する方法｜--initフラグとtiniでシグナル処理とゾンビプロセスを防ぐ設計

この記事のポイント

・アプリをPID 1で起動するとSIGTERMが届かずdocker stopが10秒後にSIGKILLになる
・子プロセスのゾンビが溜まるのはPID 1がwait()を呼ばないのが原因
・--initフラグでtiniをPID 1に差し込むと両問題を解決できる
・本番イメージに焼き込むにはDockerfileにtiniをインストールしてENTRYPOINTに指定する

# sleepコマンドをPID 1として起動した例
$ docker run --rm -d --name pid1-demo ubuntu:24.04 sleep 600

$ docker exec pid1-demo ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.0  0.0   2788   952 ?        Ss   03:21   0:00 sleep 600

# シェル形式（PID 1がshになってしまう）
CMD sh -c "node server.js"
# または
CMD ["sh", "-c", "node server.js"]

# exec形式（PID 1がnodeになる。こちらが正しい）
CMD ["node", "server.js"]

# シェル形式でsleepを起動（shがPID 1でSIGTERMを無視する）
$ docker run --rm -d --name test-signal ubuntu:24.04   sh -c 'exec sleep 600'

# stopにかかる時間を計測
$ time docker stop test-signal
test-signal

real    0m10.394s   ← 10秒以上かかっている（SIGKILLで強制終了）

# PID 1にシェルを置いて子プロセスを次々に起動・終了させる
$ docker run --rm -d --name zombie-test ubuntu:24.04   sh -c 'while true; do sleep 0.1 & done'

# 少し待ってからプロセスを確認
$ docker exec zombie-test ps aux | grep defunct | head -5
root       312  0.0  0.0      0     0 ?        Z    04:15   0:00 [sleep] 
root       313  0.0  0.0      0     0 ?        Z    04:15   0:00 [sleep] 
root       314  0.0  0.0      0     0 ?        Z    04:15   0:00 [sleep] 
root       315  0.0  0.0      0     0 ?        Z    04:15   0:00 [sleep] 
root       316  0.0  0.0      0     0 ?        Z    04:15   0:00 [sleep] 

# ゾンビの数を確認（放置すると増え続ける）
$ docker exec zombie-test ps aux | grep -c defunct
47

# --initフラグを付けて起動
$ docker run --rm -d --name with-init --init ubuntu:24.04   sh -c 'while true; do sleep 0.1 & done'

# PID 1がtiniになっている
$ docker exec with-init ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.0  0.0    876   708 ?        Ss   04:30   0:00 /sbin/docker-init -- sh -c while true; do sleep ...
root         7  0.0  0.0   2788   952 ?        S    04:30   0:00 sh -c while true; do sleep 0.1 & done

# ゾンビが溜まらないことを確認
$ docker exec with-init ps aux | grep defunct | wc -l
0

# --initあり：tiniがSIGTERMをアプリに転送して即座に終了
$ time docker stop with-init
with-init

real    0m0.481s   ← ほぼ即時終了

# compose.yml
services:
  app:
    image: myapp:latest
    init: true    # tiniをPID 1として挿入
    ports:
      - "3000:3000"

  db:
    image: mysql:8.4
    init: true
    environment:
      MYSQL_ROOT_PASSWORD: secret

FROM node:22-alpine

# tiniをパッケージマネージャーで追加
RUN apk add --no-cache tini

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

# ENTRYPOINTの先頭にtiniを置く（exec形式必須）
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "server.js"]

FROM python:3.13-slim

RUN apt-get update && apt-get install -y     tini   && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

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

# Alpine のパス
$ docker run --rm node:22-alpine which tini
/sbin/tini

# Debian/Ubuntu のパス
$ docker run --rm python:3.13-slim sh -c 'apt-get install -y tini -qq && which tini'
/usr/bin/tini

# Dockerfileを正しく書けていればビルド後のコンテナで確認可能
$ docker run --rm myapp:latest ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.0  0.0    884   708 ?        Ss   05:00   0:00 /sbin/tini -- node server.js
root         6  0.2  1.2 681420 49152 ?        Sl   05:00   0:00 node server.js

# 起動時のエラー例
docker: Error response from daemon: failed to create task for container:
failed to create shim task: OCI runtime create failed:
container_linux.go:380: starting container process caused: exec: "/sbin/tini":
stat /sbin/tini: no such file or directory: unknown.

# パスを確認してからDockerfileに書く
$ docker run --rm python:3.13-slim sh -c 'apt-get install -y tini -qq && which tini'
/usr/bin/tini

# Dockerfileは確認したパスで記述
ENTRYPOINT ["/usr/bin/tini", "--"]