Compose ファイルのマージ

Compose では Compose アプリケーションモデルを定義するにあたって、複数の Compose ファイルの利用を可能としています。 これを行った場合、Compose では所定のルールに従って Compose ファイルをマージします。

そのルールの概要は以下のとおりです。

マッピング

YAML の mapping では、存在しないエントリーは追加され、衝突したエントリーはマージされます。

以下の YAML ツリーをマージするものとします。

services:
  foo:
    key1: value1
    key2: value2

services:
  foo:
    key2: VALUE
    key3: value3

結果となる Compose アプリケーションモデルは、以下のような YAML ツリーになります。

services:
  foo:
    key1: value1
    key2: VALUE
    key3: value3

シーケンス

YAML の sequence (順序) は、前の Compose ファイルに後ろのものに対して、値を付け加えてマージします。

以下の YAML ツリーをマージするものとします。

services:
  foo:
    DNS:
      - 1.1.1.1

services:
  foo:
    DNS:
      - 8.8.8.8

結果となる Compose アプリケーションモデルは、以下のような YAML ツリーになります。

services:
  foo:
    DNS:
      - 1.1.1.1
      - 8.8.8.8

例外

シェルコマンド

When merging Compose files that use the services attributes command, entrypoint and healthcheck: test, the value is overridden by the latest Compose file, and not appended.

以下の YAML ツリーをマージするものとします。

services:
  foo:
    command: ["echo", "foo"]

services:
  foo:
    command: ["echo", "bar"]

結果となる Compose アプリケーションモデルは、以下のような YAML ツリーになります。

services:
  foo:
    command: ["echo", "bar"]

ユニークなリソース

Applies to the ports, volumes, secrets and configs services attributes. While these types are modeled in a Compose file as a sequence, they have special uniqueness requirements:

When merging Compose files, Compose appends new entries that do not violate a uniqueness constraint and merge entries that share a unique key.

以下の YAML ツリーをマージするものとします。

services:
  foo:
    volumes:
      - foo:/work

services:
  foo:
    volumes:
      - bar:/work

結果となる Compose アプリケーションモデルは、以下のような YAML ツリーになります。

services:
  foo:
    volumes:
      - bar:/work

Reset value

In addition to the previously described mechanism, an override Compose file can also be used to remove elements from your application model. For this purpose, the custom YAML tag !reset can be set to override a value set by the overridden Compose file. A valid value for attribute must be provided, but will be ignored and target attribute will be set with type's default value or null.

For readability, it is recommended to explicitly set the attribute value to the null (null) or empty array [] (with !reset null or !reset []) so that it is clear that resulting attribute will be cleared.

A base compose.yaml file:

services:
  app:
    image: myapp
    ports:
      - "8080:80"
    environment:
      FOO: BAR

And a compose.override.yaml file:

services:
  app:
    image: myapp
    ports: !reset []
    environment:
      FOO: !reset null

Results in:

services:
  app:
    image: myapp

Replace value

While !reset can be used to remove a declaration from a Compose file using an override file, !override allows you to fully replace an attribute, bypassing the standard merge rules. A typical example is to fully replace a resource definition, to rely on a distinct model but using the same name.

A base compose.yaml file:

services:
  app:
    image: myapp
    ports:
      - "8080:80"

To remove the original port, but expose a new one, the following override file is used:

services:
  app:
    ports: !override
      - "8443:443"

This results in:

services:
  app:
    image: myapp
    ports:
      - "8443:443"

If !override had not been used, both 8080:80 and 8443:443 would be exposed as per the merging rules outlined above.

さらなる情報

For more information on how merge can be used to create a composite Compose file, see Working with multiple Compose files