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

この記事のポイント

・YAMLアンカー（&）でブロックに名前を付け、エイリアス（*）で複数サービスから参照できる
・<<（マージキー）でアンカーを展開し、個別サービスの設定にマージできる
・Extension fields（x-プレフィックス）でアンカー定義をファイル先頭に集約して管理できる
・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'

# 実行環境: 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