Compose ファイル バージョン 3 リファレンス

読む時間の目安: 43 分

リファレンスとガイドライン

ここに示す内容は Compose ファイルフォーマット、バージョン 3 です。 これが最新バージョンです。

Compose と Docker の互換マトリックス

Compose ファイルフォーマットには 1、2、2.x、3.x という複数のバージョンがあります。 その様子は以下の一覧表に見ることができます。 各バージョンにて何が増えたのか、どのようにアップグレードしたのか、といった詳細については バージョンとアップグレードについてを参照してください。

以下の一覧表は、Compose ファイルのどのバージョンが Docker リリースをサポートしているかを示すものです。

Compose ファイルフォーマット Docker Engine リリース
Compose 仕様 19.03.0 以上
3.8 19.03.0 以上
3.7 18.06.0 以上
3.6 18.02.0 以上
3.5 17.12.0 以上
3.4 17.09.0 以上
3.3 17.06.0 以上
3.2 17.04.0 以上
3.1 1.13.1 以上
3.0 1.13.0 以上
2.4 17.12.0 以上
2.3 17.06.0 以上
2.2 1.13.0 以上
2.1 1.12.0 以上
2.0 1.10.0 以上

この表に示している Compose のファイルフォーマットバージョンに加えて、Compose そのもののリリーススケジュールがあります。 詳しくは Compose リリースに示されています。 しかしファイルフォーマットのバージョンは、個々のリリースに合わせてバージョンアップする必要がありません。 たとえば Compose ファイルフォーマット 3.0 が初めて導入されたのは Compose リリース 1.10.0 ですが、その後のリリースの中で、徐々にバージョンアップを行ってきています。

最新の Compose ファイルフォーマットは Compose 仕様 において定義されていて、Docker Compose 1.27.0 以上 において実装されています。

Compose ファイルの構造と記述例

Here is a sample Compose file from the voting app sample used in the Docker for Beginners lab topic on Deploying an app to a Swarm:


version: "3.9"
services:

  redis:
    image: redis:alpine
    ports:
      - "6379"
    networks:
      - frontend
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

  db:
    image: postgres:9.4
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend
    deploy:
      placement:
        max_replicas_per_node: 1
        constraints:
          - "node.role==manager"

  vote:
    image: dockersamples/examplevotingapp_vote:before
    ports:
      - "5000:80"
    networks:
      - frontend
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
      restart_policy:
        condition: on-failure

  result:
    image: dockersamples/examplevotingapp_result:before
    ports:
      - "5001:80"
    networks:
      - backend
    depends_on:
      - db
    deploy:
      replicas: 1
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 1
      labels: [APP=VOTING]
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 3
        window: 120s
      placement:
        constraints:
          - "node.role==manager"

  visualizer:
    image: dockersamples/visualizer:stable
    ports:
      - "8080:8080"
    stop_grace_period: 1m30s
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
    deploy:
      placement:
        constraints:
          - "node.role==manager"

networks:
  frontend:
  backend:

volumes:
  db-data:

このリファレンスページで取り上げているトピックは、Compose ファイルの構造に合わせて、最上位のキー項目をアルファベット順に示しています。 最上位のキー項目とは、設定ファイルにおいてのセクションを定義するものであり、build、deploy、depends_on、networksなどのことです。 そのキー項目ごとに、それをサポートするオプションをサブトピックとして説明しています。 これは Compose ファイルにおいて<key>: <option>: <value>という形式のインデント構造に対応します。

サービス設定リファレンス

Compose ファイルは YAML 形式のファイルであり、サービス（services）、ネットワーク（networks）、ボリューム（volumes）を定義します。 Compose ファイルのデフォルトパスは./docker-compose.ymlです。

ヒント このファイルの拡張子は.ymlと.yamlのどちらでも構いません。 いずれでも動作します。

サービスの定義とは、そのサービスを起動する各コンテナーに適用される設定を行うことです。 コマンドラインからdocker runのパラメーターを受け渡すことと、非常によく似ています。 同様に、ネットワークの定義、ボリュームの定義は、それぞれdocker network createとdocker volume createのコマンドに対応づくものです。

docker runに関しても同じことが言えますが、Dockerfile にて指定された CMD、EXPOSE、VOLUME、ENVのようなオプションはデフォルトでは維持されます。したがってdocker-compose.ymlの中で再度設定する必要はありません。

設定を記述する際には環境変数を用いることができます。 環境変数は Bash 風に${VARIABLE}のように記述します。 詳しくは変数の置換を参照してください。

このセクションでは、バージョン 3 のサービス定義においてサポートされている設定オプションをすべて説明しています。

build

この設定オプションはビルド時に適用されます。

buildの指定方法の 1 つは、ビルドコンテキストへのパスを表わす文字列を指定します。

version: "3.9"
services:
  webapp:
    build: ./dir

あるいは context の指定のもとにパスを指定し、オプションとして Dockerfile や args を記述する方法をとります。

version: "3.9"
services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1

buildに加えてimageも指定した場合、Compose はビルドイメージに名前をつけます。 たとえば以下のようにimageを指定すると、イメージ名をwebapp、オプションのタグをtagという名前にします。

build: ./dir
image: webapp:tag

結果としてイメージ名はwebappでありtagというタグづけが行われます。 そしてこのイメージは./dirから作り出されます。

docker のスタックデプロイ時のメモ

build オプションは、スウォームモードでのスタックのデプロイ を行う場合には無視されます。 docker stackコマンドは、デプロイするまではイメージをビルドしません。

context

Dockerfile を含むディレクトリへのパスか、あるいは git リポジトリの URL を設定します。

設定された記述が相対パスを表わしている場合、Compose ファイルのあるディレクトリからの相対パスとして解釈されます。 このディレクトリはビルドコンテキストでもあり、Docker デーモンへ送信されるディレクトリです。

Compose は指定された名前により、イメージのビルドとタグづけを行い、後々これを利用します。

build:
  context: ./dir

dockerfile

別の Dockerfile を指定します。

Compose は指定された別の Dockerfile を使ってビルドを行います。 このときは、ビルドパスを同時に指定しなければなりません。

build:
  context: .
  dockerfile: Dockerfile-alternate

args

ビルド引数を追加します。 これは環境変数であり、ビルド処理の間だけ利用可能なものです。

Dockerfile 内にてはじめにビルド引数を指定します。

# syntax=docker/dockerfile:1

ARG buildno
ARG gitcommithash

RUN echo "Build number: $buildno"
RUN echo "Based on commit: $gitcommithash"

そしてbuildキーのもとにその引数を指定します。 指定は個々をマッピングする形式か、リストとする形式が可能です。

build:
  context: .
  args:
    buildno: 1
    gitcommithash: cdc3b19

build:
  context: .
  args:
    - buildno=1
    - gitcommithash=cdc3b19

build 引数の適用範囲

Dockerfile にてFROM命令の前にARG命令を指定した場合、FROM以降のビルド命令においてARGの値は利用することができません。 FROMの前後どこでも、そして特にFROM命令の後でもその値を利用したい場合は、ARG と FROM の関連について を参照してください。

ビルド引数の指定にあたって、その値設定を省略することができます。 この場合、ビルド時におけるその値は、Compose を起動している環境での値になります。

args:
  - buildno
  - gitcommithash

ブール値利用時のメモ

YAML のブール値 ("true", "false", "yes", "no", "on", "off") を用いる場合は、クォートで囲む必要があります。 そうすることで、これらの値は文字列として解釈されます。

cache_from

ファイルフォーマットバージョン 3.2 における追加

エンジンがキャッシュ解決のために利用するイメージを設定します。

build:
  context: .
  cache_from:
    - alpine:latest
    - corp/web_app:3.14

labels

ファイルフォーマットバージョン 3.3 における追加

Docker labels を使ってイメージにメタデータを追加します。 配列形式と辞書形式のいずれかにより指定します。

ここでは逆 DNS 記法とすることが推奨されます。 この記法にしておけば、他のソフトウェアが用いるラベルとの競合が避けられるからです。

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

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

network

ファイルフォーマットバージョン 3.4 における追加。

ビルド中のRUN命令において、ネットワークコンテナーの接続先を設定します。

build:
  context: .
  network: host

build:
  context: .
  network: custom_network_1

noneを指定すると、ビルド中のネットワークを無効にします。

build:
  context: .
  network: none

shm_size

ファイルフォーマットバージョン 3.5 において追加されました。

このビルドコンテナーにおける/dev/shmパーティションのサイズを設定します。 指定する値は、バイト数を表わす整数値か、あるいは バイト表現 によって表わされる文字列とします。

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

target

ファイルフォーマットバージョン 3.4 において追加されました。

Dockerfile内部に定義されている特定のステージをビルドする方法は、マルチステージビルド を参照してください。

build:
  context: .
  target: prod

cap_add, cap_drop

コンテナーケーパビリティーの機能を追加または削除します。 詳細な一覧はman 7 capabilitiesを参照してください。

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

docker のスタックデプロイ時のメモ

cap_addオプションとcap_dropオプションは、スウォームモードでのスタックのデプロイ を行う場合には無視されます。

cgroup_parent

コンテナーに対して、オプションで指定する親の cgroup を指定します。

cgroup_parent: m-executor-abcd

docker のスタックデプロイ時のメモ

cgroup_parentオプションは、スウォームモードでのスタックのデプロイ を行う場合には無視されます。

command

デフォルトコマンドを上書きします。

command: bundle exec thin -p 3000

このコマンドは dockerfile の場合と同じように、リスト形式により指定することもできます。

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

configs

サービスごとのconfigsを利用して、サービス単位での configs 設定を許可します。 2 つの異なる文法がサポートされています。

メモ: config は既に定義済であるか、あるいは 最上位のconfigsが定義済 である必要があります。 そうでない場合、このファイルによるデプロイが失敗します。

configs に関する詳細は configs を参照してください。

短い文法

短い文法の場合には config 名を指定するのみです。 これを行うと、コンテナー内において/<config_name>というディレクトリをマウントしてアクセス可能とします。 マウント元の名前とマウント名はともに config 名となります。

以下の例では短い文法を用います。 redisサービスが 2 つの configs ファイルmy_configとmy_other_configにアクセスできるようにするものです。 my_configへは、ファイル./my_config.txtの内容を設定しています。 そしてmy_other_configは外部リソースとして定義します。 これはつまり Docker によりすでに定義されていることを意味し、docker config createの実行により、あるいは別のスタックデプロイメントにより指定されます。 外部 config が存在していない場合は、スタックデプロイメントは失敗しconfig not foundというエラーになります。

ファイルフォーマットバージョン 3.3 における追加

config定義は、Compose ファイルフォーマットのバージョン 3.3 またはそれ以上においてサポートされています。

version: "3.9"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

長い文法

長い文法は、サービスのタスクコンテナー内にて生成する config をより細かく設定します。

  • source＝ この設定ファイル内において定義される config の識別子。
  • target＝ サービスのタスクコンテナー内にマウントされるファイルパス名。 指定されない場合のデフォルトは /<source>。
  • uidとgid＝ サービスのタスクコンテナー内にマウントされる config ファイルの所有者を表わす UID 値および GID 値。 指定されない場合のデフォルトは、Linux においては 0。 Windows においてはサポートされません。
  • mode＝ サービスのタスクコンテナー内にマウントされる config ファイルのパーミッション。 8 進数表記。 たとえば0444であればすべて読み込み可。 デフォルトは 0444。 Configs は、テンポラリなファイルシステム上にマウントされるため、書き込み可能にはできません。 したがって書き込みビットを設定しても無視されます。 実行ビットは設定できます。 UNIX のファイルパーミッションモードに詳しくない方は、パーミッション計算機 を参照してください。

以下の例ではmy_configという名前の config を、コンテナー内ではredis_configとして設定します。 そしてモードを 0440（グループが読み込み可能）とし、ユーザーとグループは103とします。 redisサービスはmy_other_configへはアクセスしません。

version: "3.9"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - source: my_config
        target: /redis_config
        uid: '103'
        gid: '103'
        mode: 0440
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

1 つのサービスが複数の configs にアクセスする設定とすることもできます。 また短い文法、長い文法を混在することも可能です。 config を定義しただけでは、サービスに対して config へのアクセスを許可するものにはなりません。

container_name

デフォルトのコンテナー名ではない、独自のコンテナー名を設定します。

container_name: my-web-container

Docker コンテナー名はユニークである必要があります。 そこで独自のコンテナー名を設定したときは、サービスをスケールアップして複数コンテナーとすることはできません。 これを行うとエラーが発生します。

docker のスタックデプロイ時のメモ

container_nameオプションは、スウォームモードでのスタックのデプロイ を行う場合には無視されます。

credential_spec

ファイルフォーマットバージョン 3.3 における追加

credential_specオプションは v3.3 で追加されました。 Compopse ファイルにおける group Managed Service Account (gMSA) の設定は Compose バージョン 3.8 においてサポートされています。

管理サービスアカウントに対する資格情報スペック（credential_spec）を設定します。 このオプションは Windows コンテナーを利用するサービスにおいてのみ用いられます。 credential_specの書式はfile://<filename>またはregistry://<value-name>でなければなりません。

file:を用いるとき、参照するファイルは実際に存在するファイルでなければならず、Docker データディレクトリ配下のサブディレクトリCredentialSpecsになければなりません。 Windows における Docker データディレクトリのデフォルトはC:\ProgramData\Docker\です。 以下の例はファイルから資格情報スペックを読み込みます。 C:\ProgramData\Docker\CredentialSpecs\my-credential-spec.json.

credential_spec:
  file: my-credential-spec.json

registry:を用いるとき資格情報スペックは、デーモンホスト内の Windows レジストリから読み込まれます。 指定された名称のレジストリ値は、以下に定義されている必要があります。

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

以下の例は、レジストリ内のmy-credential-specという値から資格情報スペックを読み込みます。

credential_spec:
  registry: my-credential-spec

gMSA の設定例

サービスに対して credential spec における gMSA を設定する場合、credential spec のconfigを設定するだけです。 その例を以下に示します。

version: "3.9"
services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

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

depends_on

サービス間の依存関係を表わします。 サービスに依存関係があると、以下の動作になります。

  • docker-compose upは依存関係の順にサービスを起動します。 以下の例においてdbとredisはwebの前に起動されます。
  • docker-compose up SERVICEを実行するとSERVICEにおける依存関係をもとに動作します。 後述の例においてdocker-compose up webを実行するとdbとredisを生成して起動します。
  • docker-compose stopは依存関係の順にサービスを停止します。 以下の例においてはwebが停止されてからdbとredisが停止されます。

以下がその簡単な例です。

version: "3.9"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

depends_onの利用にあたっては、気をつけておくべきことがあります。

  • depends_onではdbやredisが「準備」状態になるのを待たずに、つまりそれらを開始したらすぐにwebを起動します。 準備状態になるのを待ってから次のサービスを起動することが必要な場合は、Compose における起動順の制御にて示す内容と解決方法を確認してください。
  • Compose ファイルバージョン 3 においてdepends_onオプションは、スウォームモードでのスタックのデプロイ を行う場合には無視されます。

deploy

ファイルフォーマットバージョン 3 における追加

サービスのデプロイや起動に関する設定を行います。 以下に示すサブオプションが有効になるのは スウォーム に対して docker stack deploy コマンドを実行したときです。 resourcesは除き、docker-compose upやdocker-compose runを実行したときには無視されます。

version: "3.9"
services:
  redis:
    image: redis:alpine
    deploy:
      replicas: 6
      placement:
        max_replicas_per_node: 1
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

利用可能なサブオプションがあります。

endpoint_mode

ファイルフォーマットバージョン 3.2 における追加。

スウォームに接続する外部クライアントのサービスディスカバリー方法を指定します。

  • endpoint_mode: vip - Docker はサービスに対して仮想 IP（virtual IP; VIP）を割り当てます。 これはネットワーク上のサービスに対して、クライアントがアクセスできるようにするためのフロントエンドとして機能します。 Docker がサービスに参加する稼動中のワーカーノードやクライアントの間でリクエストを受け渡ししている際に、クライアントはそのサービス上にどれだけの数のノードが参加しているのか、その IP アドレスやポートが何なのか、一切分かりません。 （この設定がデフォルトです。）

  • endpoint_mode: dnsrr - DNS ラウンドロビン（DNS round-robin; DNSRR）によるサービスディスカバリーでは、仮想 IP は単一ではありません。 Docker はサービスに対する DNS エントリーを設定し、サービス名に対する DNS クエリーが IP アドレスのリストを返すようにします。 クライアントはそのうちの 1 つに対して直接アクセスします。 DNS ラウンドロビンが有効なのは、独自のロードバランサーを利用したい場合や、Windows と Linux が統合されたアプリケーションに対して利用する場合です。

version: "3.9"

services:
  wordpress:
    image: wordpress
    ports:
      - "8080:80"
    networks:
      - overlay
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: vip

  mysql:
    image: mysql
    volumes:
       - db-data:/var/lib/mysql/data
    networks:
       - overlay
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: dnsrr

volumes:
  db-data:

networks:
  overlay:

endpoint_modeに対する設定は、スウォームモードの CLI コマンド docker service create におけるフラグとしても動作します。 スウォームに関連するdockerコマンドの一覧は スウォームモード CLI コマンド を参照してください。

スウォームモードにおけるサービスディスカバリーやネットワークに関しての詳細は、スウォームモードのトピックにある サービスディスカバリーの設定 を参照してください。

labels

サービスに対してのラベルを設定します。 このラベルはサービスに対してのみ設定するものであって、サービスのコンテナーに設定するものではありません。

version: "3.9"
services:
  web:
    image: web
    deploy:
      labels:
        com.example.description: "This label will appear on the web service"

コンテナーにラベルを設定するのであれば、deployの外にlabelsキーを記述してください。

version: "3.9"
services:
  web:
    image: web
    labels:
      com.example.description: "This label will appear on all containers for the web service"

mode

global（スウォームノードごとに 1 つのコンテナーとする）か、replicated（指定されたコンテナー数とするか）のいずれかを設定します。 デフォルトはreplicatedです。 （詳しくは スウォームのトピックにある サービスの Replicated と global を参照してください。）

version: "3.9"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    deploy:
      mode: global

placement

制約（constraints）とプリファレンス（preferences）の記述場所を指定します。 docker service create のドキュメントには、制約、プリファレンス、各ノードごとの最大レプリカ数の設定 に関しての文法と設定可能な型について、詳細に説明しているので参照してください。

version: "3.9"
services:
  db:
    image: postgres
    deploy:
      placement:
        constraints:
          - "node.role==manager"
          - "engine.labels.operatingsystem==ubuntu 18.04"
        preferences:
          - spread: node.labels.zone

max_replicas_per_node

ファイルフォーマットバージョン 3.8 における追加。

サービスを replicated（デフォルト）に設定しているとき、ノード上において稼動可能な レプリカ数の上限 を定めます。

稼動中のノード数以上に、タスクが要求された場合、no suitable node (max replicas per node limit exceed)（十分なノードがない (ノードごとの最大レプリカ数の上限オーバー)）というエラーが発生します。

version: "3.9"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6
      placement:
        max_replicas_per_node: 1

replicas

サービスを replicated（デフォルト）に設定しているときに、起動させるコンテナー数を指定します。

version: "3.9"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6

resources

リソースの制約を設定します。

compose ファイルバージョン 3 における変更

resourcesのセクションは Compose ファイルバージョン 3 以前の リソースに対する古い制約オプション （cpu_shares, cpu_quota, cpuset, mem_limit, memswap_limit, mem_swappiness）に置き換わるものです。 compose ファイルのバージョン 2 と 3 の違いについては バージョン 2.x から 3.x へのアップグレード を参照してください。

個々の設定には単一の値を指定します。 これは docker service create のオプションに対応づきます。

以下の一般的な例はredisサービスに制約をつけるものです。 メモリ利用は 50M まで、利用可能なプロセス時間（CPU）は 0.50（シングルコアの 50%）まで。 最低メモリは20M確保し（常時利用可能な） CPU 時間は0.25とします。

version: "3.9"
services:
  redis:
    image: redis:alpine
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
        reservations:
          cpus: '0.25'
          memory: 20M

以下では、スウォーム内のサービスやコンテナーに設定できるリソース制約を説明します。

スウォームモードではないコンテナーでのリソース設定を探していますか？

ここに説明している設定は、スウォームモードで利用するdeployキーにおけるオプションです。 スウォームモードではないデプロイメントにおけるリソース制約を設定したい場合は、Compose ファイルバージョン 2 における CPU、メモリなどに関するリソースオプション を参照してください。 それでもよくわからない場合は、GitHub 上にあげられている議論 docker/compose/4513 を参照してください。

Out Of Memory Exceptions (OOME)

サービスやコンテナーが、システムにおいて利用可能なメモリ容量以上を利用しようとして、Out Of Memory Exception (OOME) が発生するということがあります。 コンテナーあるいは Docker デーモンは、このときカーネルの OOM killer によって強制終了させられます。 これが発生しないようにするためには、ホスト上で動作させるアプリケーションのメモリ利用を適切に行うことが必要です。 メモリ不足のリスクへの理解 を参照してください。

restart_policy

コンテナーが終了した後に、いつどのようにして再起動するかを設定します。 restart に置き換わるものです。

  • condition: none, on-failure, anyのいずれかを指定します。（デフォルト: any）
  • delay: 再起動までどれだけの間隔をあけるかを 時間 として指定します。 （デフォルト: 5s）
  • max_attempts: 再起動に失敗しても何回までリトライするかを指定します。 （デフォルト: 無制限） 設定したwindow時間内に再起動が成功しなかったとしても、そのときの再起動リトライは、max_attemptsの値としてカウントされません。 たとえばmax_attemptsが2として設定されていて、1 回めの再起動が失敗したとします。 この場合、2 回以上の再起動が発生する可能性があります。
  • window: 再起動が成功したかどうかを決定するためにどれだけ待つかを 時間 として指定します。 （デフォルト: 即時）
version: "3.9"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

rollback_config

ファイルフォーマットバージョン 3.7 における追加

サービスの更新が失敗した場合に、どのようにしてロールバックするかを設定します。

  • parallelism: 一度にロールバックするコンテナー数を指定します。 0 を指定した場合、コンテナーすべてが同時にロールバックされます。
  • delay: コンテナーグループごとのロールバックの間をどれだけ待つかを指定します。（デフォルト 0s）
  • failure_action: ロールバックが失敗したときにどうするかを指定します。 continue、 pauseのいずれかです。（デフォルトpause）
  • monitor: 各タスク更新後に失敗を監視する時間(ns|us|ms|s|m|h)を設定します。 （デフォルト： 5s）メモ 0 に設定するとデフォルト値 5s が用いられます。
  • max_failure_ratio: ロールバック時の失敗許容率を設定します。（デフォルト 0）
  • order: ロールバック時の処理順を設定します。 stop-first（古いタスクを停止してから新しいタスクを実行する）、あるいはstart-first（新しいタスクをまず起動させ、タスク起動を一時的に重複させる）のいずれかを設定します。 （デフォルト： stop-first）

update_config

どのようにサービスを更新するかを設定します。 Rolling update を設定する際に有効です。

  • parallelism： 一度に更新を行うコンテナー数を設定します。
  • delay： 一連のコンテナーを更新する時間を設定します。
  • failure_action： 更新に失敗したときの動作を設定します。 continue、rollback、pauseのいずれかです。 （デフォルト： pause）
  • monitor: 各タスク更新後に失敗を監視する時間(ns|us|ms|s|m|h)を設定します。 （デフォルト： 5s）メモ 0 に設定するとデフォルト値 5s が用いられます。
  • max_failure_ratio: 更新時の失敗許容率を設定します。
  • order: 更新時の処理順を設定します。 stop-first（古いタスクを停止してから新しいタスクを実行する）、あるいはstart-first（新しいタスクをまず起動させ、タスク起動を一時的に重複させる）のいずれかを設定します。 （デフォルト： stop-first） メモ: v3.4 またはそれ以上においてのみサポートされます。

ファイルフォーマットバージョン 3.4 における追加

orderオプションは Compose ファイルフォーマット v3.4 およびそれ以上においてのみサポートされます。

version: "3.9"
services:
  vote:
    image: dockersamples/examplevotingapp_vote:before
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s
        order: stop-first

docker stack deployでサポートされないオプション

以下に示すサブオプション（docker-compose upとdocker-compose runにおいてサポートされるオプション）は、docker stack deployまたはdeployキーにおいては サポートされません 。

ヒント

サービス、スウォーム、docker-stack.yml ファイルにおけるボリューム設定方法 にある説明を確認してください。 ボリュームはサポートされますが、これはスウォームとサービスに対してです。 ボリュームは名前つきとして設定されるか、あるいは必要なボリュームにアクセスするノードのみから構成されるサービスに関連づけられている必要があります。

devices

デバイスのマッピングをリスト形式で設定します。 Docker クライアントの create オプションと同じ書式にします。

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"

docker のスタックデプロイ時のメモ

devicesオプションは、スウォームモードでのスタックのデプロイを行う場合には無視されます。

dns

DNS サーバーを設定します。 設定は 1 つだけとするか、リストにすることができます。

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

DNS 検索ドメインを設定します。 設定は 1 つだけとするか、リストにすることができます。

dns_search: example.com

dns_search:
  - dc1.example.com
  - dc2.example.com

entrypoint

デフォルトのエントリーポイントを上書きします。

entrypoint: /code/entrypoint.sh

エントリーポイントはリスト形式で設定することができます。 その指定方法は dockerfile と同様です。

entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]

メモ

entrypointを設定すると、サービスイメージ内に Dockerfile 命令のENTRYPOINTによって設定されているデフォルトのエントリーポイントは上書きされ、さらにイメージ内のあらゆるデフォルトコマンドもクリアされます。 これはつまり、Dockerfile にCMD命令があったとしたら無視されるということです。

env_file

ファイルを用いて環境変数を追加します。 設定は 1 つだけとするか、リストにすることができます。

Compose ファイルをdocker-compose -f FILEという起動により指定している場合、env_fileにおけるパスは、Compose ファイルがあるディレクトリからの相対パスとします。

環境変数が environment の項に宣言されていれば、ここでの設定をオーバーライドします。 たとえ設定値が空や未定義であっても、これは変わりません。

env_file: .env

env_file:
  - ./common.env
  - ./apps/web.env
  - /opt/runtime_opts.env

env ファイルの各行はVAR=VALの書式とします。 行先頭に#があると、コメント行となり無視されます。 空行も無視されます。

# Set Rails/Rack environment
RACK_ENV=development

Compose では以下のようなインラインコメントも認識されます。

MY_VAR = value # これはコメントです。

”#” がインラインコメントとして解釈されないようにするには、クォーテーション記号を使います。

MY_VAR = "この中にある # はすべて値の一部として扱われます"

メモ

サービスに build オプションを指定している場合、env ファイル内に定義された変数は、ビルド時にこのままでは自動的に参照されません。 その場合はbuildのサブオプション args を利用して、ビルド時の環境変数を設定してください。

VALの値は記述されたとおりに用いられ、一切修正はされません。 たとえば値がクォートにより囲まれている（よくシェル変数に対して行う）場合、クォートもそのまま値として Compose に受け渡されます。

ファイルを複数用いる場合の順番には気をつけてください。 特に何度も出現する変数に対して、値がどのように決定されるかです。 ファイルが複数指定された場合、その処理は上から順に行われます。 たとえばa.envファイルに変数が指定されていて、b.envファイルには同じ変数が異なる値で定義されていたとします。 ここでb.envファイルが下に（後に）指定されているとします。 このとき変数の値はb.envのものが採用されます。 さらに例としてdocker-compose.ymlに以下のような宣言があったとします。

services:
  some-service:
    env_file:
      - a.env
      - b.env

ファイルの内容は以下であるとします。

# a.env
VAR=1

# b.env
VAR=hello

この結果$VARはhelloになります。

environment

環境変数を追加します。 配列形式または辞書形式での指定が可能です。 ブール値true、false、yes、noを用いる場合は、クォートで囲むことで YML パーサーによって True や False に変換されてしまうのを防ぐ必要があります。

環境変数だけが記述されている場合は、Compose が起動しているマシン上にて定義されている値が設定されます。 これは機密情報やホスト固有の値を設定する場合に利用できます。

environment:
  RACK_ENV: development
  SHOW: 'true'
  SESSION_SECRET:

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

メモ

サービスに build オプションを指定している場合、env ファイル内に定義された変数は、ビルド時にこのままでは自動的に参照されません。 その場合はbuildのサブオプション args を利用して、ビルド時の環境変数を設定してください。

expose

ホストマシンにはポートを公開せずに、ポートを expose します。 これはリンクされたサービスのみアクセスが可能になります。 内部ポートのみが指定できます。

expose:
  - "3000"
  - "8000"

今のdocker-compose.ymlからではない別のところから起動されたコンテナーをリンクします。 あるいは Compose の外から、特に共有サービスや汎用サービスとして提供されるコンテナーをリンクします。 external_linksの文法は、かつてのオプションlinksと同様です。 つまりコンテナー名とリンクのエイリアス名（CONTAINER:ALIAS）を同時に指定します。

external_links:
  - redis_1
  - project_db_1:mysql
  - project_db_1:postgresql

メモ

外部にて生成されたコンテナーをネットワークに接続する場合は、そのコンテナーがサービスとしてリンクしているネットワークのうちの 1 つでなければなりません。 Links は古いオプションです。 これではなく networks を用いるようにしてください。

docker のスタックデプロイ時のメモ

external_linksオプションは、スウォームモードでのスタックのデプロイ を行う場合には無視されます。

extra_hosts

ホスト名のマッピングを追加します。 Docker Client の--add-hostパラメーターと同じ値を設定してください。

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

ホスト名と IP アドレスによるこの設定内容は、サービスコンテナー内の/etc/hostsに追加されます。 たとえば以下のとおりです。

162.242.195.82  somehost
50.31.209.229   otherhost

healthcheck

このサービスを起動させているコンテナーが「健康」（healthy）かどうかを確認する処理を設定します。 ヘルスチェックがどのように動作するのかの詳細は Dockerfile の HEALTHCHECK 命令 を参照してください。

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

interval, timeout, start_periodは 時間 を設定します。

ファイルフォーマットバージョン 3.4 における追加

start_periodオプションはファイルフォーマットバージョン 3.4 またはそれ以上においてのみサポートされます。

testは 1 つの文字列かリスト形式である必要があります。 リスト形式の場合、第 1 要素は必ずNONE、CMD、CMD-SHELLのいずれかとします。 文字列の場合は、CMD-SHELLに続けてその文字列を指定することと同じになります。

# ローカルのウェブアプリにアクセスします。
test: ["CMD", "curl", "-f", "http://localhost"]

上と同様ですが、次は/bin/shによってラップされます。 なお以下の 2 つの書式は同じことです。

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

test: curl -f https://localhost || exit 1

イメージが設定するデフォルトのヘルスチェックを無効にするには、disable: trueを指定します。 これはtest: ["NONE"]と指定することと同じです。

healthcheck:
  disable: true

image

コンテナーを起動させるイメージを設定します。 リポジトリ/タグの形式か、あるいは部分イメージ ID により指定します。

image: redis

image: ubuntu:18.04

image: tutum/influxdb

image: example-registry.com:4000/postgresql

image: a4bc65fd

イメージが存在しなかった場合、build を指定していなければ Compose はイメージを取得しようとします。 取得する際には、指定されたオプションを使ってビルドを行い、指定されたタグ名によりタグづけを行います。

init

ファイルフォーマットバージョン 3.7 における追加

コンテナー内にて init を実行し、シグナルを送信してプロセスを停止させます。 このオプションにtrueを設定することで、サービスに対するこの機能を有効にします。

version: "3.9"
services:
  web:
    image: alpine:latest
    init: true

利用されるデフォルトの init の実行モジュールは Tini であり、デーモンホストの/usr/libexec/docker-initにインストールされています。 デーモンに対して独自の init 実行モジュールを設定するには、init-path設定オプション を利用します。

isolation

コンテナーの分離技術（isolation technology）を設定します。 Linux においてサポートされるのはdefaultのみです。 Windows ではdefault、process、hypervの設定が可能です。 詳しくは Docker Engine ドキュメント を参照してください。

labels

Docker labels を使ってコンテナーにメタデータを追加します。 配列形式と辞書形式のいずれかにより指定します。

他のソフトウェアが用いるラベルとの競合を避けるため、逆 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"

警告

--linkフラグはすでに古い機能であり、そのうち削除されるかもしれません。 このフラグを利用し続ける必要が明確にないのであれば、ユーザー定義のネットワーク を利用することをお勧めします。 そうすれば--linkを用いなくても、2 つのコンテナー間での通信を実現できます。

ただしユーザー定義のネットワークではサポートされない機能が 1 つあります。 それは--linkであれば、コンテナー間で環境変数を共有できるという点です。 もっともボリュームなどの他のメカニズムを利用すれば、コンテナー間での環境変数の共有は可能であり、その方がより制御しやすい方法になります。

他サービスのコンテナーをリンクします。 サービス名とリンクのエイリアス名（"SERVICE:ALIAS"）を指定するか、直接サービス名を指定します。

web:
  links:
    - "db"
    - "db:database"
    - "redis"

リンクされたサービスのコンテナーは、エイリアスと同等のホスト名により到達可能になります。 エイリアスが設定されていない場合はサービス名により到達可能です。

Links はサービスを通信可能とするために必要になるものではありません。 デフォルトで各サービスは、サービス名を使って他サービスにアクセスすることができます。 （Compose ネットワークにおける Links のトピック も参照してください。）

Links は depends_on と同様にサービス間の依存関係を表わします。 したがってサービスの起動順を設定するものになります。

メモ

links と networks をともに設定する場合、リンクするサービスは、少なくとも 1 つのネットワークが共有され通信ができるようにする必要があります。

docker のスタックデプロイ時のメモ

Compose ファイルバージョン 3 においてこのオプションは、スウォームモードでのスタックのデプロイを行う場合には無視されます。

logging

サービスに対するログ記録の設定をします。

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

driver名にはサービスコンテナーにおけるログドライバーを指定します。 これは docker run コマンドに対する--log-driverオプションと同じです。 （ドキュメントはこちら）

デフォルトは json-file です。

driver: "json-file"

driver: "syslog"

driver: "none"

メモ

ドライバーのうちjson-fileとjournaldだけが、docker-compose upとdocker-compose logsによって直接ログ参照ができます。 その他のドライバーではログ表示は行われません。

ログドライバーへのログオプションの設定はoptionsキーにより行います。 これはdocker runコマンドの--log-optオプションと同じです。

ログオプションはキーバリューのペアで指定します。 たとえばsyslogオプションは以下のようになります。

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

デフォルトドライバーである json-file には、保存するログの容量を制限するオプションがあります。 これを利用する場合は、キーバリューのペアを使って、最大保存容量（max-size）と最大ファイル数（max-file）を指定します。

options:
  max-size: "200k"
  max-file: "10"

上に示した例では、max-sizeに指定された 200 KB に達するまでログファイルへの出力を行います。 最大値に達するとログをローテートします。 保存するログファイル数はmax-fileにより指定します。 ログ出力が上限数を越えた場合、古いログファイルは削除され、新たなログファイルへの保存が行われます。

以下に示すのはdocker-compose.ymlファイルにおいてログ保存の制限を行う例です。

version: "3.9"
services:
  some-service:
    image: some-service
    logging:
      driver: "json-file"
      options:
        max-size: "200k"
        max-file: "10"

利用可能なログオプションはログドライバーに依存

上で示した例においては、ログファイルや容量を制御するために json-file ドライバー に固有のオプションを利用しました。 このようなオプションはその他のログドライバーでは利用できません。 サポートされるログドライバーと個々のオプションについては ログドライバー を参照してください。

network_mode

ネットワークモードを設定します。 Docker クライアントの--networkパラメーターと同じ値を設定します。 これに加えてservice:[service name]という特別な書式も指定可能です。

network_mode: "bridge"

network_mode: "host"

network_mode: "none"

network_mode: "service:[service name]"

network_mode: "container:[container name/id]"

メモ

networks

ネットワークへの参加を設定します。 設定には 最上位のnetworksキー に設定された値を用います。

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

aliases

ネットワーク上のサービスに対して、ホスト名の別名となるエイリアスを設定します。 同じネットワーク上にある他のコンテナーは、この 1 つのサービスコンテナーに対して、サービス名か、あるいはそのエイリアスを使ってアクセスすることができます。

aliasesはネットワーク範囲内において有効です。 ネットワークが異なれば、同一サービスに違うエイリアスを持たせることができます。

メモ

ネットワーク全体にわたってのエイリアスを複数コンテナー間で共有することができます。 それは複数サービス間でも可能です。 ただしこの場合、名前解決がどのコンテナーに対して行われるかは保証されません。

一般的な書式は以下のとおりです。

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

以下の例では 3 つのサービス（web, worker, db）と 2 つのネットワーク（newとlegacy）を提供します。 dbサービスはnewネットワーク上では、ホスト名dbあるいはdatabaseとしてアクセスできます。 一方legacyネットワーク上ではdbあるいはmysqlとしてアクセスできます。

version: "3.9"

services:
  web:
    image: "nginx:alpine"
    networks:
      - new

  worker:
    image: "my-worker-image:latest"
    networks:
      - legacy

  db:
    image: mysql
    networks:
      new:
        aliases:
          - database
      legacy:
        aliases:
          - mysql

networks:
  new:
  legacy:

ipv4_address, ipv6_address

サービスをネットワークに参加させる際、そのコンテナーに対してスタティック IP アドレスを設定します。

最上位の networks セクション の対応するネットワーク設定においては、ipamブロックが必要です。 そこでは各スタティックアドレスに応じたサブネットの設定が必要になります。

IPv6 を利用したい場合は、まず Docker デーモンが IPv6 に対応するものとして設定されていることを確認します。 詳細な手順については IPv6 の有効化 を参照してください。 Compose バージョン 3.x であれば/etc/docker/daemon.jsonファイルを編集して、IPv6 のアドレス設定部分を指定します。 そこでは以下のような内容とします。 {"ipv6": true, "fixed-cidr-v6": "2001:db8:1::/64"}

そして Docker デーモンを再ロードして、docker-compose.yml 内に以下のようにサービス配下の指定を行います。

    sysctls:
      - net.ipv6.conf.all.disable_ipv6=0

enable_ipv6 オプションは Compose ファイルバージョン 2.x でのみ利用可能です。 IPv6 オプションは、現時点ではスウォームモード内で動作しません。

以下に例を示します。

version: "3.9"

services:
  app:
    image: nginx:alpine
    networks:
      app_net:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

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

pid

pid: "host"

PID モードをホスト PID モードに設定します。 これはコンテナーとホストオペレーティングシステムとの間で、PID アドレス空間の共有を開始します。 このフラグを使って起動したコンテナーは、ベアメタルマシンの名前空間にあるコンテナーにアクセスし、操作することが可能になります。 逆もまた可能です。

ports

公開用ポートを設定します。

メモ

ポートマッピングはnetwork_mode: hostとは互換性がありません。

メモ

docker-compose runは--service-portsを指定しない限りportsを無視します。

短い文法

書き方は 3 通りあります。

  • 両方のポートを指定する場合（HOST:CONTAINER）
  • コンテナー側のポートを指定する場合（ホスト側のポートとしてはエフェメラルなホストポートが設定されます）
  • ホストの IP アドレスがバインドされる先と両ポートを指定する場合（デフォルトは 0.0.0.0 であり全インターフェースを意味します）（IPADDR:HOSTPORT:CONTAINERPORT） HOSTPORT が空の場合（たとえば127.0.0.1::80）、ホスト上においてエフェメラルなポートが設定されます。

メモ

HOST:CONTAINERの書式によってポートをマッピングした場合に、コンテナー側のポートが 60 番未満であるとエラーになることがあります。 これは YAML パーサーがxx:yyの書式内にある数値を 60 進数値として解釈するからです。 このことからポートマッピングを指定する際には、常に文字列として設定することをお勧めします。

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"
  - "127.0.0.1::5000"
  - "6060:6060/udp"
  - "12400-12500:1240"

長い文法

長い文法は追加の設定項目が加えられていて、短い文法では表現できないものです。

  • target: コンテナー内部のポート。
  • published: 公開ポート。
  • protocol: ポートプロトコル。（tcpまたはudp）
  • mode: hostは各ノード向けにホストポートを公開、またingressはロードバランスを行うためのスウォームモードポート。
ports:
  - target: 80
    published: 8080
    protocol: tcp
    mode: host

ファイルフォーマットバージョン 3.2 における追加

長い文法は v3.2 から導入されました。

profiles

profiles: ["frontend", "debug"]
profiles:
  - frontend
  - debug

profilesは、名前つきプロファイルに従ってサービスが有効になる、そういったプロファイルの一覧を定義します。 これが設定されていない場合、サービスは 常に 有効です。 重要なアプリケーションを構成するサービスに対しては、このprofilesは省略して、常にそのサービスは起動するようにしてください。

適正なプロファイル名は、正規表現[a-zA-Z0-9][a-zA-Z0-9_.-]+に従うものです。

プロファイルの詳細については Compose におけるプロファイル利用 も参照してください。

restart

再起動ポリシー（restart policy）のデフォルトはnoです。 この場合はどういう状況であってもコンテナーは再起動しません。 alwaysを指定した場合、コンテナーは常に再起動することになります。 またon-failureポリシーでは、終了コードが on-failure エラーを表わしている場合にコンテナーが再起動します。 unless-stoppedは、コンテナーが（手動で、あるいは別の原因で）停止する場合を除き、常にコンテナーが再起動します。

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

docker のスタックデプロイ時のメモ

Compose ファイルバージョン 3 においてこのオプションは、スウォームモードでのスタックのデプロイ を行う場合には無視されます。

secrets

各サービスごとのsecrets設定を用いて、個々のサービスごとに secrets へのアクセスを許可します。 2 つの異なる文法がサポートされています。

docker のスタックデプロイ時のメモ

secrets は既に定義済であるか、あるいは 最上位のsecretsが定義済 である必要があります。 そうでない場合、このファイルによるデプロイが失敗します。

secrets に関する詳細は secrets を参照してください。

短い文法

短い文法では secret 名を指定することだけができます。 これを行うと、コンテナーが secret にアクセスできるようになり、secret はコンテナー内の/run/secrets/<secret_name>にマウントされます。 ソース元となる名前とマウントポイント名は、ともに secret 名となります。

以下の例では短い文法を使って、redisサービスが 2 つの secret、つまりmy_secretとmy_other_secretにアクセスできるようにします。 my_secretの値には./my_secret.txtファイルに含まれる内容を設定します。 my_other_secretは外部リソースとして定義し、それはつまり Docker において定義済の内容を用います。 これはdocker secret createコマンドの実行か、あるいは別のスタックデプロイメントにより与えられます。 外部 secret が存在しなかった場合、スタックデプロイメントは失敗しsecret not foundといったエラーが発生します。

version: "3.9"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - my_secret
      - my_other_secret
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

長い文法

長い文法ではさらに細かな設定として、サービスタスクのコンテナー内にて secret をどのように生成するかを設定します。

  • source＝ この設定ファイル内において定義される secret の識別子。
  • target: サービスのタスクコンテナーにおいて/run/secrets/にマウントされるファイル名。 指定されなかった場合のデフォルトはsourceとなる。

  • uidとgid: サービスのタスクコンテナーにおいて/run/secrets/内のファイルを所有する UID 値と GID 値。

    指定されなかった場合のデフォルトはいずれも0。

  • mode: サービスのタスクコンテナーにおいて/run/secrets/にマウントされるファイルのパーミッション。 8 進数表記。 たとえば0444であればすべて読み込み可。 Docker 1.13.1 におけるデフォルトは0000でしたが、それ以降では0444となりました。 secrets はテンポラリなファイルシステム上にマウントされるため、書き込み可能にはできません。 したがって書き込みビットを設定しても無視されます。 実行ビットは設定できます。 UNIX のファイルパーミッションモードに詳しくない方は、パーミッション計算機 を参照してください。

以下の例ではmy_secretという名前の secret を、コンテナー内ではredis_secretとして設定します。 そしてモードを 0440（グループが読み込み可能）とし、ユーザーとグループは103とします。 redisサービスはmy_other_secretへはアクセスしません。

version: "3.9"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - source: my_secret
        target: redis_secret
        uid: '103'
        gid: '103'
        mode: 0440
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

1 つのサービスが複数の secrets にアクセスする設定とすることもできます。 また短い文法、長い文法を混在することも可能です。 secret を定義しただけでは、サービスに対して secret へのアクセスを許可するものにはなりません。

security_opt

各コンテナーにおけるデフォルトのラベリングスキーム（labeling scheme）を上書きします。

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

docker のスタックデプロイ時のメモ

security_optオプションは、スウォームモードでのスタックのデプロイ を行う場合には無視されます。

stop_grace_period

コンテナーが SIGKILL を送信するまでに、SIGTERM（あるいは stop_signal によって設定されたストップシグナル）をどれだけ待つかを設定します。 指定には 時間 を用います。

stop_grace_period: 1s

stop_grace_period: 1m30s

デフォルトで、コンテナーが SIGKILL を送信する前にstopは 10 秒待ちます。

stop_signal

コンテナーに対して別の停止シグナルを設定します。 デフォルトにおいてstopは SIGTERM を用います。 stop_signalを使って別のシグナルを設定するとstopにはそのシグナルが代わりに送信されます。

stop_signal: SIGUSR1

sysctls

コンテナーに設定するカーネルパラメーターを設定します。 配列または辞書形式での指定ができます。

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

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

You can only use sysctls that are namespaced in the kernel. Docker does not support changing sysctls inside a container that also modify the host system. For an overview of supported sysctls, refer to configure namespaced kernel parameters (sysctls) at runtime.

docker のスタックデプロイ時のメモ

このオプションを スウォームモードでのスタックのデプロイ において用いるには Docker Engine 19.03 以降が必要です。

tmpfs

ファイルフォーマットバージョン 3.6 における追加

コンテナー内においてテンポラリファイルシステムをマウントします。 設定は 1 つだけとするか、リストにすることができます。

tmpfs: /run

tmpfs:
  - /run
  - /tmp

docker のスタックデプロイ時のメモ

Compose ファイルバージョン 3 ～ 3.5 においてこのオプションは、スウォームモードでのスタックのデプロイ を行う場合には無視されます。

コンテナー内部にてテンポラリファイルシステムをマウントします。 size パラメーターは tmpfs マウントのサイズをバイト単位で指定します。 デフォルトは無制限です。

- type: tmpfs
  target: /app
  tmpfs:
    size: 1000

ulimits

コンテナーにおけるデフォルトの ulimits を上書きします。 1 つの limit を整数値として指定するか、ソフト、ハードの limit をマッピングとして指定することができます。

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

userns_mode

userns_mode: "host"

Docker デーモンにおいてユーザー名前空間が設定されていても、サービスに対してユーザー名前空間を無効にします。 詳しくは dockerd を参照してください。

docker のスタックデプロイ時のメモ

userns_modeオプションは、スウォームモードでのスタックのデプロイ を行う場合には無視されます。

volumes

マウントホストパスや名前つきボリュームを、サービスに対するサブオプションとして指定します。

ホストパスのマウントは、単一サービスの定義の一部として行うことができます。 これは最上位のvolumesキーにて定義する必要はありません。

ただし複数のサービスにわたってボリュームを再利用したい場合は、最上位のvolumesキー において名前つきボリュームを定義してください。 名前つきボリュームは サービス、スウォーム、スタックファイル において用いられます。

ファイルフォーマットバージョン 3 における変更

最上位の volumes キーは名前つきボリュームを定義し、各サービスのvolumesリストからこれを参照します。 これは Compose ファイルフォーマットのかつてのバージョンにおけるvolumes_fromに置き換わるものです。

以下の例では名前つきボリューム（mydata）がwebサービスにおいて利用されています。 またバインドマウントが単一のサービス（dbサービスのvolumesにある最初のパス）に対して定義されています。 dbサービスはさらにdbdataという名前つきボリュームを利用しています（dbサービスのvolumesの 2 つめのパス）が、その定義の仕方は、名前つきボリュームをマウントする古い文字列書式を使っています。 名前つきボリュームは以下に示しているように、最上位のvolumesキーのもとに列記されていなければなりません。

version: "3.9"
services:
  web:
    image: nginx:alpine
    volumes:
      - type: volume
        source: mydata
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: ./static
        target: /opt/app/static

  db:
    image: postgres:latest
    volumes:
      - "/var/run/postgres/postgres.sock:/var/run/postgres/postgres.sock"
      - "dbdata:/var/lib/postgresql/data"

volumes:
  mydata:
  dbdata:

メモ

ボリュームに関する一般的な情報については ボリュームの利用 や ボリュームプラグイン を参照してください。

短い文法

短い文法は一般に[SOURCE:]TARGET[:MODE]という書式になります。 ここでSOURCEはホストパスまたはボリューム名を指定します。 TARGETはボリュームがマウントされているコンテナーのパスです。 標準モードには読み込み専用roと読み書き可能rw（デフォルト）があります。

ホスト上の相対パスをマウントすることができます。 これは、用いられている Compose 設定ファイルのディレクトリからの相対パスとして展開されます。 相対パスは.または..で書き始める必要があります。

volumes:
  # パス指定のみ。Engine にボリュームを生成させます。
  - /var/lib/mysql

  # 絶対パスのマッピングを指定。
  - /opt/data:/var/lib/mysql

  # ホストからのパス指定。Compose ファイルからの相対パス。
  - ./cache:/tmp/cache

  # ユーザーディレクトリからの相対パス。
  - ~/configs:/etc/configs/:ro

  # 名前つきボリューム。
  - datavolume:/var/lib/mysql

長い文法

Added in version 3.2 file format.

長い文法は追加の設定項目が加えられていて、短い文法では表現できないものです。

  • type: マウントタイプを表わすvolume、bind、tmpfs、npipeのいずれかを指定します。
  • source: マウント元。バインドマウントにおいてはホスト上のパスを指定します。 また 最上位のvolumesキー で定義したボリューム名を指定します。 tmpfs マウントはできません。
  • target: ボリュームがマウントされるコンテナー内のパスを指定します。
  • read_only: ボリュームを読み込み専用に設定します。
  • bind: 追加のバインドオプションを設定します。
    • propagation: バインドにおいて伝播モード（propagation mode）を利用します。
  • volume: 追加のボリュームオプションを設定します。
    • nocopy: ボリュームの生成時にはコンテナーからのデータコピーを無効にします。
  • tmpfs: 追加の tmpfs オプションを設定します。
    • size: tmpfs マウントのサイズをバイト数で指定します。
version: "3.9"
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - type: volume
        source: mydata
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: ./static
        target: /opt/app/static

networks:
  webnet:

volumes:
  mydata:

メモ

バインドマウントを生成するにあたって長い文法を用いるのであれば、参照するパスはあらかじめ生成しておく必要があります。 短い文法であれば、そのパスが存在いていなかった場合には生成されます。 詳しくは バインドマウント を参照してください。

サービス、スウォーム、スタックファイルに対するボリューム設定

docker のスタックデプロイ時のメモ

サービス、スウォーム、docker-stack.ymlファイルを扱っている際には気をつけておくべきことがあります。 サービスのもとにあるタスク（コンテナー）はスォーム内のどのノードにでもデプロイされます。 サービスは毎回、異なるノードとなり得るということです。

ボリュームに名前をつけずに利用したとすると、Docker はサービスのもとにある各タスクに対して、名前のない匿名のボリュームを生成します。 匿名ボリュームは、関連コンテナーが削除された後は持続されません。

データを維持しておきたい場合は、名前つきボリュームを設定し、複数ホストに対応したボリュームドライバーを利用してください。 そうすればデータはどのノードからでもアクセスできます。 あるいはサービスに対する指定として、ボリュームが存在しているノードへタスクをデプロイするようにしてください。

例として Docker Labs にある投票アプリ では、docker-stack.ymlにてpostgresデータベースを起動するdbサービスが定義されています。 そして名前つきボリュームを設定して、スウォーム内のデータを失わないようにしています。 さらにそれはmanagerノードでのみ稼動するように限定しています。 以下は該当するファイル部分の抜粋です。

version: "3.9"
services:
  db:
    image: postgres:9.4
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend
    deploy:
      placement:
        constraints: [node.role == manager]

domainname, hostname, ipc, mac_address, privileged, read_only, shm_size, stdin_open, tty, user, working_dir

ここに示すオプションはいずれも、値 1 つを設定するものであり、docker run のオプションに対応づいています。 なおmac_addressは古くなったオプションです。

user: postgresql
working_dir: /code

domainname: foo.com
hostname: foo
ipc: host
mac_address: 02:42:ac:11:65:43

privileged: true


read_only: true
shm_size: 64M
stdin_open: true
tty: true

時間の指定

check のサブオプションinterval、timeoutのように、時間を設定するオプションがあります。 これは以下のような書式による文字列を時間として受け付けるものです。

2.5s
10s
1m30s
2h32m
5h34m56s

サポートされる単位はus、ms、s、m、hです。

バイト値の表現

build のサブオプションshm_sizeのようにバイト値を設定するオプションがあります。 バイト値は文字列として指定するものであり、以下のようになります。

2b
1024kb
2048k
300m
1gb

サポートされる単位はb、k、m、gとそれに応じたkb、mb、gbです。 現時点にて 10 進数値の指定はサポートされていません。

ボリューム設定リファレンス

サービスの宣言の一部として、一時的に ボリューム を宣言することが可能ですが、このセクションでは（volumes_fromを利用せずに）マルチサービスにわたって再利用可能な名前つきボリュームの生成方法を説明します。 またこのボリュームは docker コマンドラインや API を使って簡単に抽出したり確認したりすることができます。 詳しくは docker volume のサブコマンドを確認してください。

ボリュームに関する一般的な情報については ボリュームの利用 や ボリュームプラグイン を参照してください。

以下の例では 2 つのサービスを用います。 データベースのデータディレクトリは、もう一方のサービスに対してボリュームとして共有させます。 これによりデータが定期的に反映されます。

version: "3.9"

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

volumes:
  data-volume:

最上位のvolumesキーは指定しないようにすることもできます。 その場合は Engine によってデフォルトで設定されているドライバーが用いられます。 （たいていはlocalドライバーとなります。） さらに追加で、以下のようなキーを設定することができます。

driver

どのボリュームドライバーを現在のボリュームに対して用いるかを指定します。 デフォルトは Docker Engine が利用するものとして設定されているドライバーになります。 たいていはlocalです。 ドライバーが利用できない場合、docker-compose upによってボリューム生成が行われる際に Engine がエラーを返します。

driver: foobar

driver_opts

このボリュームが利用するドライバーに対して、受け渡したいオプションをキーバリューペアのリストとして設定します。 このオプションは各ドライバーによって異なります。 詳しくは各ドライバーのドキュメントを参照してください。 設定は任意です。

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

external

このオプションをtrueに設定することにより、Compose の外部において生成されているボリュームを設定します。 docker-compose upはボリュームを生成しないようになりますが、ボリュームが存在しなければエラーとなります。

バージョン 3.3 およびそれ以前にて、externalは他のボリューム設定キー（driver, driver_opts, labels）と同時に用いることはできませんでした。 この制約は バージョン 3.4 以降においてはなくなりました。

以下の例では[projectname]_dataというボリュームは生成されることはなく、Compose はすでに存在しているdataという単純な名前のボリュームを探しにいきます。 そしてこれをdbサービスコンテナー内にマウントします。

version: "3.9"

services:
  db:
    image: postgres
    volumes:
      - data:/var/lib/postgresql/data

volumes:
  data:
    external: true

ファイルフォーマットバージョン 3.4 において非推奨

ファイルフォーマットバージョン 3.4 において external.name は廃止予定となりました。 代わりにnameを用いてください。

ボリューム名として指定する名前は、Compose ファイル内で参照されている名前以外でも指定することができます。

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

docker のスタックデプロイ時のメモ

external ボリュームが存在しない場合に、docker stack deploy を実行してアプリを スウォームモード 内に導入すると、ボリュームが生成されます。 （docker compose up とは異なります。） スウォームモードにおいて、サービスとして定義されているボリュームは自動生成されます。 サービスタスクは新たなノード上においてスケジューリングされるので、swarmkit がローカルノード上にボリュームを生成します。 詳しくは moby/moby#29976 を参照してください。

labels

Docker labels を使ってコンテナーにメタデータを追加します。 配列形式と辞書形式のいずれかにより指定します。

ここでは逆 DNS 記法とすることをお勧めします。 この記法にしておけば、他のソフトウェアが用いるラベルとの競合が避けられるからです。

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"

name

ファイルフォーマットバージョン 3.4 における追加

ボリュームに対して独自の名前を設定します。 name は、特殊文字を含むボリュームを参照する際に用いることができます。 name は記述されたとおりに用いられ、スタック名によるスコープは行われません。

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

これはexternalプロパティと同時に利用することができます。

version: "3.9"
volumes:
  data:
    external: true
    name: my-app-data

ネットワーク設定リファレンス

最上位のnetworksキーは、生成するネットワークを指定します。

driver

現在のネットワークにおいて利用するドライバーを設定します。

デフォルトとなるドライバーは、Docker Engine においてどのドライバーを用いているかによって変わります。 たいていの場合、単一ホストであれば bridge、スウォーム上ではoverlayになります。

ドライバーが利用できない場合、Docker Engine はエラーを返します。

driver: overlay

bridge

単一ホストの場合、Docker はデフォルトとしてbridgeネットワークを利用します。 bridge ネットワークがどのように動作するかは、Docker Labs のチュートリアルである ブリッジネットワーク の例を参照してください。

overlay

overlayドライバーは、スウォーム 内での複数ノードにわたって、名前づけされたネットワークを生成します。

  • スウォームモードにてoverlayネットワークによるサービスを構築し利用する例として、Docker Labs のチュートリアル Overlay networking and service discovery を参照してください。

  • さらに詳しく内部動作を知るためには、networking concepts lab にある Overlay Driver Network Architecture を参照してください。

host または none

ホストのネットワークスタックを利用する場合、あるいはネットワークを利用しない場合に指定します。 docker run --net=hostあるいはdocker run --net=noneを実行することと同じです。 docker stackコマンドを用いる場合にのみ利用します。 docker-composeコマンドを用いる場合は、これではなく network_mode を利用してください。

通常のビルドではあるものの、ネットワークには特定のものを利用したい場合は、2 つめの yaml ファイル例に示しているように network を利用してください。

hostやnoneのようにビルトインネットワークを利用する場合の文法は、少々違います。 外部ネットワークを定義する場合はhostやnone（Docker ではすでに自動的に生成済）を用い、また Compose が利用可能なエイリアス（以下の例におけるhostnetやnonet）を定義してください。 そしてサービスが、そのエイリアスを使ってネットワークにアクセスできるようにしてください。

version: "3.9"
services:
  web:
    networks:
      hostnet: {}

networks:
  hostnet:
    external: true
    name: host

services:
  web:
    ...
    build:
      ...
      network: host
      context: .
      ...

services:
  web:
    ...
    networks:
      nonet: {}

networks:
  nonet:
    external: true
    name: none

driver_opts

このネットワークが利用するドライバーに対して、受け渡したいオプションをキーバリューペアのリストとして設定します。 このオプションは各ドライバーによって異なります。 詳しくは各ドライバーのドキュメントを参照してください。 設定は任意です。

driver_opts:
  foo: "bar"
  baz: 1

attachable

ファイルフォーマットバージョン 3.2 における追加

driverがoverlayに設定されている場合にのみ用います。 これがtrueに設定されている場合、スタンドアロンのコンテナーがネットワークに、そしてサービスにアタッチされます。 スタンドアロンのコンテナーが overlay ネットワークにアタッチしていると、サービス間での通信が可能になります。 さらに他の Docker デーモンにより overlay ネットワークが構成されている場合に、そこにアタッチされたスタンドアロンコンテナーとも通信が可能になります。

networks:
  mynet1:
    driver: overlay
    attachable: true

enable_ipv6

現在のネットワークにおいて IPv6 ネットワークを有効にします。

Compose ファイルバージョン 3 ではサポートされません。

enable_ipv6は Compose ファイルバージョン 2 を必要とします。 したがってこのディレクティブはまだ、スウォームモードに対してはサポートされていません。

ipam

独自の IPAM 設定を行います。 いくつかのプロパティにより表わされるオブジェクトであり、それぞれの指定は任意です。

  • driver: デフォルトではない独自の IPAM ドライバーを指定します。
  • config: 設定ブロックを指定します。要素数はゼロでも複数でも可です。 以下のキーを用いることができます。
    • subnet: ネットワークセグメントを表わす CIDR 形式のサブネットを指定します。

すべてを利用した例が以下です。

ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16

メモ

gatewayのような設定キーは、現時点ではバージョン 2 においてのみ利用できます。

internal

デフォルトにおいて Docker はブリッジネットワークに接続する際に、外部接続機能も提供します。 外部に独立した overlay ネットワークを生成したい場合、本オプションをtrueにします。

labels

Docker labels を使ってコンテナーにメタデータを追加します。 配列形式と辞書形式のいずれかにより指定します。

ここでは逆 DNS 記法とすることをお勧めします。 この記法にしておけば、他のソフトウェアが用いるラベルとの競合が避けられるからです。

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"

external

このオプションをtrueに設定することにより、Compose の外部において生成されているボリュームを設定します。 docker-compose upはボリュームを生成しないようになりますが、ボリュームが存在しなければエラーとなります。

バージョン 3.3 およびそれ以前にて、externalは他のボリューム設定キー（driver、driver_opts、ipam、internal）と同時に用いることはできませんでした。 この制約は バージョン 3.4 以降においてはなくなりました。

以下の例においてproxyは外部ネットワークとの間のゲートウェイです。 [projectname]_outsideというネットワークは生成されることはなく、Compose はすでに存在しているoutsideという単純な名前のネットワークを探しにいって、proxyサービスのコンテナーに接続します。

version: "3.9"

services:
  proxy:
    build: ./proxy
    networks:
      - outside
      - default
  app:
    build: ./app
    networks:
      - default

networks:
  outside:
    external: true

ファイルフォーマットバージョン 3.5 において非推奨

バージョン 3.5 において external.name は廃止予定となりました。 代わりにnameを用いてください。

ネットワーク名として指定する名前は、Compose ファイル内で参照されている名前以外でも指定することができます。

version: "3.9"
networks:
  outside:
    external:
      name: actual-name-of-network

name

ファイルフォーマットバージョン 3.5 における追加

ネットワークに対して独自の名前を設定します。 name は、特殊文字を含むネットワークを参照する際に用いることができます。 name は記述されたとおりに用いられ、スタック名によるスコープは行われません。

version: "3.9"
networks:
  network1:
    name: my-app-net

これはexternalプロパティと同時に利用することができます。

version: "3.9"
networks:
  network1:
    external: true
    name: my-app-net

configs 設定リファレンス

最上位のconfigsの宣言では、このスタックファイル内のサービスに対して適用する configs を定義し参照します。 config の値となるのはfileかexternalです。

  • file: config は、指定されたパスにあるファイルの内容に従って生成されます。
  • external: true に設定されている場合、config がすでに定義済であることを設定します。 Dockder はこれを生成しないようになりますが、config が存在しなければconfig not foundというエラーが発生します。
  • name: Docker における config オブジェクト名を設定します。 この設定は、特殊文字を含む config を参照する際に用いることができます。 name はそのまま用いられ、スタック名によるスコープは行われません。 これはファイルフォーマットバージョン 3.5 において導入されたものです。
  • driver and driver_opts: The name of a custom secret driver, and driver-specific options passed as key/value pairs. Introduced in version 3.8 file format, and only supported when using docker stack.
  • template_driver: The name of the templating driver to use, which controls whether and how to evaluate the secret payload as a template. If no driver is set, no templating is used. The only driver currently supported is golang, which uses a golang. Introduced in version 3.8 file format, and only supported when using docker stack. Refer to use a templated config for a examples of templated configs.

以下の例においては、スタックがデプロイされる際に（<stack_name>_my_first_configとして）my_first_configが生成されます。 またmy_second_configは Docker にすでに定義済のものです。

configs:
  my_first_config:
    file: ./config_data
  my_second_config:
    external: true

別の状況として、外部にある config を参照する際に、Docker における config 名と、サービス内にある config 名が異なる場合があります。 以下は、前の例における config を、外部に定義されているredis_configというものに変更した例です。

configs:
  my_first_config:
    file: ./config_data
  my_second_config:
    external:
      name: redis_config

スタック内の各サービスに対しては、config へのアクセス許可 を行う必要があります。

secrets 設定リファレンス

最上位のsecretsの宣言では、このスタックファイル内のサービスに対して適用する secrets を定義し参照します。 secret の値となるのはfileかexternalです。

  • file: secret は、指定されたパスにあるファイルの内容に従って生成されます。
  • external: true に設定されている場合、secret がすでに定義済であることを設定します。 Dockder はこれを生成しないようになりますが、secret が存在しなければsecret not foundというエラーが発生します。
  • name: Docker における secret オブジェクト名を設定します。 この設定は、特殊文字を含む secret を参照する際に用いることができます。 name はそのまま用いられ、スタック名によるスコープは行われません。 これはファイルフォーマットバージョン 3.5 において導入されたものです。
  • template_driver: The name of the templating driver to use, which controls whether and how to evaluate the secret payload as a template. If no driver is set, no templating is used. The only driver currently supported is golang, which uses a golang. Introduced in version 3.8 file format, and only supported when using docker stack.

以下の例においては、スタックがデプロイされる際に（<stack_name>_my_first_secretとして）my_first_secretが生成されます。 またmy_second_secretは Docker にすでに定義済のものです。

secrets:
  my_first_secret:
    file: ./secret_data
  my_second_secret:
    external: true

別の状況として、外部にある secret を参照する際に、Docker における secret 名と、サービス内にある secret 名が異なる場合があります。 以下は、前の例における secret を、外部に定義されているredis_secretというものに変更した例です。

Compose ファイル v3.5 またはそれ以降の場合

secrets:
  my_first_secret:
    file: ./secret_data
  my_second_secret:
    external: true
    name: redis_secret

Compose File v3.4 and under

  my_second_secret:
    external:
      name: redis_secret

スタック内の各サービスに対しては、secret へのアクセス許可 を行う必要があります。

変数の置換

設定オプションには環境変数を含めることができます。 Compose は docker-compose が実行されたシェル環境から変数値を取得します。 たとえばシェル環境に POSTGRES_VERSION=9.3 が定義されているとして、以下のような設定を行ったとします。

db:
  image: "postgres:${POSTGRES_VERSION}"

上の設定を使って docker-compose up を実行すると、Compose はシェル環境内の環境変数 POSTGRES_VERSION を見にいき、その値を使って設定を置換します。 この例では image が postgres:9.3 と置換された上で、設定に関する処理へ進みます。

その環境変数が何も設定されていなかった場合、Compose は空文字に置換します。 上の例でいうと POSTGRES_VERSION が設定されていなかったとき、image オプションの値は postgres: になります。

環境変数のデフォルト値を .env ファイル に設定しておくことができます。 Compose はプロジェクトディレクトリ（Compose ファイルの親ディレクトリ）内のこのファイルを自動的に探しにいきます。 .env ファイルで定義されたものよりも、シェル環境で設定された値が優先されます。

.env ファイルによる機能は docker-compose up コマンドを使うときだけ動作します。 docker stack deploy コマンドでは動作しません。

$VARIABLE と ${VARIABLE} という 2 つの文法がともにサポートされます。 さらに 2.1 ファイルフォーマット を利用している場合は、シェル上でも利用されているインラインのデフォルト指定方法を行うことができます。

  • ${VARIABLE:-default} は VARIABLE がセットされていないか空文字であるときに default として評価されます。
  • ${VARIABLE-default} は VARIABLE がセットされていないときのみ default として評価されます。

同様に以下の文法により、変数を必須とする扱いができます。

  • ${VARIABLE:?err} は VARIABLE がセットされていないか空文字であるときに、err を含むエラーメッセージを表示して終了します。
  • ${VARIABLE?err} は VARIABLE がセットされていないときに、err を含むエラーメッセージを表示して終了します。

シェル風のこの他の機能、たとえば ${VARIABLE/foo/bar} などはサポートされていません。

設定ファイル内にドル記号そのものが必要な場合は $$（ドル記号 2 つ）を書きます。 この記述は Compose が値を取り違えないようにします。 つまり $$ と書くことで、環境変数を参照しつつ Compose には処理させないようにすることができます。

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

このことを忘れてドル記号 1 つ（$）を用いてしまうと、Compose は環境変数として値を解釈し、以下の警告を出します。

The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.
(VAR_NOT_INTERPOLATED_BY_COMPOSE は設定されていません。空文字として置換します。)

拡張項目

ファイルフォーマットバージョン 3.4 における追加

拡張項目（extension fields）を利用することで、設定内容の再利用が可能になります。 この特別な項目は Compose ファイルの最上位項目として位置していれば、どのような書式であっても構いません。 このとき項目名の先頭は x- で書き始めます。

メモ

（3.x シリーズにおいては）バージョン 3.7 から、また（2.x シリーズにおいては）バージョン 2.4 から、この拡張項目は、service、volume、network、config、secret それぞれの最上位に記述できることになりました。

version: "3.9"
x-custom:
  items:
    - a
    - b
  options:
    max-size: '12m'
  name: "custom"

この項目に記述された内容は Compose からは無視されます。 そして YAML アンカー を利用して、この項目をリソース定義内に挿入します。 たとえば複数のサービスに対して、同様のロギング設定を行いたいとします。

logging:
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

その場合、以下のようにして Compose ファイルを書くことができます。

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

services:
  web:
    image: myapp/web:latest
    logging: *default-logging
  db:
    image: mysql:latest
    logging: *default-logging

また YAML マージタイプ を利用すれば、拡張項目内にて部分的に値を上書きすることもできます。 たとえば以下のとおりです。

version: "3.9"
x-volumes:
  &default-volume
  driver: foobar-storage

services:
  web:
    image: myapp/web:latest
    volumes: ["vol1", "vol2", "vol3"]
volumes:
  vol1: *default-volume
  vol2:
    << : *default-volume
    name: volume02
  vol3:
    << : *default-volume
    driver: default
    name: volume-local

Compose ドキュメント

fig, composition, compose version 3, docker