Docker ComposeのYAMLアンカーとExtension fields（x-プレフィックス）でcompose.ymlの重複を排除する方法

この記事のポイント

・YAMLアンカー（&）でブロックに名前を付け、*（エイリアス）で複数サービスから参照できる
・<<（マージキー）でアンカーをマージしつつ、個別サービス側で一部だけ上書きできる
・Extension fields（x-プレフィックス）でアンカーをファイル先頭に集約して管理できる
・アンカーはファイル内DRY化、extendsはサービス継承、includeはファイル分割と役割が異なる
・docker compose configで展開後の設定を確認してから本番へ適用するのが安全な手順

# 問題のあるcompose.yml（重複設定が3か所に散在している）
services:
  web:
    image: myapp:latest
    ports:
      - "8000:8000"
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      - LOG_LEVEL=info
      - TZ=Asia/Tokyo

  worker:
    image: myapp:latest
    command: python worker.py
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      - LOG_LEVEL=info
      - TZ=Asia/Tokyo

  scheduler:
    image: myapp:latest
    command: python scheduler.py
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      - LOG_LEVEL=info
      - TZ=Asia/Tokyo

# &logging-config でアンカーを定義する
logging: &logging-config
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

services:
  web:
    image: myapp:latest
    logging: &logging-config       # アンカーをここで定義
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  worker:
    image: myapp:latest
    command: python worker.py
    logging: *logging-config       # アンカーを参照（展開）

  scheduler:
    image: myapp:latest
    command: python scheduler.py
    logging: *logging-config       # 同様に参照

# 共通設定をアンカーで定義
x-common-settings: &common-settings
  restart: unless-stopped
  logging:
    driver: "json-file"
    options:
      max-size: "10m"
      max-file: "3"

services:
  web:
    <<: *common-settings         # 共通設定をマージ
    image: myapp:latest
    ports:
      - "8000:8000"

  worker:
    <<: *common-settings         # 共通設定をマージ
    image: myapp:latest
    command: python worker.py
    restart: on-failure          # restartだけ個別に上書き

  scheduler:
    <<: *common-settings         # 共通設定をマージ
    image: myapp:latest
    command: python scheduler.py

# compose.yml（x-プレフィックスでアンカーをファイル先頭に集約）

# --- ここに共通設定をまとめる（x-プレフィックスはDockerが無視する） ---
x-logging: &x-logging
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

x-common-env: &x-common-env
  LOG_LEVEL: info
  TZ: Asia/Tokyo
  APP_URL: http://api:8080

x-base-config: &x-base-config
  restart: unless-stopped
  logging: *x-logging

# --- 各サービスの定義 ---
services:
  web:
    <<: *x-base-config
    image: myapp:latest
    ports:
      - "8000:8000"
    environment:
      <<: *x-common-env
      APP_ROLE: web

  worker:
    <<: *x-base-config
    image: myapp:latest
    command: python worker.py
    environment:
      <<: *x-common-env
      APP_ROLE: worker
      CONCURRENCY: "4"

  scheduler:
    <<: *x-base-config
    image: myapp:latest
    command: python scheduler.py
    environment:
      <<: *x-common-env
      APP_ROLE: scheduler

x-logging: &x-logging
  driver: "json-file"
  options:
    max-size: "50m"    # 1コンテナあたりの最大ログサイズ
    max-file: "5"      # ローテーション世代数（古いものから削除）

services:
  web:
    image: nginx:alpine
    logging: *x-logging

  api:
    image: myapi:latest
    logging: *x-logging

  worker:
    image: myapp:latest
    logging: *x-logging

x-base-env: &x-base-env
  TZ: Asia/Tokyo
  LOG_LEVEL: info
  DB_HOST: db
  DB_PORT: "5432"
  REDIS_HOST: redis

services:
  web:
    image: myapp:latest
    environment:
      <<: *x-base-env
      APP_ROLE: web
      PORT: "8000"
      SESSION_SECRET: "${SESSION_SECRET}"  # .envから注入

  worker:
    image: myapp:latest
    command: python worker.py
    environment:
      <<: *x-base-env
      APP_ROLE: worker
      CONCURRENCY: "4"

# リソース枠の定義（小・大の2種類）
x-resource-small: &x-resource-small
  deploy:
    resources:
      limits:
        cpus: "0.50"
        memory: 512M
      reservations:
        cpus: "0.25"
        memory: 256M

x-resource-large: &x-resource-large
  deploy:
    resources:
      limits:
        cpus: "2.00"
        memory: 2048M
      reservations:
        cpus: "1.00"
        memory: 1024M

services:
  web:
    <<: *x-resource-large    # 大きめのリソース枠を適用
    image: myapp:latest
    ports:
      - "8000:8000"

  worker:
    <<: *x-resource-small    # 小さめのリソース枠を適用
    image: myapp:latest
    command: python worker.py

# NG例: リスト形式のアンカーを << でマージしようとした場合
x-base-env: &x-base-env
  - TZ=Asia/Tokyo
  - LOG_LEVEL=info

services:
  web:
    environment:
      <<: *x-base-env     # エラーになる（シーケンスにマージキーは使えない）
      - PORT=8000

# docker compose up を実行するとエラーが発生する例:
# Error response from daemon: Merge key and its value must be a mapping or
# a list of mappings

# OK例: マッピング形式に変換してから << でマージ
x-base-env: &x-base-env
  TZ: Asia/Tokyo
  LOG_LEVEL: info

services:
  web:
    environment:
      <<: *x-base-env     # 正常にマージされる
      PORT: "8000"         # 個別の値を追加できる
      APP_ROLE: web        # 個別の値を追加できる

# compose.ymlの展開結果を確認する
$ docker compose config

# 特定サービスだけ確認する
$ docker compose config web

# JSON形式で出力する（jqで絞り込みたい場合に便利）
$ docker compose config --format json | jq '.services.web'

# 展開後にサービス数が想定通りか数える
$ docker compose config --format json | jq '.services | keys'

# 実行環境: app-server01.example.internal / Docker Compose v2.24.6
$ docker compose config
name: myproject
services:
  scheduler:
    command: python scheduler.py
    environment:
      APP_ROLE: scheduler
      LOG_LEVEL: info
      TZ: Asia/Tokyo
    image: myapp:latest
    logging:
      driver: json-file
      options:
        max-file: "3"
        max-size: 10m
    networks:
      default: null
    restart: unless-stopped
  web:
    environment:
      APP_ROLE: web
      LOG_LEVEL: info
      PORT: "8000"
      TZ: Asia/Tokyo
    image: myapp:latest
    logging:
      driver: json-file
      options:
        max-file: "3"
        max-size: 10m
    networks:
      default: null
    ports:
      - mode: ingress
        target: 8000
        published: "8000"
        protocol: tcp
    restart: unless-stopped
  worker:
    command: python worker.py
    environment:
      APP_ROLE: worker
      CONCURRENCY: "4"
      LOG_LEVEL: info
      TZ: Asia/Tokyo
    image: myapp:latest
    logging:
      driver: json-file
      options:
        max-file: "3"
        max-size: 10m
    networks:
      default: null
    restart: unless-stopped
networks:
  default:
    name: myproject_default

# "dev" のスペルミス（"dve"）でも起動は成功してしまう
$ docker compose --profile dve up -d
[+] Running 2/2
 ✔ Container myapp-db-1   Started  0.8s
 ✔ Container myapp-app-1  Started  0.6s
# mailpit・adminer はスペルミスのため無言で無視され、起動されない

# compose.yml内のprofiles設定を確認する（jqで絞り込み）
$ docker compose config --format json | jq '[.services | to_entries[] | select(.value.profiles != null) | {name: .key, profiles: .value.profiles}]'
[
  {"name": "adminer", "profiles": ["dev"]},
  {"name": "mailpit", "profiles": ["dev"]}
]

no such service: adminer

# 現在のシェル環境変数を確認する
$ echo $COMPOSE_PROFILES

# シェル環境変数を一時的にクリアして.envファイルの値を使う
$ unset COMPOSE_PROFILES
$ docker compose --profile dev up -d

# またはシェル変数を明示的に上書きして実行する
$ COMPOSE_PROFILES=dev docker compose up -d

services:
  db:
    image: postgres:16
    # profilesなし → 常時起動

  adminer:
    image: adminer:4
    profiles: [dev]
    depends_on:
      - db      # profilesなしのdbへの依存はOK

  # 問題のある構成: backupがdevのadminerに依存している
  backup-report:
    image: myapp/report:latest
    profiles: [backup]
    depends_on:
      - adminer   # adminerはdevプロファイル → backupだけでは起動しない

# backup-reportを起動するには両プロファイルを同時に有効にする必要がある
$ docker compose --profile backup --profile dev up -d

# Compose v2.22以降: required: false でプロファイルサービスへの依存を任意化する
services:
  app:
    image: myapp:latest
    depends_on:
      adminer:
        condition: service_started
        required: false  # adminerが起動していなくてもappの起動を続行する

$ docker compose version
Docker Compose version v2.17.3   # v2.20未満 → includeは使えない

$ docker compose up
validating /home/user/myproject/compose.yml: (root) Additional property include is not allowed

# compose.yml（アンカー + profiles の組み合わせ）

# --- 共通設定（x-プレフィックスでファイル先頭に集約） ---
x-logging: &x-logging
  driver: "json-file"
  options:
    max-size: "50m"
    max-file: "5"

x-base-env: &x-base-env
  TZ: Asia/Tokyo
  LOG_LEVEL: info
  DB_HOST: db

x-base-config: &x-base-config
  restart: unless-stopped
  logging: *x-logging

# --- コアサービス（profiles なし = 本番・開発どちらでも常時起動） ---
services:
  app:
    <<: *x-base-config
    image: myapp:latest
    ports:
      - "8080:8080"
    environment:
      <<: *x-base-env
      APP_ROLE: web
    depends_on:
      db:
        condition: service_healthy

  worker:
    <<: *x-base-config
    image: myapp:latest
    command: python worker.py
    environment:
      <<: *x-base-env
      APP_ROLE: worker
      CONCURRENCY: "4"

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: "${DB_PASS}"
      POSTGRES_DB: appdb
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser"]
      interval: 5s
      timeout: 3s
      retries: 5

  # --- 開発専用サービス（dev プロファイル指定時のみ起動） ---
  mailpit:
    image: axllent/mailpit:latest
    ports:
      - "8025:8025"
      - "1025:1025"
    profiles:
      - dev

  adminer:
    <<: *x-base-config
    image: adminer:latest
    ports:
      - "8081:8081"
    profiles:
      - dev
      - debug

volumes:
  pgdata:

# 本番環境（コアサービスのみ起動）
$ docker compose up -d

# 開発環境（dev プロファイルも有効化）
$ docker compose --profile dev up -d

# 展開後の確認（アンカー展開 + プロファイル適用の最終設定を表示）
$ docker compose --profile dev config

# 開発機の .env ファイル（プロジェクトルートに配置）
COMPOSE_PROFILES=dev
DB_PASS=devpassword

# 本番サーバーの .env ファイル（COMPOSE_PROFILES は記述しない）
DB_PASS=prodpassword

# devとdebugプロファイルを同時に有効化
$ docker compose --profile dev --profile debug up -d

# または COMPOSE_PROFILES 環境変数でカンマ区切り指定
$ COMPOSE_PROFILES=dev,debug docker compose up -d

# compose.yml（本番監視スタックをprodプロファイルで管理）

x-logging: &x-logging
  driver: "json-file"
  options:
    max-size: "50m"
    max-file: "5"

x-base-config: &x-base-config
  restart: unless-stopped
  logging: *x-logging

services:
  app:
    <<: *x-base-config
    image: myapp:latest

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: "${DB_PASS}"
    volumes:
      - pgdata:/var/lib/postgresql/data

  # 本番・ステージング専用の監視スタック（prodまたはstagingプロファイル指定時のみ起動）
  prometheus:
    <<: *x-base-config
    image: prom/prometheus:latest
    profiles: [prod, staging]
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
    ports:
      - "9090:9090"

  grafana:
    <<: *x-base-config
    image: grafana/grafana:latest
    profiles: [prod, staging]
    depends_on:
      - prometheus
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana

volumes:
  pgdata:
  grafana_data:

services:
  app:
    image: myapp:latest

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: "${DB_PASS}"

  # テスト実行時のみ起動するAWS互換環境
  localstack:
    image: localstack/localstack:latest
    profiles: [test]
    ports:
      - "4566:4566"
    environment:
      SERVICES: s3,sqs,dynamodb

  # テスト用HTTPモック
  wiremock:
    image: wiremock/wiremock:latest
    profiles: [test]
    ports:
      - "8081:8080"
    volumes:
      - ./wiremock/mappings:/home/wiremock/mappings

# GitHub Actionsでのテスト実行例（workflowファイルの一部）
- name: Start services with test profile
  run: docker compose --profile test up -d

- name: Wait for db to be healthy
  run: docker compose exec db pg_isready -U myuser

- name: Run integration tests
  env:
    COMPOSE_PROFILES: test
  run: docker compose exec app pytest tests/integration/

- name: Teardown
  run: docker compose --profile test down