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

この記事のポイント

・extendsは共通のサービス定義を別ファイルに切り出し、複数サービス・複数プロジェクトから再利用する仕組み
・override（docker-compose.override.yml）は同一プロジェクト内の環境差分、extendsは共通化そのものが目的で役割が違う
・Composeのマージ規則では、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

# 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}}\t{{.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