Docker Composeのextendsで共通設定を複数ファイルに分割管理する方法｜環境別オーバーライドとの使い分け

この記事のポイント

・extendsは共通のサービス定義を別ファイルに切り出し、複数サービス・複数プロジェクトから再利用する仕組み
・includeはCompose v2.20以降で使えるファイル丸ごと取り込み機能。アプリ・インフラ・監視の3ファイル構成でチームの担当領域を分離できる
・configsキーは設定ファイルをコンテナに注入する仕組み。bind mountのホストパス依存を解消できる
・override（docker-compose.override.yml）は同一プロジェクト内の環境差分、extendsは共通化そのものが目的で役割が違う
・ports・volumesなどのリスト項目はマージ時に結合ではなく丸ごと置き換えになる点が事故の原因になりやすい
・docker compose configで結合後の設定を出力し、意図した内容にマージされているかを毎回確認するのが鉄則

# extendsの最小構文
services:
  web:
    extends:
      file: common-services.yml
      service: app-base
    ports:
      - "8080:80"

# common-services.yml（共通設定の置き場）
services:
  app-base:
    image: myapp:latest
    environment:
      - TZ=Asia/Tokyo
      - LOG_LEVEL=info
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3
    restart: unless-stopped

# compose.yml（本体：web/workerがapp-baseを継承する）
services:
  web:
    extends:
      file: common-services.yml
      service: app-base
    ports:
      - "8080:80"

  worker:
    extends:
      file: common-services.yml
      service: app-base
    command: ["python", "worker.py"]

# 結合後の実効設定をYAMLで出力して確認する
$ docker compose config

# 出力例（環境により異なります）
services:
  web:
    environment:
      LOG_LEVEL: info
      TZ: Asia/Tokyo
    healthcheck:
      interval: 30s
      retries: 3
      test:
        - CMD
        - curl
        - -f
        - http://localhost/healthz
      timeout: 5s
    image: myapp:latest
    logging:
      driver: json-file
      options:
        max-file: "3"
        max-size: 10m
    ports:
      - mode: ingress
        target: 80
        published: "8080"
    restart: unless-stopped

# compose.override.yml（本番のみポート・レプリカ数を変更する差分）
services:
  web:
    ports:
      - "443:80"
    deploy:
      replicas: 3

# 本番環境ではoverrideファイルを明示的に指定して起動する
$ docker compose -f compose.yml -f compose.override.yml up -d

# バージョン確認
$ docker compose version

# 出力例（環境により異なります）
Docker Compose version v2.27.0

# Ubuntu / Debian系のアップグレード
$ sudo apt update && sudo apt upgrade docker-compose-plugin

# Rocky Linux / RHEL 9系のアップグレード
$ sudo dnf update docker-compose-plugin

myproject/
├── compose.yml           # ルートCompose（includeのみ書く）
├── services/
│   ├── api/
│   │   ├── compose.yml   # APIサービス定義
│   │   └── Dockerfile
│   ├── db/
│   │   └── compose.yml   # DBサービス定義
│   └── cache/
│       └── compose.yml   # キャッシュサービス定義
└── .env

# compose.yml（ルート）
include:
  - path: ./services/api/compose.yml
  - path: ./services/db/compose.yml
  - path: ./services/cache/compose.yml

networks:
  app-network:
    driver: bridge

$ docker compose up -d

# 出力例（環境により異なります）
[+] Running 3/3
 ✔ Container myproject-db-1     Started
 ✔ Container myproject-cache-1  Started
 ✔ Container myproject-api-1    Started

# インクルードされたサービスの一覧を確認する
$ docker compose config --services
api
cache
db

project/
├── compose.yml                   # メイン（includeを束ねる）
├── app/
│   ├── compose.app.yml           # アプリ層（web, worker）
│   └── Dockerfile
├── infra/
│   ├── compose.infra.yml         # インフラ層（db, redis）
│   └── initdb/
│       └── 01_init.sql
└── monitoring/
    ├── compose.monitoring.yml    # 監視層（prometheus, grafana）
    └── prometheus.yml

# compose.yml（メインファイル）
include:
  - app/compose.app.yml
  - infra/compose.infra.yml
  - monitoring/compose.monitoring.yml

# app/compose.app.yml（アプリ層）
services:
  web:
    build: .
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgresql://postgres:secret@db:5432/myapp
    depends_on:
      db:
        condition: service_healthy

  worker:
    build: .
    command: celery -A myapp worker -l info
    depends_on:
      - redis
      - db

# infra/compose.infra.yml（インフラ層）
services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./initdb:/docker-entrypoint-initdb.d
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myapp
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    volumes:
      - redisdata:/data

volumes:
  pgdata:
  redisdata:

# 開発環境（ソースコードをバインドマウントし、デバッグモードを有効化）
$ docker compose -f compose.yml -f compose.dev.yml up

# 本番環境（ビルドイメージをそのまま使用）
$ docker compose -f compose.yml -f compose.prod.yml up

# compose.dev.yml（開発用の追加設定）
services:
  web:
    volumes:
      - .:/app
    environment:
      DEBUG: "true"

# compose.yml
configs:
  nginx_config:           # configの名前（任意）
    file: ./nginx.conf    # ホスト側のファイルパス

services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    configs:
      - source: nginx_config            # configの名前
        target: /etc/nginx/nginx.conf   # コンテナ内の配置先
        mode: 0444                      # ファイルの権限（8進数）

configs:
  shared_config:
    file: ./shared-settings.conf

services:
  app:
    image: myapp:latest
    configs:
      - source: shared_config
        target: /app/config/settings.conf

  monitor:
    image: fluentd:latest
    configs:
      - source: shared_config
        target: /etc/fluent/settings.conf

configs:
  nginx_config:
    file: ./nginx.conf

secrets:
  db_password:
    file: ./db_password.txt  # .gitignoreで除外

services:
  nginx:
    image: nginx:latest
    configs:
      - source: nginx_config
        target: /etc/nginx/conf.d/default.conf

  app:
    image: myapp:latest
    secrets:
      - db_password

  db:
    image: postgres:16
    secrets:
      - db_password
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password

# app-base側のvolumes（共有ライブラリのマウント）
services:
  app-base:
    volumes:
      - shared_lib:/opt/shared

# web側でvolumesを追加したつもりが、実際は置き換わってしまう例
services:
  web:
    extends:
      file: common-services.yml
      service: app-base
    volumes:
      - ./web-static:/var/www/static
      # ← ここに shared_lib のマウントを書き足さないと消える

# 認識されているサービス一覧を確認（extends先のservice名の誤字はここで発覚しやすい）
$ docker compose config --services
web
worker
db

# 起動中コンテナの実際のマウント・ポート状況を確認
$ docker compose ps --format "table {{.Name}}	{{.Ports}}"
NAME          PORTS
myapp-web-1   0.0.0.0:8080->80/tcp
myapp-worker-1

$ docker compose up -d
service "web" refers to undefined service "app-base": could not find common-services.yml

# 対処: extends.fileのパスを実際のディレクトリ構成に合わせて修正する
extends:
  file: ../shared/common-services.yml
  service: app-base

# サービスを停止・削除してから再起動（configも再作成される）
$ docker compose down
$ docker compose up -d

# 再起動後にコンテナ内の設定ファイルを確認する
$ docker compose exec nginx cat /etc/nginx/nginx.conf

# エラー例（出力例、環境により異なります）
Error response from daemon:
open /path/to/infra/compose.infra.yml: no such file or directory

# エラー例（出力例、環境により異なります）
Error: service "redis" already defined in included file