Compose 設定をファイルとプロジェクト間で共有

共通する設定を共有するため、 Compose は2つの方法をサポートしています。

  1. 複数の Compose ファイルを使い 、Compose ファイル全体を拡張

  2. 「extends」 フィールド で個々のサービスを拡張(Compose ファイルバージョン 2.1 以上)

複数の Compose ファイル

複数の Compose ファイルを使えば、異なる環境や異なるワークフローごとに、 Compose アプリケーションをカスタマイズできます。

複数の Compose ファイルを理解

デフォルトでは、 Compose は2つのファイルを読み込みます。1つは docker-compose.yml で、もう1つはオプションで docker-compose.override.yml ファイルです。習慣として、 docker-compose.yml に基本となる設定を入れます。 上書き(override) ファイルは、その名前が意味する通り、既存のサービスや新しいサービス全体の設定を上書きする設定を含められます。

両方のファイルでサービスが定義されると、 Compose は 設定の追加と上書き に記述してある規則を使い、設定を統合します。

複数の上書きファイルを使う場合や、異なる名前の上書きファイルを使う場合は、 -f オプションを使ってリストやファイルを指定できます。コマンドライン上で指定した順番で、Compose はそれらのファイルを統合します。 -f を使う詳しい情報は docker-compose コマンドリファレンス をご覧ください。

複数の設定ファイルを使う場合、全ファイルのパスが基本となる Compose ファイル( -f で1番目に指定した Comopse ファイル)からの相対パスになるので、注意が必要です。注意が要るのは、上書きするファイルは正しい Comopse ファイルである必要がないためです。サービスの一部を追跡するにあたり、相対パスは複雑で混乱するため、パスを分かりやすくするためには、全てのパスを基本ファイルからの相対パスとして指定すべきです。

使用例

このセクションには、複数の Compose ファイルを使う一般的な使用例が2つあります。異なる環境で Compose アプリを変えるものと、Compose アプリに対して管理用タスクを実行するものです。

異なる環境

複数のファイルを使う一般的な利用例は、開発用 Compose アプリを本番のような環境用(本番や、ステージングや、CI など)に変える場合です。環境の違いに対応するには、 Comopse 設定を複数の異なるファイルに分割できます。

各サービスに対する標準的な設定を定義する ベースファイル(base file) から始めましょう。

docker-compose.yml

web:
  image: example/my_web_app:latest
  depends_on:
    - db
    - cache

db:
  image: postgres:latest

cache:
  image: redis:latest

この例にある開発用の設定では、ホスト上のいくつかのポートを公開し、ボリュームとしてコードをマウントし、web イメージを構築します。

docker-compose.override.yml

web:
  build: .
  volumes:
    - '.:/code'
  ports:
    - 8883:80
  environment:
    DEBUG: 'true'

db:
  command: '-d'
  ports:
    - 5432:5432

cache:
  ports:
    - 6379:6379

docker-compose up を実行すると、上書きファイルを自動的に読み込みます。

これで、この Compose アプリを本番環境でも使えるようになりました。あとは、他の上書きファイル(異なる git リポジトリに保管されるかもしれませんし、他のチームによって管理されるかもしれません)を作成します。

docker-compose.prod.yml

web:
  ports:
    - 80:80
  environment:
    PRODUCTION: 'true'

cache:
  environment:
    TTL: '500'

この本番用 Compose ファイルでデプロイするには、次のように実行します。

$ docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

これは docker-compose.ymldocker-compose.prod.yml (開発用の設定 docker-compose.override.yml ではありません)の設定を使い、設定された3つのサービスすべてをデプロイします。

Compose を本番環境で使うための情報は 本番環境 をご覧ください。

管理用タスク

他の一般的な利用例は、 Compose アプリ内のサービスに対して、一時的または管理的なタスクを1つまたは複数実行する場合です。

docker-compose.yml から始めます。

web:
  image: example/my_web_app:latest
  depends_on:
    - db

db:
  image: postgres:latest

docker-compose.admin.yml には、データベースの 出力(export) やバックアップを実行する新しいサービスを追加します。

dbadmin:
  build: database_admin/
  depends_on:
    - db

docker-compose up -d を実行して、通常の環境を起動します。データベースのバックアップを実行するには、 docker-compose.admin.yaml も同様に含めます。

$ docker-compose -f docker-compose.yml -f docker-compose.admin.yml \
  run dbadmin db-backup

サービスの 拡張(extends)

注釈

extends (拡張)キーワードは、初期の Compose ファイル形式から Compose ファイルバージョン 2.1 ( v2 の extends を参照 )までサポートされていましたが、Compose バージョン 3.x ではサポートされていません。 バージョン 3 概要 でのキー追加と削除に加え、 アップグレードの仕方 をご覧ください。将来の形式で同じように extends をサポートする可能性についての議論は、 moby/moby#31101 をご覧ください。 extends キーワードは、 docker-compose バージョン 1.27 以上から含まれるようになりました。

Docker Compose の extends キーワードは、共通の設定を異なるファイル間で共有できます。また、全く異なるプロジェクトでさえも共有できます。サービスの 拡張(extends) は、共通する設定オプション群を持つ、複数のサービスがある場合に役立ちます。 extends を使えば、1箇所で共通するサービスのオプション群を設定できますし、どこからでも参照できます。

注意点として、 volumes_fromdepends_on は、 extends を使うサービス間で決して共有されません。これは潜在的な依存関係を防ぐために、例外終了します。つまり、 volumes_from は常にローカルで定義しなくてはいけません。これにより、現在のファイルを読み込む時に、サービスの依存関係が明確に表示されます。また、これら(ボリューム)をローカルで定義するため、参照しているファイルを変更したとても、一切影響がありません。

extends 設定の理解

docker-compose.yml であらゆるサービスを定義する時に、次のように、他のサービスを拡張するよう宣言できます。

services:
  web:
    extends:
      file: common-services.yml
      service: webapp

これは Compose に対し、 common-services.yml ファイル内で定義された webapp サービスの設定を再利用するように命令します。 common-services.yml は、このような内容を想定しています。

services:
  webapp:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - "/data"

このようにすると、 docker-compose.yml 内の web 以下で、同じ buildportsvolumes 設定を定義した場合と結果が完全に同じになります。

docker-compose.yml 内では、さらに続けてローカルの設定を定義(あるいは再定義)できます。

services:
  web:
    extends:
      file: common-services.yml
      service: webapp
    environment:
      - DEBUG=1
    cpu_shares: 5

  important_web:
    extends: web
    cpu_shares: 10

また、 他のサービスを記述し、 web サービスに対してサービスをリンクできます。

services:
  web:
    extends:
      file: common-services.yml
      service: webapp
    environment:
      - DEBUG=1
    cpu_shares: 5
    depends_on:
      - db
  db:
    image: postgres

利用例

複数のサービスが共通の設定を持つ場合、個々のサービスを拡張するのが便利です。以下の例にある Compose アプリは、 ウェブ(web) アプリケーションと キュー ワーカ(queue worker) という、2つのサービスがあります。どちらのサービスも、同じコードベースを使い、多くの設定オプションを共有します。

common.yml 内には、共通する設定を定義します。

services:
  app:
    build: .
    environment:
      CONFIG_FILE_PATH: /code/config
      API_KEY: xxxyyy
    cpu_shares: 5

docker-compose.yml 内には、共通する設定を使う具体的なサービスを定義します。

services:
  webapp:
    extends:
      file: common.yml
      service: app
    command: /code/run_web_app
    ports:
      - 8080:8080
    depends_on:
      - queue
      - db

  queue_worker:
    extends:
      file: common.yml
      service: app
    command: /code/run_worker
    depends_on:
      - queue

設定情報の追加と上書き

Compose はオリジナルのサービスにある設定情報を、ローカルの設定情報へとコピーします。設定情報のオプションがオリジナル サービスとローカル サービスの両方で定義されている場合、ローカルの値は「 置き換え(replaces) 」られるか、オリジナルの値が「 拡張(extends) 」されます。

imagecommandmem_limit のようにオプションが単一の値を持つ場合、古い値を新しい値で置き換えます。

オリジナル サービス:

services:
  myservice:
    # ...
    command: python app.py

ローカル サービス:

services:
  myservice:
    # ...
    command: python otherapp.py

結果:

services:
  myservice:
    # ...
    command: python otherapp.py

portsexposeexternal_linksdnsdns_searchtmpfs のような 複数の値を持つオプション では、Compose は両方の値を連結します。

services:
  myservice:
    # ...
    expose:
      - "3000"

ローカル サービス:

services:
  myservice:
    # ...
    expose:
      - "4000"
      - "5000"

結果:

services:
  myservice:
    # ...
    expose:
      - "3000"
      - "4000"
      - "5000"

environmentlabelsvolumesdevices では、 Compose はローカルで定義した値を優先しながら、全体を「 統合(merge) 」します。 environmentlabels では、環境変数の値やラベル名で明示された値が使われます。

オリジナル サービス:

services:
  myservice:
    # ...
    environment:
      - FOO=original
      - BAR=original

ローカル サービス:

services:
  myservice:
    # ...
    environment:
      - BAR=local
      - BAZ=local

結果:

services:
  myservice:
    # ...
    environment:
      - FOO=original
      - BAR=local
      - BAZ=local

voluemsdevices のエントリは、コンテナ内にマウントするパスを使う場合に 統合(merge) されます。

オリジナル サービス:

services:
  myservice:
    # ...
    volumes:
      - ./original:/foo
      - ./original:/bar

ローカル サービス:

services:
  myservice:
    # ...
    volumes:
      - ./local:/bar
      - ./local:/baz

結果:

services:
  myservice:
    # ...
    volumes:
      - ./original:/foo
      - ./local:/bar
      - ./local:/baz

Compose ドキュメント

参考

Share Compose configurations between files and projects

https://docs.docker.com/compose/extends/