Docker Composeの依存関係制御｜depends_onとhealthcheckの正しい使い方

5-2 の末尾で「DBが起動していないとアプリが失敗する問題」を扱いました。単純な depends_on では解決しません。起動順と接続準備完了は別物だからです。

この記事で使うツールは2つ：

1. healthcheck：サービスが「使える状態」かを自己診断する仕組み
2. depends_on + condition: service_healthy：健康になるまで他サービスを待たせる

目次

1. そもそもの問題：起動順≠接続可能
2. depends_on 単独の挙動
3. healthcheck の基本
4. depends_on.condition の3種類
5. 実戦例：アプリ → DB
6. Dockerfile の HEALTHCHECK との関係
7. よくあるつまずき
8. まとめ

1. そもそもの問題：起動順≠接続可能

2. depends_on 単独の挙動

services:
  app:
    image: myapp
    depends_on:
      - db        # ← 「db の起動を待つ」だけ

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret

この書き方では Compose はdb コンテナの「起動」が完了するまで app を起動しないことを保証するだけ。db 内部のプロセスが接続を受け付けられる状態になっているかは見てくれません。

3. healthcheck の基本

healthcheck は「サービスが使える状態か」をDocker自身が定期的に確認する機能。コマンドの exit code で判断します（0＝healthy、非0＝unhealthy）。

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s        # 何秒おきに確認するか
      timeout: 3s         # 1回の確認のタイムアウト
      retries: 10         # 連続何回失敗したら unhealthy と判定
      start_period: 10s   # 起動直後はここで指定した秒数、失敗をカウントしない

代表的な test コマンド例

healthy 状態を確認する

$ docker compose ps
NAME           STATUS
myapp-db-1     Up 30s (healthy)      ← healthy が表示される

$ docker inspect --format='{{json .State.Health}}' myapp-db-1 | jq
{
  "Status": "healthy",
  "FailingStreak": 0,
  "Log": [...]
}

4. depends_on.condition の3種類

Compose V2 では depends_on に condition を指定して「どの条件を満たしたら他サービスを起動するか」を細かく制御できます。

services:
  app:
    image: myapp
    depends_on:
      db:
        condition: service_healthy       # DB が healthy になるまで待つ
      migrate:
        condition: service_completed_successfully   # マイグレ完了まで待つ
      cache:
        condition: service_started       # 起動だけでOK

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10

  migrate:
    build: .
    command: python manage.py migrate
    depends_on:
      db:
        condition: service_healthy

  cache:
    image: redis:7-alpine

5. 実戦例：アプリ → DB

5-1. compose.yml

services:
  app:
    image: postgres:16
    command: sh -c "psql -h db -U postgres -c 'SELECT 1;' && echo '✅ connected' && sleep 60"
    environment:
      PGPASSWORD: secret
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      retries: 20
      start_period: 10s

5-2. 挙動を観察

$ docker compose up
[+] Running 2/2
 ✔ Container myapp-db-1   Created
 ✔ Container myapp-app-1  Created
Attaching to app-1, db-1
db-1   | ...starting PostgreSQL...
db-1   | ...database system is ready to accept connections
 ← healthcheck 通過（数秒遅れて）
app-1  |  ?column?
app-1  | ----------
app-1  |         1
app-1  | (1 row)
app-1  | ✅ connected

6. Dockerfile の HEALTHCHECK との関係

Dockerfile にも HEALTHCHECK 命令があります。イメージ作成時に焼き込まれ、そのイメージから起動したコンテナすべてに適用されます。

# Dockerfile
FROM python:3.12
# ... アプリコードのCOPY・pip install ...
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["gunicorn", "--bind", "0.0.0.0:3000", "app:app"]

7. よくあるつまずき

8. まとめ

参考リンク

• healthcheck（Compose公式） — healthcheck キーの一次情報源。
• depends_on（Compose公式） — condition の3種類と挙動。

Dockerの基礎を動画で体系的に学びませんか？

実務で使う基礎だけを3時間に凝縮。環境構築から丁寧に解説しています。

クーポン割引で講座を見る →