Compose Specification(仕様)

Compose ファイルとは、Docker アプリケーション用のサービス、ネットワーク、ボリュームを定義した YAML ファイル です。最新かつ推奨される Compose ファイル形式のバージョンは、 Compose Specification で定義されています。Compose の仕様は、古いバージョン 2.x と 3.x を1つにまとめ、各フォーマット間が 持っている属性(property) を統合したものが、 Compose 1.27.0 以上 から実装されています。

この文章の状態

このドキュメントで定めるのは、複数コンテナのアプリケーションを定義するために使う Compose ファイル形式についての仕様です。このドキュメントの配布に制限はありません。

このドキュメントにおけるキーワード「 しなければならない(MUST) 」「 してはならない(MUST NOT) 」「 することになる(SHALL) 」「 することはない(SHALL NOT) 」「 する必要がある(SHOULD) 」「 しないほうがよい(SHOULD NOT) 」「 推奨される(RECOMMENDED) 」「 してもよい(MAY) 」「 選択できる(OPTIONAL) 」の解釈に対する説明は RFC 2119 にあります。

動作条件とオプションの属性

Compose 仕様には、Linux カーネル固有で設定オプションを公開するような、ローカルの OCI コンテナ ランタイムを対象に設計された 属性(property) を含みます。しかし、いくつかの Windows コンテナ固有の属性だけでなく、同様にクラスタ上でのリソース配置、複製したアプリケーションの分散と 拡張性(scalability) といった、クラウド プラットフォームに関連する機能もあります。

私たちが認識しているのは、 全ての 属性をサポートする Compose の実装は一切期待されておらず、また、いくつかの属性はプラットフォームに依存し、実行時にのみ確認できることです。バージョン化された枠組みの定義とは、 Compose ファイル形式が設計された docker-compose ツールによって確立されたもので、 Compose ファイル内でサポートしている属性を制御するためでした。そのため、エンドユーザに属する実装が、実際に行えるかどうかを保証しません。

この仕様が定義するのは、想定している設定情報の構文と挙動ですが、特に注記がなければ、これらをサポートするかどうかは 選択可能(OPTIONAL) です。

Compose の実装では、Compose ファイルで サポート外(unsupported) の属性を解析しようとすると、ユーザに対して警告を する必要があります(SHOULD) 。私たちが推奨する実装は、以下の実行モデルのサポートです:

  • デフォルト:サポート外の属性はユーザに警告するが、それらを無視

  • 厳密(strict) :サポート外の属性をユーザに警告し、compose ファイルを 拒否(reject)

  • 緩い(loose) :サポート外および未知の属性を無視する(未知の属性とは、仕様で定義されていない実装によって作成された場合)

Compose のアプリケーション モデル

Compose の 仕様(specification) とは、 プラットフォームに依存しない(platform-agnostic) コンテナを基礎とするアプリケーションを定義できるようにするための仕様です。このアプリケーションの設計では、複数のコンテナが相互に動作できるよう、適切にリソースと通信チャネルを確保します。

アプリケーションの 計算コンポーネント(computing component) は、 サービス(services) によって定義されます。サービスとはプラットフォーム上に実装される抽象的な概念で、同じコンテナ イメージ(と設定)を何度も実行できるものです。

サービスは ネットワーク(networks) を通して相互に通信します。この仕様では、ネットワークとは プラットフォーム機能の抽象化(platform capability abstraction) であり、サービス内のコンテナが一緒に接続できるよう IP 経路を確立します。下位のレベルでは、プラットフォーム固有のネットワーク機能のオプションを、ネットワークの定義内でグループ化されていますが、いくつかのプラットフォームでは部分的に実装する 可能性があります(MAY)

サービスは ボリューム(volumes) 内に 保持するデータ(persistent data) の保存と共有をします。仕様では、グローバルのオプションを使い、上位レベルのファイルシステムへマウントするように、保持するデータを記述します。実際のプラットフォーム固有の実装詳細は、ボリューム定義内にグループ化されていますが、いくつかのプラットフォームでは部分的に実装する 可能性があります(MAY)

いくつかのサービスは、ランタイムやプラットフォームに依存する 設定情報(configuration) データを必要とします。このため、仕様では 設定情報(configs) という、専用の概念を定義しています。サービス用コンテナの視点からすると、コンテナ内にファイルをマウントするため、 :ruby`設定情報 <configs>` はボリュームに似ています。しかし、実際の定義では、このタイプで抽象化されたプラットフォーム固有のリソースとサービスを含みます。

機微情報(secrets) は、セキュリティの考慮なしに公開 しないほうがよい(SHOULD NOT) (細心の注意を払うべき)センシティブなデータのための、特別な設定情報です。機微情報はサービス内のコンテナに対してファイルをマウントして利用できます。プラットフォーム固有の機微データを提供するリソースがある場合にも、Compose 仕様内で明確な概念と定義に値するための、十分な指定があります。

volumes、configs、secret 内を区別すると、サービスレベルでも同等の抽象化された実装が行えますが、プラットフォーム固有のリソースにおける明確なデータ仕様用途に対しては、その(固有のリソースに)特化した設定で扱います。

プロジェクト(project) は、個々のアプリケーション仕様をプラットフォーム上に展開したものです。プロジェクトの名前は、リソースを一緒に扱うグループのために使われたり、他のアプリケーションとは分離されたり、同じ Compose 仕様のアプリケーションでありながら、特定のパラメータを持つ他のものをインストールします。プラットフォーム上の Compose 実装は、プロジェクトごとにリソース名を前につけ、ラベル com.docker.compose.project付けなければいけません。(MUST)

プロジェクト名は、トップレベルの name 属性で明示できます。Compose 実装では、ユーザが任意のプロジェクト名の指定と、この名前を上書きできるように しなければなりません(MUST) 。つまり、異なる名前を渡すだけで、同じ compose.yaml ファイルを元にしながら、変更のない同じ構造を2つデプロイできます。

説明例

以下の例では、具体的なアプリケーション例を使い Compose 仕様の概要を説明します。この例は規範的ではありません。

フロントエンド ウェブアプリケーションとバックエンド サービスに分かれたアプリケーションを考えます。

フロントエンドは、基盤によって管理されている HTTP 設定ファイルを使い、実行時に設定をします。設定とは、外部でのドメイン名と、プラットフォームの安全な 機微情報(シークレット) ストアから投入された HTTPS サーバ証明書です。

バックエンドは 持続型ボリューム(persistent volume) にデータを保管します。

どちらのサービスも隔離された後方ネットワーク上で互いに通信します。一方、フロントエンドも前方ネットワークに接続し、外部から使うためにポート 443 を公開します。

Compose 例

このアプリケーション例では、以下のパーツを組み込んでいます。

  • 2つのサービス、 Docker イメージを元にしている: webappdatabase

  • 1つの機微情報(HTTPS 証明書)、フロントエンドに投入

  • 1つの設定情報(HTTP)、フロントエンドに投入

  • 1つの持続型ボリューム、バックエンドに 取り付け(attached)

  • 2つのネットワーク

services:
  frontend:
    image: awesome/webapp
    ports:
      - "443:8043"
    networks:
      - front-tier
      - back-tier
    configs:
      - httpd-config
    secrets:
      - server-certificate

  backend:
    image: awesome/database
    volumes:
      - db-data:/etc/data
    networks:
      - back-tier

volumes:
  db-data:
    driver: flocker
    driver_opts:
      size: "10GiB"

configs:
  httpd-config:
    external: true

secrets:
  server-certificate:
    external: true

networks:
  # これらオブジェクトを定義するには、存在するだけで十分
  front-tier: {}
  back-tier: {}

この例では、 volumes 、 configs 、 secrets 間の違いを示します。これらはすべて、サービス用コンテナに対してファイルやディレクトリをマウントしているように見えますが、ボリュームのみ読み込みと書き込みの作業ができます。secrets と configs は読み込み専用です。実際の基盤にしたがってボリューム管理を調整するには、ボリュームの設定情報によって、ボリュームドライバを選択したり、ドライバにオプションを渡せたりします。configs と secrets はプラットフォーム上のサービスに依存します。また、これらはアプリケーションのライフサイクルとして管理されないため、 external と宣言します。つまり、 Compose の実装では、プラットフォーム固有の 調査(lookup) メカニズムを使用して、ランタイム値を取得します。

Compose ファイル

Compose ファイルとは YAML ファイルであり、 version (非推奨)、 services (必須)、 networksvolumesconfigssecrets を定義します。作業ディレクトリ内での、Compose ファイルのデフォルトのパスは compose.yaml (推奨)か compose.yml です。Compose 実装は、下位互換性のために docker-compose.yamldocker-compose.yml もサポート すべきです。(SHOULD) 両方のファイルが存在する場合、 Compose 実装は標準である compose.yaml を優先 しなければいけません(MUST)

アプリケーション モデルを定義するために、複数の Compose ファイルを一緒に組み合わせられます。YAML ファイルの結合にあたっては、ユーザによって指定された Compose ファイルの順番に基づき、 YAML 要素の追加と上書きを実装 しなければいけません(MUST) 。単一の属性と マップ(map) は、最上位の Compose ファイルによって上書きされます。また、リストでは追加されたものを統合します。統合される補完ファイルが他のフォルダ内に置かれている場合、常に相対パスは 1つめの Compose ファイルの親ディレクトリを基準に解決 しなければいけません(MUST)

いくつかの Compose ファイル要素は、単一文字列か複雑なオブジェクトとして表記できるため、統合する場合は拡張形式を適用 しなければいけません(MUST)

profiles

profiles によって、様々な用途や環境にあわせて Compose アプリケーション モデルを調整できます。Compose 実装は、ユーザがアクティブな profiles のセットを定義できるように すべきです(SHOULD) 。厳密な仕組みは個別の実装次第であり、コマンドラインのフラグ、環境変数等も 含められます(MAY)

サービスのトップレベル要素は、 profiles 属性をサポートし、 profiles 名の一覧を定義します。 profiles 属性セットの無いサービスは、常に有効に しなければいけません(MUST)profiles に一致するアクティブな profiles が存在しなければ、サービスがコマンドで対象を明示されていない限り、サービスは Compose 実装によって無視 されなければいけません(MUST) 。その場合、その porifles をアクティブな profiles のセットに追加 しなければいけません(MUST) 。これ以外すべてのトップレベル要素は profiles の影響を受けず、常に機能します。

他のサービスへの参照( linksextends 、共有リソース構文 service:xxx )は、アクティブな profiles によって無視されたコンポーネントを自動的に有効化 してはいけません(MUST) 。そのかわり、 Compose 実装はエラーを 返さなければなりません(MUST)

説明例

services:
  foo:
    image: foo
  bar:
    image: bar
    profiles:
      - test
  baz:
    image: baz
    depends_on:
      - bar
    profiles:
      - test
  zot:
    image: zot
    depends_on:
      - bar
    profiles:
      - debug
  • profiles を有効にしないで構文解析された Compose アプリケーション モデルには、 foo サービスしか含みません。

  • profiles で test を有効化する場合、モデルに含まれるサービスは test profile によって有効化される barbaz のサービスと、サービス foo は常に有効です。

  • profiles で debug を有効化する場合、モデルに含まれるサービスは foozot の両方ですが、 barbazzotdepends_on 条件があるようなモデルも無効です。

  • profiles debugtest を有効化する場合、モデルには全てのサービスを含みます。つまり、 foobarbazzot です。

  • bar を起動するサービスとして明示して Compose 実装を実行する場合、「ユーザによって」 test profile を有効にしていない場合でも、bartst をサービスとして実行します。

  • baz を起動するサービスとして明示して Compose 実装を実行する場合、サービス baztest profile が有効になり、 depends_on 強制によって bar も実行されます。

  • zot を起動するサービスとして明示して Compose 実装を実行する場合、 zotbar に共通する profiles が一覧にないため、 zotdepends_on 強制についてのモデルは無効になります。

  • zot を起動するサービスとして明示し、 profile test を有効にして Compose 実装を実行する場合、profile debug が自動的に有効になり、サービス zotbar の両方は依存関係があるため、 bar が実行されます。

version トップレベル要素

トップレベルの version 属性は、下位互換性のために仕様で定義されていますが、情報を参考にするためだけです。

Compose 実装は、 Compose ファイルの検証にあたり、正確なスキームを選ぶためにこの version を使う べきではありません(SHOULD NOT) 。そうではなく、 Compose ファイルが設計された時点での最新のスキーマを優先すべきです。

Comopse 実装は Compose ファイルを完全に構文解析できるかどうかを検証 すべきです(SHOULD) 。もしも一部に未知のフィールドがある場合、通常、その Compose ファイルは新しいバージョンの仕様によって定義されたフィールドで書かれているため、 Compose 実装はユーザに警告 すべき(SHOULD) です。Compose 実装は未知のフィールドを無視するオプションを 提供してもよいです(MAY) (「 loose 」モードによって定義されます)。

name トップレベル要素

トップレベルの name 属性は、ユーザが明示的に設定しない場合に使われる、プロジェクト名として仕様で定義されています。Compose 実装では、ユーザこの名前を上書きする方法を提供 しなければいけません(MUST) 。また、トップレベルの name 要素が設定されない場合、デフォルトのプロジェクト名を 決定する(compute) 仕組みを定義 すべきです(SHOULD)

トップレベルの name や何らかの特別な仕組みによってプロジェクト名が定義される場合は、ただちに 補完 で変数展開したり、環境変数 COMPOSE_PROJECT_NAME として解決できるように すべき(MUST) です。

services:
  foo:
    image: busybox
    environment:
      - COMPOSE_PROJECT_NAME
    command: echo "I'm running ${COMPOSE_PROJECT_NAME}"

services トップレベル要素

サービス(service) とはアプリケーション内の 計算資源(computing resource) に対する抽象的な定義であり、他の コンポーネント(構成要素) からは独立して スケール(拡大・縮小) や置き換えができます。サービスはコンテナの集まりによって支えられ、 複製の要件(replication requirements)配置の制約(placement constraints) に照らしながらプラットフォームによって実行されます。コンテナによって支えられているサービスは、 Docker イメージとランタイム引数のセットで定義されます。サービス内のすべてのコンテナは、これらの引数により完全に同じように作成されます。

Compose ファイルでは、 マップ(map) として services ルート要素を宣言する 必要があります(MUST) 。マップとは、キーがサービス名を表す文字列で、値がサービスを定義します。サービス定義には、サービス用に起動する各コンテナに適用する設定情報も含みます。

各サービスには build セクションも 含めてもよく(MAY) 、サービス用の Docker イメージの作成方法を定義します。Compose 実装は、このサービス定義を使っての Docker イメージの構築をサポート してもよいです(MAY) 。build セクションを実装しない場合、このセクションを無視 すべきで(SHOULD) すが、Compose ファイルでは有効のままにする 必要があります(MUST)

build のサポートは、 Compose 仕様において 選択できる(OPTIONAL) 項目です。これは、 build サポート ドキュメントに詳細な説明があります。

各サービスは、サービスを実行する ランタイム制約(runtime constraint) と必要条件を定義します。 deploy セクションは、これらの制約をグループ化できます。さらに、プラットフォームは利用可能なリソースと、コンテナが必要なリソースを一致させるよう、 デプロイ方針(deployment strategy) を調整できるようにします。

deploy のサポートは Compose 仕様において 選択できる(OPTIONAL) 項目です。これは deployment サポート ドキュメントに詳細な説明があります。deploy セクションを実装しない場合、このセクションを無視 すべきで(SHOULD) すが、Compose ファイルでは有効のままにする 必要があります(MUST)

build

build 、はソースからコンテナ イメージを作成するための 構築情報(build configuration) を指定します。これは build サポート

blkio_config

blkio_config が定義するのは、サービスに対するブロック IO を制限するオプション設定の集まりです。

services:
  foo:
    image: busybox
    blkio_config:
       weight: 300
       weight_device:
         - path: /dev/sda
           weight: 400
       device_read_bps:
         - path: /dev/sdb
           rate: '12mb'
       device_read_iops:
         - path: /dev/sdb
           rate: 120
       device_write_bps:
         - path: /dev/sdb
           rate: '1024k'
       device_write_iops:
         - path: /dev/sdb
           rate: 30
device_read_bps、 device_write_bps

特定のデバイス上で、読み書き処理に対する制限を、1秒あたりのバイト数で指定します。リスト内の各項目は、2つのキーを持つ 必要があります(MUST)

  • path :影響があるデバイスへのシンボリック パスを定義

  • rate :バイト数を表す整数値、あるいは、バイト値を表現する文字列のどちらか

device_read_iops、 device_write_iops

特定のデバイス上で、読み書きに対する制限を、1秒あたりの処理回数で指定します。リストの各項目は、2つのキーを持つ 必要があります(MUST)

  • path :影響があるデバイスへのシンボリック パスを定義

  • rate :1秒あたりに許可する処理回数を、整数値で示す

weight

他のサービスと比較し、このサービスに割り当てる帯域の比率を調整します。 10 から 1000 までの整数値をとり、デフォルトは 500 になります。

weight_device

デバイスに対する帯域を微調整します。各アイテムの値は2つのキーを持つ必要があります。リストの各項目は、2つのキーを持つ 必要があります(MUST)

  • path :影響があるデバイスへのシンボリック パスを定義

  • weight : 10 から 1000 までの整数値

cpu_count

cpu_count はサービス用コンテナで利用できる CPU の下図を定義します。

cpu_percent

利用可能な CPU で使用する割合を定義します。

cpu_shares

cpu_shares はサービス用コンテナに対し、他のコンテナからの相対 CPU ウエイトを(整数値で)定義します。

cpu_period

プラットフォームが Linux カーネルを基盤としている場合、 cpu_period は CPU CFS ( Complete Fair Scheduler , 完全公平スケジューラ ) 期間の設定を Compose 実装が行えるようにします。

cpu_quota

プラットフォームが Linux カーネルを基盤としている場合、 cpu_period は CPU CFS ( Complete Fair Scheduler , 完全公平スケジューラ ) クォータの設定を Compose 実装が行えるようにします。

cpu_rt_runtime

cpu_rt_runtime は、リアルタイム スケジューラをサポートするプラットフォームに対し、 CPU 割り当てパラメータを設定します。マイクロ秒の単位を整数値で指定するか、 ref:期間 <compose-spec-specifying-durations> のどちらかで指定します。

cpu_rt_runtime: '400ms'
cpu_rt_runtime: 95000`

cpu_rt_period

cpu_rt_period は、リアルタイム スケジューラをサポートするプラットフォームに対し、 CPU 割り当てパラメータを設定します。マイクロ秒の単位を整数値で指定するか、 ref:期間 <compose-spec-specifying-durations> のどちらかで指定します。

cpu_rt_period: '1400us'
cpu_rt_period: 11000`

cpus

非推奨: :ref:`deploy.reservations.cpu <compose-file-deploy-cpus>` をお使います。

cpu はサービス用コンテナに割り当てる (ことが期待できる仮想の)CPU 数を定義します。

cpuset

cpuset は実行を許可する CPU を明示する定義です。 0-3 のような範囲、または 0,1 のようなリストです。

cap_add

cap_add は文字列でコンテナ ケーパビリティ の追加を指定します。

cap_add:
  - ALL

cap_drop

cap_add は文字列でコンテナ ケーパビリティ を落とす指定をします。

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup_parent

cgroup_parent は、コンテナに対する親 cgroupオプションで(OPTIONAL) 指定できます。

cgroup_parent: m-executor-abcd

command

command はコンテナ イメージによって宣言済み(例: Dockerfile の CMD )のデフォルト コマンドを上書きします。

command: bundle exec thin -p 3000

コマンドはリストにもでき、 Dockerfile の書き方に似ています。

command: [ "bundle", "exec", "thin", "-p", "3000" ]

configs

configs は、サービスごとの configs 設定情報(configuration) を元に、サービスごとの設定へのアクセスを許可します。2つの異なる構文形式がサポートされています。

Compose の実装は、プラットフォーム上に 設定(config) が存在しないか、この Compose ファイルの configs セクションで定義されていなければ、エラーを 報告しなければいけません(MUST)

configs を定義する構文は2つあります。この実装に従い続ける限り、実装は両方の構文をサポート しなければいけません(MUST) 。また、同じドキュメント内で、短い構文と長い構文の、両方の使用を許可するように実装 しなければいけません(MUST)

短い構文

短い構文(short syntax) 形式では、 設定名(config name) のみ指定します。これにより、コンテナは 設定情報(config) にアクセスできるようになり、コンテナ内で /<設定名> としてマウントします。ソース名とマウントポイント先は、どちらも 設定情報(config) の名前です。

以下の例では短い構文を使い、 redis サービスに対して my_configmy_other_config 設定情報へのアクセスを許可します。 my_config の値は ./my_config.txt ファイルの中に設定されます。そして、 my_other_config は外部リソースとして定義されており、つまり、既にプラットフォーム内で定義済みを意味します。外部の設定情報が存在しなければ、デプロイは 失敗しなければいけません(MUST)

services:
  redis:
    image: redis:latest
    configs:
      - my_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

長い構文

長い構文により、より詳細な 設定情報(config) をサービスのタスク コンテナ内で作成できるようになります。

  • source :プラットフォーム内に存在する設定情報の名前

  • target :サービス用タスクコンテナ内にマウントする、ファイルのパスと名前

  • uidgid :サービス用タスクコンテナ内にマウントする、設定ファイルを所有する UID か GID を示す整数

  • mode :サービス用タスクコンテナ内にマウントする、ファイルに対する パーミッション を8進数で指定。デフォルト値は誰でも読み込み可能( 0444 )。書き込み可能なビットは 無視しなければいけません(MUST) 。実行可能ビットは設定できます。

以下の例は my_config という名前の設定情報をコンテナ内の redis_config に設定し、モードを 0440 (グループ読み込み可能)とし、ユーザとグループを 103 に設定します。この redis サービスは、 my_other_config 設定に対してアクセスできない。

services:
  redis:
    image: redis:latest
    configs:
      - source: my_config
        target: /redis_config
        uid: "103"
        gid: "103"
        mode: 0440
configs:
  my_config:
    external: true
  my_other_config:
    external: true

サービスに対し、複数の設定情報へのアクセスを許可できます。また、長い形式と短い形式を混在できます。

container_name

container_name は、デフォルトで生成される名前ではなく、任意のコンテナ名を指定する文字列です。

container_name: my-web-container

Compose ファイルで container_name を指定している場合、Compose 実装は、コンテナ1つよりも多くにサービスをスケール させてはいけません(MUST NOT)

指定するには、 container_name は正規表現の形式 [a-zA-Z0-9][a-zA-Z0-9_.-]+従うべきです(SHOULD)

_compose-spec-credential_spec: credential_spec --------------------

credential_spec は、マネージド サービス アカウント用の 認証情報仕様(credential spec) を設定します。

Windows コンテナーを使うサービスをサポートする Compose 実装では、credential_spec のために file:registry: プロトコルのサポートが 必須です(MUST) 。また、 Compose 実装では、任意の利用例に応じた追加プロトコルをサポート してもよいです(MAY)

credential_specfile://<ファイル名>registry://<値の名前> の形式にする必要があります。

credential_spec:
  file: my-credential-spec.json

registry: を使う場合、 デーモンのホスト上にある Windows レジストリから、 認証情報仕様(credential spec) を読み込みます。レジストリの値は、以下の場所に置く必要があります。

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

以下の例は、レジストリ内の my-credential-spec という名前の値から、 認証情報仕様(credential spec) を読み込みます。

credential_spec:
  registry: my-credential-spec

gMSA 設定情報の例

サービスに対して gMSA 認証情報を設定する場合、必要なのは以下の例にあるように、 config で認証情報仕様を指定するだけです。

services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json|

depends_on

depends_on はサービス間の起動順番と終了順番の依存関係を表します。

短い構文

短い構文の形式は、依存関係があるサービス名のみ指定します。サービスの依存関係によって、次の挙動をもたらします。

  • Compose 実装は、依存関係のある順番でサービスを作成する 必要があります(MUST) 。以下の例では、 web の前に dbredis が作成されます。

  • Comopse 実装は、依存関係のある順番でサービスを削除する 必要があります(MUST) 。以下の例では、 dbredis の前に web が削除されます。

簡単な例:

services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

Compose 実装は、依存先のサービスが起動する前に、依存元のサービスを確実に 起動しなくてはいけません(MUST) Compsoe 実装は、依存先のサービスが起動する前に、依存元のサービスを「 待機状態(ready) 」になるまで待つ ことができます(MAY)

長い構文

長い構文の形式は、短い形式では指定できない追加のフィールドも設定可能になります。

  • condition :依存関係を満たしているとみなす状態

    • service_started :前述の短い構文のものと同等

    • service_healthy :依存先のサービスを起動する前に、依存元のサービスが「 正常(healthy) 」( healthcheck で示す)な状態を指定

    • service_completed_successfully :依存先のサービスを起動する前に、依存元のサービスは正常に実行済みの状態を指定

サービスの依存関係は、次のような挙動になります。

  • Compose 実装は、依存関係のある順番でサービスを作成する 必要があります(MUST) 。以下の例では、 web の前に dbredis が作成されます。

  • Compose 実装は、依存元のサービスが service_healthy で示すヘルスチェックを通過するまで待つ 必要があります(MUST) 。以下の例では、 db が 「 正常(healthy) 」な状態になった後、 web が作成されます。

  • Comopse 実装は、依存関係のある順番でサービスを削除する 必要があります(MUST) 。以下の例では、 dbredis の前に web が削除されます。

簡単な例:

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres

Compose 実装は、依存元のサービスが起動する前に、依存先のサービスを確実に起動する 必要があります(MUST) 。Compose 実装は、依存元のサービスが起動する前に、依存先のサービスの service_healthy (サービス正常性)が確実に「 正常(healthy) 」になるようにする 必要があります(MUST)

deploy

deploy は、 こちら で定義されている通り、サービスの展開とライフサイクルの設定情報を指定します。

device_cgroup_rules

device_cgroup_rules は、このコンテナに対するデバイス cgroup ルールの一覧を定義します。書式は Control Groups Device Whitelist Controller にある Linux カーネルが指定する書式と同じです。

device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'

devices

devices は、作成したコンテナにマッピングするデバイスの一覧を HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS] の形式で定義します。

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"

dns

dns は、コンテナのネットワーク インターフェース設定に、任意の DNS サーバを定義します。

dns: 8.8.8.8
dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

dns_opt は、コンテナの DNS レゾルバに対して渡す、任意のオプションのリストです。

dns_opt:
  - use-vc
  - no-tld-query

domainname

domainname では、サービス用コンテナが使う任意のドメイン名を宣言します。これは有効な RFC 1123 ホスト名の 必要があります(MUST)

entrypoint

entrypoint は Docker イメージのデフォルト entrypoint (つまり、 Dockerfile の ENTRYPOINT 設定)を上書きします。Compose 実装は、 Docker イメージ内のあらゆるデフォルトコマンドを除去する 必要があります(MUST) 。コマンドとは Dockerfile 内の ENTRYPOINTCMD の両命令であり、 Compose ファイルでは entrypoint で設定します。もしも command が設定されている場合、これが Docker イメージの CMD を置き換え、 entrypoint のパラメータとして使われます。

entrypoint: /code/entrypoint.sh

entrypoint はリストにもでき、書き方は Dockerfile と似ています。

entrypoint:
  - php
  - -d
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  - -d
  - memory_limit=-1
  - vendor/bin/phpunit

env_file

env_file はファイルの内容をもとに、コンテナへ環境変数を追加します。

env_file: .env

env_file はリストにもできます。ファイル内のリストは、上から下へと処理する 必要があります(MUST) 。2つの env ファイルで同じ変数が指定されると、リスト内で最も直近の値を有効に しなければいけません(MUST)

env_file:
  - ./a.env
  - ./b.env

相対パス、は Compose ファイルの親フォルダを基準に解決する 必要があります(MUST) 。絶対パスを避ければ Compose ファイルが 移動できるようになるため(being portable) 、Compose 実装では env_file に絶対パスが使われていれば、 警告すべきです(SHOULD)

environment セクションで宣言された環境変数は、これらの値を上書き すべきです(MUST) 。つまり、 env_file を使って定義された変数の値が、空白もしくは未定義だとしても、保持し続けます。

env_file 形式

env_file の各行は 変数[=[値]] の形式である 必要があります(MUST)# で始まる行は無視する 必要があります(MUST)

の値は、そのままの文字列として使われ、加工は一切行われません。値が引用符で囲まれた場合(通常、シェル変数を扱う場合)、Compose 実装によって作成されるコンテナに対し、引用符を 含めて 渡す 必要があります(MUST)

は省略する ことができます(MAY) 。たとえば、変数の値が、空白の文字列の場合です。 =値 は省略する ことができます(MAY) 。たとえば変数の値を unset する場合です。

# Rails/Rack 環境変数を設定
RACK_ENV=development
VAR="quoted"

environment

environment は、コンテナ内での環境変数を定義します。 environment は配列とマップのどちらかを使えます。あらゆるブール値、true、false、yes、no は、YAML パーサによって True や False に変換されないようにするため、引用符で囲むように すべきです(SHOULD)

環境変数の値は、1つのキーで宣言 する場合があります(MAY) (イコール記号と値がないもの)。このような場合、 Compose 実装は値を解決するため、何らかのユーザとのやりとりに頼る べきです(SHOULD) 。そうしなければ、変数は unset され、サービス用コンテナ環境から削除されます。

マップ形式の構文:

environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:

配列形式の構文:

environment:
  - RACK_ENV=development
  - SHOW=true
  - USER_INPUT

サービスに対して env_fileenvironment の両方がある場合、 environment の値が優先されます。

expose

expose では、 Compose 実装がコンテナから公開 しなければいけない(MUST) ポートを定義します。これらのポートは、つながっているサービスへ接続 する必要があり(MUST) ますが、ホストマシン上には公開 しないほうがよい(SHOULD NOT) ものです。内部のコンテナ用ポートのみ指定できます。

expose:
  - "3000"
  - "8000"

extends

現在のファイルや他のファイルからサービスを 拡張(extend) し、オプションで設定を上書きします。他の設定情報のキーと一緒に、あらゆるサービスで extends を使えます。 extends の値はマップで定義する する必要があり(MUST)service キーは必須で、 file キーはオプションです。

extends:
  file: common.yml
  service: webapp

Compose 実装がサポートする場合は、以下の方法で extends を処理する 必要があります(MUST)

  • service ベース(元になるもの)として参照されるサービスの名前を定義します。たとえば webdatabase です。

  • file は対象サービス向けの Compose 設定情報ファイルの場所です。

制限事項

参照されるサービスには、以下の制限が適用されます。

  • 他のサービスと依存関係を持つサービスは、他のサービスからのベースとして使えません。つまり、他のサービスに依存しているキーは、 extends と互換性がありません。このようなキーの網羅的ではない一覧: linksvolumes_fromcontainer モード( ipdpidnetwork_modenet )、 service モード( ipcpidnetwork_mode``depends_on )。

  • サービスは extends循環参照(circular reference) できません。

Compose 実装は、これ以外のケースでエラーを返す 必要があります(MUST)

参照されているサービスを探す

file の値とは:

  • 存在しない場合。これは同じ Comopse ファイル内の別のサービスが参照されているのを示します。

  • 以下どちらかのファイルパスです。

    • 相対パス。このパスはメインの Compose がある場所からの相対パスとみなします。

    • 絶対パス。

service によって示すサービスは、参照用として指定された Compose ファイルに存在する 必要があります(MUST) 。Compose 実装は、以下の場合にエラーを 返さなければいけません(MUST)

  • service で示されたサービスが見つからない

  • file で示された Compose ファイルが見つからない

サービス定義の統合

2つのサービス定義(1つは main で現在の Compose ファイル、もう1つは extends で指定した referenced として参照されるもの)は、以下の方法で統合する 必要があります(MUST)

  • マッピング(mapping)main サービス定義のマッピング内のキーは、 referenced サービス定義のマッピング内のキーを上書きします。上書きされないキーは、そのまま含まれたままです(残ったままです)。

  • シーケンス(sequence):アイテムは結合され、新しいシーケンスになります。要素の順番は、 referenced アイテムが最初で、次に main アイテムが続きます。

  • スカラー(scalar)main サービス内の定義は、 referenced サービス定義内のキーよりも優先されます。

マッピング(mappings)

次のキーがマッピングとして扱われるでしょう: build.argsbuild.labelsbuild.extra_hostsdeploy.labelsdeploy.update_configdeploy.rollback_configdeploy.restart_policydeploy.resources.limitsenvironmenthealthchecklabelslogging.optionssysctlsstorage_optextra_hostsulimits.

healthcheck に対しては例外が適用されます。 referenced マッピングで disable: true を指定しない限り、 main マッピングでも disable: true を指定できません。Compose 実装は、このような場合にエラーを返す 必要があります(MUST)

たとえば、以下のような入力があります。

services:
  common:
    image: busybox
    environment:
      TZ: utc
      PORT: 80
  cli:
    extends:
      service: common
    environment:
      PORT: 8080

以下の設定で cli サービスを生成します。配列形式を使うと、同じ出力が生成されます。

environment:
  PORT: 8080
  TZ: utc
image: busybox

blkio_config.device_read_bps 、 `` blkio_config.device_read_iops`` 、 `` blkio_config.device_write_bps`` 、 `` blkio_config.device_write_iops`` 、 `` devices and volumes`` 以下のアイテムも、キーとしてコンテナ内のパスが対象にあれば、マッピングとして扱われます。

たとえば、以下のような入力があります。


services:
common:

image: busybox volumes:

  • common-volume:/var/lib/backup/data:rw

cli:
extends:

service: common

volumes:
  • cli-volume:/var/lib/backup/data:ro

以下の設定で cli サービスを生成します。注意点として、マウントされたパスは新しいボリューム名を指し示し、 ro フラグが適用されます。

image: busybox
volumes:
- cli-volume:/var/lib/backup/data:ro

referenced サービスの定義が extends マッピングを含む場合は、新しい統合された定義に対し、アイテム以下がシンプルにコピーされます。統合の処理は extends キーが存在しなくなるまで、繰り返し行われます。

たとえば、以下のような入力があります。


services:
base:

image: busybox user: root

common:

image: busybox extends:

service: base

cli:
extends:

service: common

以下の設定で cli サービスを生成します。ここでは、 cli サービスは common サービスから user キーを取得します。サービスは base サービスからこのキーを取得します。

image: busybox
user: root
シーケンス(sequences)

以下のキーはシーケンスとして扱われるべきです:cap_addcap_dropconfigsdeploy.placement.constraintsdeploy.placement.preferencesdeploy.reservations.generic_resourcesdevice_cgroup_rulesexposeexternal_linksportssecretssecurity_opt 。統合の結果、重複した結果は削除されるため、シーケンスに含まれるのはユニークな(重複しない)要素のみです。

たとえば、以下のような入力があります。

services:
  common:
    image: busybox
    security_opt:
      - label:role:ROLE
  cli:
    extends:
      service: common
    security_opt:
      - label:user:USER

以下の設定で cli サービスを生成します。

image: busybox
security_opt:
- label:role:ROLE
- label:user:USER

リスト形式を使う場合、以下のキーはシーケンスとしても扱われるべきです: dnsdns_searchenv_filetmpfs 。先述したシーケンスのフィールドとは異なり、統合の結果、重複したものは削除されます。

スカラー(scalars)

その他のサービス内で許可されたキーは、スカラーとして扱われるべきです。

extra_hosts

extra_hosts はコンテナのネットワーク インタフェース設定( Linux は /etc/hosts )に対して、ホスト名のマッピングを追加します。値には、ホスト名と IP アドレスを ホスト名:IP の形式で指定する 必要があります(MUST)

extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"

Compose 実装は、コンテナのネットワーク設定内に IP アドレスとホスト名に一致するエントリを 作成しなくてはいけません(MUST) 。つまり、 Linux の場合は /etc/hosts に次のような行が追加されるのを意味します。

162.242.195.82  somehost
50.31.209.229   otherhost

group_add

group_add は、コンテナイアのユーザが所属する 必要がある(MUST) 追加グループ(名前または番号)を指定します。

便利な例は、共有ボリューム上の同じファイルを(異なるユーザとして実行している)複数のコンテナから読み書きする場合です。対象のファイルを所有するのは、全てのコンテナ内で共通しているグループと、 group_add で指定されたグループです。

services:
  myservice:
    image: alpine
    group_add:
      - mail

作成されたコンテナ内で id を実行すると、ユーザは mail グループとして 表示されなければいけません(MUST)group_add で宣言されていない場合は、このようになりません。

healthcheck

healthcheck で定義するのは、このサービスが「 正常(healthy) 」かどうかを決めるために実行する調査についてです。これは、サービスの Docker イメージで設定する HEALTHCHECK Dockerfile 命令 を上書きします。

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s

interval` ``timeoutstart_period期間を指定 します。

test で定義するコマンドのは、 Compose 実装がコンテナが正常かどうかを確認するために実行するものです。コマンドは文字列もしくはリストです。リストの場合、1番目の項目は NONECMDCMD-SHELL のどちらかである必要があります。文字列の場合は CMD-SHELL を指定したのと同じになり、以降に文字列が続きます。

# ローカルのウェブアプリをたたく
test: ["CMD", "curl", "-f", "http://localhost"]

CMD-SHELL を使うと、コンテナのデフォルトシェル( Linux の場合は /bin/sh )を使い、文字をコマンドとして扱い実行します。以下はどちらも同じ処理内容です。

test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
test: curl -f https://localhost || exit 1

NONE はヘルスチェックを無効にします。多くの場合、イメージによって設定されているヘルスチェックの無効化に役立ちます。あるいは、 disable: true の設定によっても、イメージのヘルスチェックを無効化できます。

healthcheck:
  disable: true

hostname

hostname declares a custom host name to use for the service container. MUST be a valid RFC 1123 hostname.

hostname は、サービス用コンテナに対して任意のホスト名を宣言します。有効な RFC 1123 ホスト名の 必要があります(MUST)

image

image は、コンテナの元になるイメージを指定します。イメージは オープンコンテナ仕様(Open Container Specification)アドレス可能なイメージ形式(addressable image format) に従う 必要があります(MUST) 。形式は [<registry>/][<project>/]<image>[:<tag>|@<digest>] です。

image: redis
image: redis:5
image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
image: library/redis
image: docker.io/library/redis
image: my_private.registry:5000/redis

もしもイメージがプラットフォーム上に存在しなければ、 Compose 実装は pull_policy をもとに 取得(pull)試みなくてはいけません(MUST) 。構築をサポートする Compose 実装は、エンドユーザに対し、ソースからイメージを構築する時、 手元に寄せる(pull over) 優先順位を制御する代替オプションを 提供してもよい(MAY) ですが、イメージの取得はデフォルトの挙動になる 必要があります(MUST)

Compose ファイルで build セクションを宣言する場合、 image省略しても構いません(MAY) 。構築をサポートしない Compose 実装の場合、 Compose ファイルに image がなければ失敗 しなければいけません(MUST)

init

init はコンテナ内で init プロセス( PID 1 )として実行するものです。これは(コンテナが受け取った)シグナルを転送し、プロセスとして処理できるようにします。サービスでこの機能を有効かするには、オプションで true に設定します。

services:
  web:
    image: alpine:latest
    init: true

この init バイナリは、プラットフォームが指定のものを使います。

ipc

ipc はサービス用コンテナによって設定される IPC isolation モードを設定します。利用できる値はプラットフォーム固有ですが、 Compose 仕様では、サポートする場合は以下どちらかの手段によって値を決めるよう定義しなければいけません。

  • shareable はコンテナ自身のプライベート IPC 名前空間に与えますが、他のコンテナからも共有できる可能性があります。 service:{name} のコンテナには、他の(共有可能な)コンテナの IP 名前空間から接続できます。

ipc: "shareable"
ipc: "service:[service name]"

isolation

isolation はコンテナの 分離(isolation) 技術を指定します。サポートされる値は、プラットフォームに固有のものです。

labels

labels はコンテナにメタデータを追加します。 配列形式(array)マップ形式(map) を使えます。

使っているソフトウェアと他のソフトウェアの衝突を避けるため、逆引き DNS 記法の使用を推奨します。

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""
labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

Compose 実装は、作成するコンテナが、 基準となる(canonical) ラベルを持つ 必要があります(MUST)

  • com.docker.compose.project Compose 実装によって作成された全てのリソースを、 ユーザ プロジェクト名(user project name) に設定する。

  • com.docker.compose.service サービス用コンテナを、 Compose ファイルで定義されたサービス名を使って設定する。

com.docker.compose ラベルのプレフィクスは予約済みです。Compose ファイルにこのプレフィクスがあれば、結果ランタイムエラーとする 必要があります(MUST)

logging

logging はサービスの ログ記録(logging) 設定を定義します。

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

driver 名は、サービス用コンテナのログ記録ドライバを指定します。デフォルトかつ利用可能な値は、プラットフォーム固有です。ドライバ固有のオプションは、 options にキーバリューのペアで指定できます。

network_mode

network_mode は、サービス コンテナのネットワーク モードを設定します。利用可能な値はプラットフォーム固有ですが、サポートする場合、 Compose 仕様では以下のように値を実装 しなければいけません(MUST)

  • none 全てのコンテナ ネットワーク機能を無効化

  • host コンテナはホスト側のネットワーク インタフェースに直接アクセスできるようにする

  • ``service:{名前}` コンテナを特定のサービスのみ接続できるようにする

network_mode: "host"
network_mode: "none"
network_mode: "service:[service name]"

networks

networks はサービス コンテナを 接続する(attached) ネットワークを定義し、 トップレベルの「networks」キー 以下のエントリを参照します。

services:
  some-service:
    networks:
      - some-network
      - other-network

aliases

aliases は、このサービスに対してサービス上で別のホスト名を宣言します。同じネットワーク上にある他のコンテナは、サービス名か、この 別名(aliases) かのどちらかを使ってサービス用コンテナに接続できます。

aliasesネットワーク内が範囲(network-scoped) です。そのため、異なるネットワーク上では、同じサービスに対して異なる別名を持たせられます。

注釈

ネットワーク外の別名(network-wide alias) であれば、複数のコンテナだけでなく、複数のサービスによっても共有できます。その場合(複数のサービスで共有される場合)、その別名がどのコンテナに名前解決されるかの保証はありません。

一般的な形式は、以下の通りです:

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

次の例では、サービス frontend は、 back-tier ネットワーク上にある、ホスト名 backenddatabasebackend サービスに対して到達可能です。また、サービス monitoring は、同じ admin ネットワーク上にある backend サービスに対して、 backendmysql で到達可能です

services:
  frontend:
    image: awesome/webapp
    networks:
      - front-tier
      - back-tier

  monitoring:
    image: awesome/monitoring
    networks:
      - admin

  backend:
    image: awesome/backend
    networks:
      back-tier:
        aliases:
          - database
      admin:
        aliases:
          - mysql

networks:
  front-tier:
  back-tier:
  admin:

ipv4_address 、 ipv6_address

このサービスがネットワークに接続する時、コンテナに対する固定 IP アドレスを指定します。

トップレベルの networks セクション 内にある ipam ブロックで、各固定アドレスを扱うサブネット設定が必要です。

services:
     frontend:
       image: awesome/webapp
       networks:
         front-tier:
           ipv4_address: 172.16.238.10
           ipv6_address: 2001:3984:3989::10

networks:
  front-tier:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"

priority

priority は、 Compose 実装がサービス用コンテナをネットワークに接続 すべき(SHOULD) 順番を示します。指定が無ければ、デフォルトの値は 0 です。

以下の例では、app サービスは第一に接続するのは、高い優先度を持つ app_net_1 です。それから app_net_3 に接続し、さらにデフォルト優先度の値 0 を使う app_net_2 に接続します。

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

mac_address

mac_address はサービス コンテナに MAC アドレスを設定します。

mem_limit

非推奨: deploy.limits.memory を使います。

mem_reservation

非推奨: deploy.reservations.memory を使います。

mem_swappiness

mem_swappiness は、ホスト kernel がコンテナで使用される 無名メモリ(anonymous memory) のスワップアウトを百分率(0~100の値)で定義します。

  • 0 の値は、無名メモリ ページ のスワップを無効にする

  • 100 の値は、全ての無名メモリ ページをスワップ可能にする

デフォルトの値はプラットフォーム固有のものです。

memswap_limit

memswap_limit は、ディスクへのスワップを許可するコンテナのメモリ容量を定義します。これは memory も設定されている場合のみ変更可能な属性です。スワップを使うと、コンテナが利用可能な全てのメモリを使い尽くした時、コンテナは要求されない余分なメモリをディスクに書き込めます。ディスクに対するスワップメモリが頻発するアプリケーションは、パフォーマンスが低下します。

  • memswap_limit に整数値を設定する場合、 memorymemswap_limit の両方を設定 しなくてはいけません。 。 memswap_limit は利用可能な全メモリ容量とスワップを表し、 memory はスワップしないで使うメモリ容量を制御します。そのため、 memory が 300m と memswap_limit が 1g の場合、コンテナは 300m のメモリと 700m(1g - 300m)のスワップを利用できます。

  • ``memswap_limit を 0 に設定する場合、設定は無視 しなければいけません 。そして値は 未定義(unset) として扱われます。

  • memswap_limitmemory と同じ値に設定する場合かつ memory を整数値に設定する場合、コンテナはスワップにアクセスしません。 コンテナがスワップをしないようにする をご覧ください。

  • memswap_limit が未定義で、かつ、 memory が設定されている場合、ホスト コンテナにスワップメモリが設定されていれば、コンテナは memory 設定と同じ容量のスワップを利用できます。たとえば、 memory が 300m で memswap_limit が設定されていなければ、コンテナはメモリとスワップで合計 600m 利用できます。

  • memswap_limit を -1 に明示すると、ホストシステム上で利用可能な上限まで、コンテナが無制限にスワップを利用できます。

oom_kill_disable

oom_kill_disable を設定する場合、 Compose 実装は、メモリ不足が発生してもコンテナを 強制停止(kill) しないよう、プラットフォームを調整する 必要があります(MUST)

oom_score_adj

oom_score_adj はメモリ不足が発生した場合、プラットフォームによって 強制停止(kill) されるコンテナの優先度を調整します。値は [-1000,1000] の範囲内の 必要があります(MUST)

pid

pid は Compose 実装によって作成されるコンテナの PID モードを設定します。サポートされている値は、プラットフォーム固有のものです。

pids_limit

非推奨: deploy.reservations.pids を使います。

pids_limit はコンテナの PID の上限を調整します。-1 に設定すると、PID を無制限にします。

pids_limit: 10

platform

platform は、このサービスを実行するための 対象プラットフォーム コンテナ(target platform containers) を定義します。定義には os[/arch[/variant]] 構文を使います。Compose 実装は、どのバージョンのイメージを取得するかを決める場合や、どのプラットフォームでサービスの構築を実行するかを決める場合に、宣言時にこの属性を使う 必要があります(MUST)

platform: osx
platform: windows/amd64
platform: linux/arm64/v8

ports

コンテナのポートを 公開(expose) します。 network_mode: host を使う場合は、ポートマッピングを 使ってはいけません(MUST) 。また、使った結果にはランタイムエラーに しなければいけません(MUST)

短い形式

短い形式はコロン記号で区切られた文字列で、ホスト IP 、ホスト側ポート、コンテナ側ポートを [ホスト:]コンテナ[/プロトコル] の形式で設定します。

  • ホスト[IP:](ポート番号|範囲)

  • コンテナポート番号|範囲

  • プロトコル は指定したプロトコルにポートを制限します。仕様では tcpudp の値が定義されており、 Compose 実装ではプラットフォーム固有のプロトコル名をサポートする場合が あります(MAY)

ホスト IP の指定がなければ、全てのネットワークインタフェースを バインド(bind) する必要があります。ポートには単一の値か範囲のどちらかを指定できます。ホストとコンテナでは、同じ範囲を使う 必要があります(MUST)

両方のポート( ホスト:コンテナ )を指定するか、コンテナのポートだけを指定するかのどちらかです。後者の場合、Compose 実装は自動的に未割り当てのホスト側ポートを割り当てる べきです(SHOULD)ホスト:コンテナ の場合、 yaml base-60 float との衝突を避けるため、常に(引用符で囲まれた)文字列で 指定すべき(SHOULD) です。

例:

ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "6060:6060/udp"

注釈

ホスト IP の 割り当て(mapping) は、プラットフォーム上ではサポート されない場合もあり(MAY NOT) 、そのような場合に Compose 実装は Compose ファイルを拒否 すべきであり(SHOULD) 、ユーザに対して指定したホスト IP を無視すると通知する 必要があります(MUST)

長い形式

長い形式の構文は、短い形式では表現できない追加フィールドで調整をできるようにします。

  • target :コンテナ側ポート

  • published :パブリックに 公開される(exposed) ポート。構文 start-end を使って範囲を指定できます。実際のポートは、この利用可能なポート範囲にもとづいて 割り当てられるべきです(SHOULD)

  • host_ip :ホスト IP を割り当て。未指定は全てのネットワークインタフェース( 0.0.0.0 )を意味する

  • protocol :ポートのプロトコル( tcpudp )。未定義はあらゆるプロトコルを意味する

  • modehost は各ノード上のホスト側ポートで公開。または、 ingress は負荷分散されたポートで公開。

ports:
  - target: 80
    host_ip: 127.0.0.1
    published: 8080
    protocol: tcp
    mode: host

  - target: 80
    host_ip: 127.0.0.1
    published: 8000-9000
    protocol: tcp
    mode: host

privileged

privileged 設定は、昇格した権限でサービスコンテナを実行します。サポートおよび実際の影響は、プラットフォーム固有です。

profiles

profiles は、サービスが有効な状態にするための、名前付き profile のリストを定義します。設定がなければ、サービスは常に有効です。

存在する場合は、 profiles は正規表現の形式 [a-zA-Z0-9][a-zA-Z0-9_.-]+従うべきです(SHOULD)

pull_policy

pull_policy は、 Compose 実装がイメージ取得を開始する時の挙動を定義します。有効な値は次の通りです。

  • always :Compose 実装は、常にレジストリからイメージを 取得すべき(SHOULD) です。

  • never :Compose 実装は、常にレジストリからイメージを 取得すべきではありません(SHOULD NOT) 。そして、プラットフォームでキャッシュされたイメージに 頼るべき(SHOULD) です。もしもキャッシュされたイメージがなければ、失敗を報告する 必要があります(MUST)

  • missing :Compose 実装は、プラットフォームのキャッシュからイメージを利用できない場合のみ、取得 すべきです(SHOULD) 。これは、構築をサポートしていない Compose 実装では、デフォルトのオプションと すべきです(SHOULD)if_not_present は、この値が後方互換性のための別名と 考えるべきです(SHOULD)

  • build :Compose 実装がイメージを 構築(build) すべきです(SHOULD) 。Compose 実装は、イメージが既に存在していても再構築 すべきです(SHOULD)

もしも pull_policybuild の両方がある場合、 Compose 実装はデフォルトでイメージを構築 すべきです(SHOULD) 。Compose 実装は、ツールチェーンの中では、この挙動を 上書きしても構いません(MAY)

read_only

read_only 設定は、読み込み専用のファイルシステムでサービス コンテナを作成します。

restart

restart は、コンテナの終了時に、プラットフォームが適用するポリシーを定義します。

  • no :デフォルトの再起動ポリシーです。どのような状況下でも、コンテナを再起動しません。

  • always :コンテナを削除するまで、常に再起動するポリシーです。

  • on-failure :コンテナの終了コードがエラーを示す場合、コンテナを再起動するポリシーです。

  • unless-stopped :コンテナの終了コードにかかわらず再起動しますが、サービスが停止もしくは削除する場合は再起動処理を行いません。

restart: "no"
restart: always
restart: on-failure
restart: unless-stopped

runtime

runtime はサービス用コンテナに使うランタイムを指定します。

runtime の値は、実装を指定します。たとえば、 runtime の値には、 "runc" のような OCI ランタイム仕様(OCI Runtime Spec)を実装 する名前です。

web:
  image: busybox:latest
  command: true
  runtime: runc

scale

非推奨: deploy/replicas を使います。

scale は、このサービスをデプロイするデフォルトのコンテナ数を指定します。

secrets

secrets は、サービス単位を元にする ref:シークレット(secrets) <compose-spec-secrets>`_によって定義する機微データ( :ruby:`センシティブ データ <sensitive data> )へのアクセスを許可します。短い形式と長い形式の、2つの異なる形式がサポートされています。

プラットフォーム上にシークレットが存在しない場合、あるいは、この Compose ファイルの secrets セクション内での定義がない場合、Compose 実装はエラーを報告する 必要があります(MUST)

短い形式

短い形式の記述では、シークレット名のみ指定します。これは、コンテナに対してシークレットに対するアクセスを許可し、コンテナ内の /run/secrets/<シークレット名> を読み込み専用としてマウントします。ソース名とマウントポイント先は、どちらもシークレット名で設定されます。

以下の例は、短い構文を使い、 frontend サービスに対して server-certificate シークレットに対するアクセスを許可します。 server-certificate の値は ./server.cert ファイルの内容を設定します。

services:
  frontend:
    image: awesome/webapp
    secrets:
      - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

長い形式

長い形式は、サービスコンテナ内で作成されるシークレットをどのように作成するか、より細かく指定します。

  • source :プラットフォームに存在するシークレット名です。

  • target :サービス用タスク コンテナ内の、 /run/secrets/ にマウントするファイル名です。

  • uidgid :サービス用タスク コンテナ内の、 /run/secrets/ 内のファイルを所有する UID や GID の整数値です。

  • mode : サービス用タスク コンテナ内の、/run/secrets にマウントするファイルの https://web.archive.org/web/20220310140126/http://permissions-calculator.org/ を8進数で指定します。もしも書き込み可能なビットが設定されても、無視する 必要があります(MUST) 。実行可能ビットは設定しても 構いません(MAY)

以下の例は、コンテナ内の server.crt ファイルに server-sertificate という名前のシークレットを作成します。このファイルのモードを 0440 に設定し、ユーザとグループを 103 にします。シークレット server-certificate の値には、プラットフォームを通して検索したものが提供されますので、シークレットのライフサイクルは Compose 実装によって直接管理されません。

services:
  frontend:
    image: awesome/webapp
    secrets:
      - source: server-certificate
        target: server.cert
        uid: "103"
        gid: "103"
        mode: 0440
secrets:
  server-certificate:
    external: true

サービスには複数のシークレットに対してアクセス権限を与えても 構いません(MAY) 。同じ Compose ファイル内で、短い形式と長い形式のシークレットを同時に使っても 構いません(MAY) 。シークレットをトップレベルの secret 内で定義し、あらゆるサービスに許可するように 意図してはいけません(MUST NOT) 。このような権限の許可は、 Compose 仕様内では secrets サービス要素として明示する必要があります。

security_opt

security_opt は各コンテナのデフォルト ラベリング スキーマ(labeling scheme) を上書きします。

security_opt:
  - label:user:USER
  - label:role:ROLE

shm_size

shm_size は、サービス コンテナが利用できる共有メモリ( Linux 上では /dev/shm パーティション)の容量を設定します。 バイト値 で指定します。

stdin_open

stdin_open は、サービス コンテナに標準入力を割り当てて実行するよう設定します。

stop_grace_period

stop_grace_period は、 Compose 実装がコンテナを停止しようとする時、 SIGTERM で処理できない場合(または、 stop_signal を停止シグナルとして指定していても)、 SIGKILL を送信する前にどれだけ待機する 必要がある(MUST) かを設定します。これは 期間 で指定します。

stop_grace_period: 1s
stop_grace_period: 1m30s

コンテナに SIGKILL を送信して停止するまでは、デフォルトで 10 秒です。

stop_signal

stop_signal はシグナルを定義します。これは Compose 実装がサービス コンテナを停止するために使う 必要があります(MUST) 。設定のないコンテナは、 Compose 実装によって SIGTERM の送信がサポートされます。

stop_signal: SIGUSR1

storage_opt

storage_opt は、サービスに対してストレージ ドライバのオプションを定義します。

storage_opt:
  size: '1G'

sysctls

sysctls はコンテナ内に設定する kernel パラメータを定義します。 ``sysctls` は配列形式かマップ形式のどちらかを使えます。

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0
sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

sysctls が使えるのは kernel 内の 名前空間(namespace) のみです。Docker はホストシステム上も変更するコンテナ内の sysctls の変更をサポートしません。サポートしている sysctls については 実行時に名前空間のカーネル・パラメータ(sysctl)を設定 を参照ください。

tmpfs

tmpfs はコンテナ内に一時的なファイルシステムをマウントします。単一の値、もしくはリスト形式です。

tmpfs: /run
tmpfs:
  - /run
  - /tmp

tty

tty は、サービス コンテナに TTY を使って実行するよう設定します。

ulimits

ulimits はコンテナのデフォルト ulimits を上書きします。単一の 制限(limit) を整数値で指定するか、マップ形式でソフト/ハード 制限(limit) のどちらかを指定します。

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000

user

user は、コンテナのプロセスを実行するために使うユーザを上書きします。デフォルトはイメージで指定されたもの(例: Dockerfile の USER )が使われますが、設定が無ければ root です。

userns_mode

userns_mode はサービスに対するユーザ名前空間を設定します。サポートしている値はプラットフォーム固有であり、プラットフォームの設定に依存する 場合があります(MAY)

userns_mode: "host"

volumes

volumes は、サービス コンテナがアクセスできるようにする 必要がある(MUST) 、 ホスト上のパスか 名前付きボリューム(named volume) を定義します。

マウントがホスト上のパスで、かつ、単一の値の場合は、サービス定義の一部ではなくトップレベルの volume キーで宣言しても 構いません(MAY)

複数のコンテナを横断してボリュームを再利用するには、 トップレベルの「volumes」キー 内で名前付きボリュームを宣言する 必要があります(MUST)

この例が表すのは、 backend サービスによって使われる名前付きボリューム( db-data )と、この1つのサービスに対する バインド マウント(bind mount) を定義します。

services:
  backend:
    image: awesome/backend
    volumes:
      - type: volume
        source: db-data
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: /var/run/postgres/postgres.sock
        target: /var/run/postgres/postgres.sock

volumes:
  db-data:

短い形式

短い形式は、コロン区切りの値を持つ単一文字列を使い、ボリュームマウント( VOLUME:CONTAINER_PASS )や、アクセスモード(VOLUME:CONTAINER_PATH:ACCESS_MODE) を指定します。

  • VOLUME :コンテナをホスティングするプラットフォーム上のホストパス(バインド マウント)かボリューム名のどちらかを 指定できます(MAY)

  • CONTAINER_PATH :ボリュームがマウントされるコンテナ内のパス

  • ACCESS_MODE :これはコンマ記号 , で区切られたリストで、次の値が 設定できます(MAY)

    • rw``読み込み(read)書き込み(write) のアクセス(デフォルト)

    • ro読み込み専用(read-only) のアクセス

    • z :SELinux オプションを示すもので、バインド マウントするホストの内容が、複数のコンテナ間で共有する

    • Z :SELinux オプションを示すもので、バインド マウントするホストの内容がプライベートであり、他のコンテナとは共有しない

注釈

SELinux の 再ラベル(re-labeling) バインド マウント オプションは、SELinux の無いプラットフォームでは無視されます。

注釈

相対ホスト パスが Compose 実装によってサポートする 必要がある(MUST) のは、ローカルのコンテナランタイムにデプロイする場合のみです。これは、相対パスとみなすのは Compose ファイルの親ディレクトリのためであり、ローカルでの実行時にのみ適用されるからです。 Compose 実装によるローカル以外へのデプロイでは、 Compose が相対ホストパスを扱えないため、エラーを出して拒否する 必要があります(MUST) 。この曖昧さを名前付きボリュームで防止するには、相対パスの指定を常に ...指定すべき(SHOULD) です。

長い形式

長い形式の構文は、短い形式では表現できない追加フィールドの設定を行えるようにします。

  • type :マウントの (type)volumebindtmpfsnpine です。

  • source :マウント元で、バインドマウントするホスト上のパスか、 トップレベル「volumes」キー で定義されるボリュームの名前です。

  • target :ボリュームがマウントされるコンテナ内のパスです。

  • read_only :ボリュームを読み込み専用に設定するフラグです。

  • bind :追加のバインド オプションを設定します。

    • propagation :バインドに 伝搬モード(propagation mode) を使います。

    • create_host_path :何も指定がなければ、ホスト上のソースパスにディレクトリを作成します。パス上に同様のパスが存在している場合は、何もしません。これは、過去の docker-compose との後方互換正のため、短い構文では自動的に処理されます。

    • selinux : SELinux の 再ラベル(re-labeing) オプション z (共有)か Z (プライベート)を指定します。

  • volume :追加のボリューム オプションを設定します。

    • nocopy :ボリュームを作成する場合、コンテナからのデータのコピーを無効化するフラグです。

  • tmpfs :追加の tmpfs オプションを指定します。

    • size :tmpfs マウント用の容量をバイトで(整数値またはバイト単位として)指定します。

  • consistency :マウントには 一貫性(onsistency) を必要とします。利用可能な値は、プラットフォームに固有のものです。

volumes_from

volumes_from は、他のサービスやコンテナから全てのボリュームをマウントします。オプションで読み込み専用のアクセス(ro)や読み書き(rw)を指定します。アクセスレベルの指定が無ければ、読み書きを使う 必要があります(MUST)

文字列の値には、 Compose アプリケーション モデル内にある別のサービスを定義します。 container: プレフィクスをサポートする場合、コンテナからのボリュームをマウントできるようにしますが、 Compose 実装によっては管理されません。

volumes_from:
  - service_name
  - service_name:ro
  - container:container_name
  - container:container_name:rw

working_dir

working_dir は、イメージで定義(例: Dockerfile の WORKDIR )されたコンテナ用の 作業ディレクトリ(working directory) を上書きします。

networks トップレベル 要素(element)

networks (ネットワーク)はサービスが相互に通信できるようにするためのレイヤです。サービスに対して公開するネットワーク機能モデルとは、対象サービスと外部リソース間でのシンプルな IP 接続に限定されます。ただし、ネットワーク定義により、プラットフォームが提供する実際の実装を微調整できます。

トップレベルの networks セクション下でネットワーク名を定義すると、ネットワークが作成されます。サービスの networks サブセクションで指定されたネットワークにも、サービスは接続できます。

以下の例では、実行時にネットワーク front-tierback-tier が作成され、それから forntend サービスは front-tier ネットワークと back-tier ネットワークに接続します。

services:
     frontend:
       image: awesome/webapp
       networks:
         - front-tier
         - back-tier

   networks:
     front-tier:
     back-tier:

driver

driver は、このネットワークに使うべきドライバを指定します。 Compose 実装はプラットフォーム上でドライバが利用できなければ、エラーを返す 必要があります(MUST)

driver: overlay

デフォルトかつ利用可能なボリュームは、プラットフォーム固有です。 Compose 仕様は、以下のドライバ nonehost を指定するようにサポートする 必要があります(MUST)

  • host はホスト側のネットワーク スタックを使用

  • none はネットワーク無効化

hostnone

hostnone では、内蔵ネットワークを扱う構文は異なります。これらネットワークは、暗黙的に Compose 実装の範囲外となるためです。これらのうち1つを使う場合、 hostname で外部ネットワークと 別名(alias) を定義する 必要があり(MUST) 、Compose 実装は使用する 別名(alias) を定義し、サービスはネットワークに対して 別名(alias) を使って接続を許可するようにします。

services:
  web:
    networks:
      hostnet: {}

networks:
  hostnet:
    external: true
    name: host
services:
  web:
    ...
    networks:
      nonet: {}

networks:
  nonet:
    external: true
    name: none

driver_opts

driver_opts は、このネットワーク用ドライバに渡すオプションのリストを、キーバリューの組み合わせで定義します。このオプションはドリア場に依存します。そのため、詳細情報はドライバのドキュメントをご確認ください。これはオプションの項目です。

driver_opts:
  foo: "bar"
  baz: 1

attachable

attachabletrue に設定すると、スタンドアロン コンテナはサービスに加え、このネットワークに 接続(attach) できるように すべきです(SHOULD) 。スタンドアロン コンテナがネットワークへ接続する時に、そのネットワークに接続している他のサービスやスタンドアロン コンテナとも通信できます。

networks:
  mynet1:
    driver: overlay
    attachable: true

enable_ipv6

enable_ipv6 は、このネットワーク上で IPv6 ネットワーク機能を有効化します。

ipam

ipam は任意の IPAM 設定を指定します。これには複数の属性を持つオブジェクトがありますが、どれもオプションです。

  • driver :デフォルトに替わる、任意の IPAM ドライバです。

  • config :ゼロ、もしくは、次の内容を含む複数の設定要素のリストです。

    • subnet :ネットワークセグメントを表す CIDR 形式のサブネット

    • ip_range :コンテナに割り当て可能な IP アドレスの範囲

    • gateway :マスタサブネットのための IPv4 または IPv6 ゲートウエイ

    • aux_addresses :ネットワーク ドライバによって使われる外部の IPv4 または IPv6 アドレスで、ホスト名から IP アドレスにマッピングする

  • options :ドライバ固有のオプションをキーバリューのマップとして指定

完全な例です:

ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16
      ip_range: 172.28.5.0/24
      gateway: 172.28.5.254
      aux_addresses:
        host1: 172.28.1.5
        host2: 172.28.1.6
        host3: 172.28.1.7
  options:
    foo: bar
    baz: "0"

internal

デフォルトでは、 Compose 仕様はネットワークに対する外部への接続性を提供する 必要があります(MUST)internal``true``に設定する場合は、外部の 分離された(isolated) ネットワークを作成できるようになります。

labels

ラベルを使ってコンテナにメタデータを追加します。配列形式もしくは辞書形式のどちらかを利用できます。

他のソフトウェアが使っているラベルとの重複を防ぐため、ユーザは逆引き DNS 記法を 使うべきです(SHOULD)

labels:
  com.example.description: "Financial transaction network"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""
labels:
  - "com.example.description=Financial transaction network"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

Compose 実装はラベル com.docker.compose.projectcom.docker.compose.network を指定する 必要があります(MUST)

external

externaltrue に設定した場合、このネットワークのライフサイクルは、対象アプリケーションの外で管理されます。Compose 実装はこれらネットワークを作成しようと すべきではなく(SHOULD NOT) 、存在しなければエラーを返します。

以下の例では、 proxy は外の世界へのゲートウェイです。ネットワークの作成を試みるのではなく、 Compose 実装はプラットフォームに対して outside という名前で既存ネットワークに存在しているかどうかを単純に尋ね、 proxy サービスのコンテナがそこに接続できるようにします。

services:
     proxy:
       image: awesome/proxy
       networks:
         - outside
         - default
     app:
       image: awesome/app
       networks:
         - default

   networks:
     outside:
       external: true

name

name は、このネットワークに対して任意の名前を設定します。name フィールドは、特別な文字を含むネットワークの参照にも使えます。この名前はそのまま使われるだけであり、プロジェクト名の範囲では使われ ません

networks:
  network1:
    name: my-app-net

プラットフォームのネットワークを定義するため、 external 属性と組み合わせての利用も可能です。これは、 Compose 実装では、 Compose がランタイム固有の値を ハードコード(hard-code) する必要がないようにするため、通常はパラメータを使って取得すべきです。

networks:
  network1:
    external: true
    name: "${NETWORK_ID}"

volumes トップレベル 要素(element)

ボリューム( volumes )とはプラットフォームによって実装される 持続的データストア(persistent data store) です。Compose 仕様では、サービスがボリュームをマウントするための中立的な中立化と、それらを 基盤上(infrastructure) に割り当てるための設定パラメータを提供します。

voluems セクションは、複数のサービスを横断して再利用できる 名前付きボリューム(named volume) の設定ができます。こちらは2つのサービスをセットアップする例で、データベースのデータディレクトリは db-data という名前のボリュームとして他のサービスから共有されます。そのため、バックアップ用途にも使えるでしょう。

services:
  backend:
    image: awesome/database
    volumes:
      - db-data:/etc/data

  backup:
    image: backup-service
    volumes:
      - db-data:/var/lib/backup/data

volumes:
  db-data:

トップレベルの volumes キー以下のエントリは空っぽにできます。ボリュームの作成にあたり、プラットフォームのデフォルト設定を使う場合に、そのようにします。オプションで、以下のキーを使って設定できます。

driver

このボリュームが使うべきボリュームドライバを指定します。デフォルトの値や利用可能な値は、プラットフォーム固有です。ドライバが利用できない場合は、 Compose 実装はエラーを返してアプリケーションのデプロイを中止する 必要があります(MUST)

driver: foobar

driver_opts

driver_opts は、このボリュームのドライバに渡すオプションのリストを、キーバリューの組み合わせで指定します。それぞれのオプションは、ドライバに依存します。

volumes:
  example:
    driver_opts:
      type: "nfs"
      o: "addr=10.40.0.199,nolock,soft,rw"
      device: ":/docker/example"

external

externaltrue に設定した場合、このボリュームのライフサイクルは、対象アプリケーションの外で管理されます。Compose 実装はこれらボリュームを作成 しようとしてはいけません(MUST NOT) 。また、存在しなければエラーを返す 必要があります(MUST)

以下の例では、 {project_name}_db-data という名前のボリューム作成を試みるのではなく、 Compose はシンプルに db-data という名前の既存ボリュームを探し、それを backend サービスのコンテナにマウントします。

services:
  backend:
    image: awesome/database
    volumes:
      - db-data:/etc/data

volumes:
  db-data:
    external: true

labels

ラベルはボリュームにメタデータを追加するために使います。配列形式もしくは辞書形式のどちらかを利用できます。

他のソフトウェアが使っているラベルとの重複を防ぐため、ユーザは逆引き DNS 記法を 使うべきです(SHOULD)

labels:
  com.example.description: "Database volume"
  com.example.department: "IT/Ops"
  com.example.label-with-empty-value: ""
labels:
  - "com.example.description=Database volume"
  - "com.example.department=IT/Ops"
  - "com.example.label-with-empty-value"

Compose 実装はラベル com.docker.compose.projectcom.docker.compose.network を指定する 必要があります(MUST)

name

name は、このボリュームに対して任意の名前を設定します。name フィールドは、特別な文字を含むボリュームの参照にも使えます。この名前はそのまま使われるだけであり、スタック名の範囲では使われ **ません ** 。

volumes:
  data:
    name: "my-app-data"

external 属性と組み合わせての利用も可能です。この場合、プラットフォーム上で実際のボリュームを探すためのボリューム名は、Compose ファイル内で参照するための名前とは別に設定されます。

volumes:
  db-data:
    external:
      name: actual-name-of-volume

次のようにすると、 Compose ファイルのパラメータで名前を探せるようになるため、ボリューム用のモデル ID を ハードコード(hard-code) する必要がなくなり、デプロイを処理する間に、プラットフォーム上での実際のボリューム ID が設定されます。

volumes:
  db-data:
    external:
      name: ${DATABASE_VOLUME}

configs ドップレベル 要素(element)

設定情報( configs )によって、 サービスに対して挙動を適用するにあたり、Docker イメージの再構築を不要にします。 configs はサービス用コンテナのファイルシステムへマウントされるため、サービスの観点からはボリュームに相当します。プラットフォームから取得する実際の実装詳細は、この設定情報の定義で設定できます。

設定情報にアクセスを許可すると、設定情報の内容が、コンテナ内ではファイルとしてマウントされます。コンテナ内のマウントポイントの場所は、 Linux コンテナでのデフォルトは </config-name> であり、 Windows コンテナーの場合は C:\<config-name> です。

デフォルトでは、設定情報はコンテナのコマンドを実行するユーザによって所有される 必要があり(MUST) が、サービス設定では上書きできません。デフォルトの設定情報は、サービスが設定を上書きしない限り、誰もが読み込みできるパーミッション(モード 0444) を持ちます。

configs のサブセクションで、サービスがアクセスできる設定情報を明示的に許可できます。

トップレベルの configs 宣言による定義や参照される設定情報データは、このアプリケーションの(他の)サービス上からも参照できるようになります。設定情報の元になるのは fileexternal です。

  • file :指定されたパスにあるファイルの内容から、設定情報を作成します。

  • external :設定情報が既に作成されている場合、設定を true にして指定します。Compose 実装は作成を試みません。また、存在しなければエラーを起こします。

  • name :プラットフォームで探す設定情報の名前です。このフィールドは特別な文字を含む設定情報も参照できます。名前はそのまま使いますが、プロジェクト名の範囲外では使われ ません

この例では、アプリケーションのデプロイ時に http_config<project_name>_http_config として作成されます。そして my_second_config は既存のプラットフォーム上に存在し、その値を探して得られる 必要があります(MUST)

この例では、アプリケーションのデプロイ時に server-http_config が( <project_name>_http_config として)作成されます。このとき、 httpd.conf の内容は設定情報のデータ内容が登録されます。

configs:
  http_config:
    file: ./httpd.conf

あるいは、 httpd_config は外部(external)としての宣言もできます。そのような場合、 Compose 実装は対象サービスで公開されている設定情報データから http_config を探します。

configs:
  http_config:
    external: true

外部設定を探すにあたり、明確にキーを name で指定しての利用もできます。以下の例は先の例を編集したもので、パラメータ HTTP_CONFIG_KEY の設定を探します。そのため、デプロイ時に変数が 展開 されたものが設定されますが、 ハードコード(hard-cord) された ID http_config としてコンテナに公開されます。

configs:
  http_config:
    external: true
    name: "${HTTP_CONFIG_KEY}"

Compose ファイルでは、アプリケーション内の関連するサービスに対しては、設定情報に明示的な許可が必要です。

secrets トップレベル 要素(element)

シークレット( secrets )は 機微データ(sensitive data) に焦点をあてた設定の一種であり、使うには固有の制限があります。プラットフォームの実装によっては configs と著しく異なる可能性があるため、secrets 専用のセクションで関連リソースの設定が可能です。

トップレベルの secrets 宣言による定義や参照される設定情報データは、このアプリケーションの(他の)サービス上からも参照できるようになります。設定情報の元になるのは fileexternal です。

  • file :指定されたパスにあるファイルの内容から、シークレットを作成します。

  • external :シークレットが既に作成されている場合、設定を true にして指定します。Compose 実装は作成を試みません。また、存在しなければエラーを起こします。

  • name :プラットフォームで探すシークレットの名前です。このフィールドは特別な文字を含むシークレットも参照できます。名前はそのまま使いますが、プロジェクト名の範囲外では使われ ません

この例では、アプリケーションのデプロイ時に server-certificate<project_name>_server-certificate として作成されます。このとき、 server.cert の内容にはプラットフォームのシークレットが登録されます。

secrets:
  server-certificate:
    file: ./server.cert

あるいは、 server-certificate は外部(external)としての宣言もできます。そのような場合、 Compose 実装は対象サービスで公開されているシークレットから server-certificate を探します。

secrets:
  server-certificate:
    external: true

外部のシークレットを探すにあたり、明確にキーを name で指定しての利用もできます。以下の例は先の例を編集したもので、パラメータ CERTIFICATE_KEY の設定を探します。そのため、デプロイ時に変数が 展開 されたものが設定されますが、 ハードコード(hard-cord) された ID server-certificate としてコンテナに公開されます。

secrets:
  server-certificate:
    external: true
    name: "${CERTIFICATE_KEY}"

Compose ファイルでは、アプリケーション内の関連するサービスに対しては、シークレットに明示的な許可が必要です。

フラグメント(fragment)

設定のフラグメントを YAML アンカー を使って再利用できます。

volumes:
  db-data: &default-volume
    driver: default
  metrics: *default-volume

先述の例では、 db-data ボリューム指定をもとに default-volume としての「 アンカー(anchor) 」を作成します。これは後ほど「 別名(alias)*default-volume としてボリュームの metrics を定義するため再利用されます。同じ仕組みを Compose ファイルの他の要素にも適用できます。アンカーの指定は 変数展開 前に行う必要があるため、変数を使ったアンカーや別名の指定は行えません。

また、 YAML merge タイプ を使うアンカー参照を指定し、部分的に上書きできます。以下の例は metrics ボリューム指定を別名で再利用できませんが、 name 属性を上書きします。

services:
  backend:
    image: awesome/database
    volumes:
      - db-data
      - metrics
volumes:
  db-data: &default-volume
    driver: default
    name: "data"
  metrics:
    <<: *default-volume
    name: "metrics"

拡張(extension)

特別な拡張フィールドは、名前が x- で始まる文字列であれば、どのような形式にも対応します。Compose ファイル内で、あらゆる構造が利用できます。以下の例は、 Compose 実装が認識できないフィールドを、警告なく無視する唯一の例外です。

x-custom:
  foo:
    - bar
    - zot

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

このようなフィールドの内容は Compose 仕様では明示されていないため、任意の機能のために利用できます。 Compose 実装は未知の拡張フィールドを発見した場合、失敗 すべきでありません(MUST NOT) が、未知のフィールドに対する警告は 行えます 。

プラットフォームを拡張するには、プラットフォームやベンダによって提供されている拡張プレフィックスの利用を推奨します。これは、ブラウザに対して 任意の CSS 機能 のサポートを追加するのと同じです。

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

参考となる履歴情報

このセクションは参考情報です。これを書いている時点で、以下プレフィクスの存在が分かっています。

プレフィクス

ベンダー/組織

docker

Docker

kubernetes

Kubernetes

フラグメントとして拡張を使う

拡張フィールドをサポートするため、 Compose ファイルを次のように書き、再利用するフラグメントを読みやすく改善できます。

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

services:
  frontend:
    image: awesome/webapp
    logging: *default-logging
  backend:
    image: awesome/database
    logging: *default-logging

バイト値を指定

バイト値を {量}{バイト単位} 形式の文字列として表記できます。サポートされている単位は b (バイト)、 kb (キロバイト)、 mmb (メガバイト)、 ggb (ギガバイト)です。

2b
1024kb
2048k
300m
1gb

期間を指定

期間を {数値}{単位} 形式の文字列として表記できます。サポ-とされている単位は us (マイクロ秒)、 ms (ミリ秒)、 s (秒)、 m (分)、 h (時間)です。複数の値を区切り文字なく連結できます。

10ms
40s
1m30s
1h5m30s20ms

変数展開(補完)

Compsoe ファイルの値には変数を設定でき、実行時に変数展開できます。 Compose ファイルは Bash 風の構文 ${変数} を使います。

$変数${変数} の両構文をサポートしています。デフォルトの値は、一般的なシェル構文を使い、その途中で記号を使い定義できます。

  • ${変数:-default}変数 が環境変数内で未定義もしくは空白の場合に default と評価します。

  • ${変数:+default}変数 が環境変数内で未定義の場合のみ、 default と評価します。

同じように、以下の構文によって変数の強制を指定できます。

  • ${変数:?err} は、 変数 が環境変数内で未定義か空白の場合、 err を含むエラーメッセージと共に終了します。

  • ${変数?err} は、 変数 が環境変数内で未定義の場合のみ、 err を含むエラーメッセージと共に終了します。

${変数/foo/bar} のような他のシェル風の拡張機能は Compose 仕様ではサポートされていません。

設定で文字列としてのドル記号を使う必要がある場合は、 $$ (二重ドル記号)を使います。また、 $$ は Compose によって値が変数展開されるのを防ぐため、Compose によって処理したくない環境変数の参照にも使えます。

web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"

Compose 仕様が変数展開を解決できず、かつ、デフォルト値が無い場合は、ユーザに対して警告を表示し、手泣きする変数を空白の文字列とする 必要があります(MUST)

Compose ファイル中のあらゆる値は、変数展開によって補完できます。複雑な要素を短くする表記を含めて、(複数の)ファイル単位を統合する前に補完を 適用しなければいけません(MUST)

Compose のドキュメント

参考

Compose specification

https://docs.docker.com/compose/compose-file/