エクステンション

エクステンションは Compose ファイルをより適切かつ効率的に構築するために利用できます。

トップレベル要素として x- をプリフィックスとする要素を記述します。これによって設定内容がモジュール化され、再利用できるようになります。 Compose は x- で始まるフィールドをすべて無視します。認識不能なフィールドであっても Compose がエラー扱いとせずに無視するという、唯一の例外的処理です。

エクステンションはアンカーおよびエイリアスと合わせて利用可能です。

They also can be used within any structure in a Compose file where user-defined keys are not expected. Compose uses those to enable experimental features, the same way browsers add support for custom CSS features

例１

x-custom:
  foo:
    - bar
    - zot

services:
  webapp:
    image: example/webapp
    x-foo: bar

service:
  backend:
    deploy:
      placement:
        x-aws-role: "arn:aws:iam::XXXXXXXXXXXX:role/foo"
        x-aws-region: "eu-west-3"
        x-azure-region: "france-central"

例２

x-env: &env
  environment:
    - CONFIG_KEY
    - EXAMPLE_KEY

services:
  first:
    <<: *env
    image: my-image:latest
  second:
    <<: *env
    image: another-image:latest

この例において環境変数はどのサービスにも記述されていません。 x-env というエクステンション項目として含まれているだけです。ここから環境変数のフィールドを含んだ新たなノードが生成されます。 YAML のアンカー形式 &env は 2 つのサービス内において、エクステンションの値を参照する *env という記述を行っています。

例３

x-function: &function
 labels:
   function: "true"
 depends_on:
   - gateway
 networks:
   - functions
 deploy:
   placement:
     constraints:
       - 'node.platform.os == linux'
services:
 # Node.js がノード (ホスト) に関する OS 情報を提供
 nodeinfo:
   <<: *function
   image: functions/nodeinfo:latest
   environment:
     no_proxy: "gateway"
     https_proxy: $https_proxy
 # エコーバックのために `cat` を利用、実行がより速い関数を採用
 echoit:
   <<: *function
   image: functions/alpine:health
   environment:
     fprocess: "cat"
     no_proxy: "gateway"
     https_proxy: $https_proxy

サービス nodeinfo と echoit はともに x-function というエクステンションを利用しており、&function というアンカーとして参照しています。その上で特定イメージと環境変数を設定しています。

例４

YAML マージの記法を用いると、複数のエクステンションを共有することが可能となります。また必要に応じて追加の属性を上書き指定することもできます。

x-environment: &default-environment
  FOO: BAR
  ZOT: QUIX
x-keys: &keys
  KEY: VALUE
services:
  frontend:
    image: example/webapp
    environment:
      << : [*default-environment, *keys]
      YET_ANOTHER: VARIABLE

メモ
YAML マージはマッピングに対してのみ適用できるものであり、シーケンスには適用できません。
上の例において環境変数は FOO: BAR というマッピング形式の文法を使って宣言しています。シーケンス形式の文法 - FOO=BAR を使った場合には、フラグメントを含めてしまうと不正な記述となります。

Informative historical notes

This section is informative. At the time of writing, the following prefixes are known to exist:

Prefix	Vendor/Organization
docker	Docker
kubernetes	Kubernetes

Specifying byte values

Values express a byte value as a string in {amount}{byte unit} format: The supported units are b (bytes), k or kb (kilo bytes), m or mb (mega bytes) and g or gb (giga bytes).

Specifying durations

Values express a duration as a string in the form of {value}{unit}. The supported units are us (microseconds), ms (milliseconds), s (seconds), m (minutes) and h (hours). Values can combine multiple values without separator.

  10ms
  40s
  1m30s
  1h5m30s20ms