Compose ファイル version 3 リファレンス

目次

リファレンスと方針

以下のトピックでは、 Compose ファイル形式バージョン3について説明します。

Compose と Docker の互換表

Compose ファイル形式には、1 、 2 、 2.x 、 3.x のように複数のバージョンがあります。下にある表をちらっと見てみましょう。各バージョンの詳細についてや、アップグレードの仕方については、 Compose ファイルのバージョンとアップグレード をご覧ください。

この表は、各 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 ファイル構造と例

こちらはサンプルの Compose ファイルです。 Docker for Beginners lab の Deploying an app to a Swarm トピックで使われている投票アプリのサンプルです。

このリファレンスページ上のトピックは、Compose ファイル自身の構造をトップレベルのキーとして反映し、アルファベット順に並べています。トップレベルのキーとは、 build 、 deploy 、 depends_on 、 networks 等の設定があるセクション定義です。

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

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

Tip

このファイルは .yml か .yaml いずれか一方の拡張子を利用できます。どちらも機能します。

サービスの定義に入るのは、コマンドラインで docker run にパラメータを渡すのと同じように、サービスとして起動するコンテナに対して適用する設定です。同様に、ネットワークやボリュームの定義も docker network create や docker volume create と似ています。

docker run と同様に、 Dockerfile で指定した CMD 、 EXPOSE 、 VOLUME 、ENV のようなオプションが、デフォルト（の設定値）として尊重されます。そのため、 docker-compose.yml で再び指定する必要はありません。

Bash のような ${変数名} の構文を使い、環境変数を設定値として使用できます。詳しくは 変数の置き換え をご覧ください。

このセクションで扱うのは、（Docker Compose）バージョン3のサービス定義用にサポートされている、設定オプションの一覧です。

build

構築時(build time) に適用するオプションを指定します。

build では 構築コンテキスト(build context) へのパスを含む文字列を指定できます。

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

または、 context 配下のパスにある特定の（ファイルやディレクトリなどの）物（オブジェクト）と、 Dockerfile のオプションと 引数 を指定できます。

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

build と同様に image （Docker イメージ）も指定する場合、 image の場所で指定された webapp とオプションの tag を使い、 Docker Compose が構築されるイメージに名前を付けます。

build: ./dir
image: webapp:tag

つまり、 ./ 以下から 構築(build) した結果、 webapp という名前と tag というタグ名を持つイメージができます。

注意

docker stack deploy 使用時の注意 build オプションは swarm mode でスタックのデプロイ 時に無視されます。 docker stack コマンドは、デプロイ前にイメージを構築しません。

context

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

相対パスとして値を指定すると、 Compose ファイルがある場所を基準とした相対パスとして解釈されます。また、そのディレクトリが構築コンテキストとなり、その内容が Docker デーモンに対して送られます。

Compose は作成時の名前を使ってイメージ構築やタグ付けをし、以降は、そのイメージを使います。

build:
  context: ./dir

dockerfile

別の Dockerfile を指定します。

Compose は別の Dockerfile ファイルを使い構築します。 構築パス(build path) の指定も必要です（訳者注：構築コンテキスト、つまり、使いたい Dockerfile のある場所を指定）。

build:
  context: .
  dockerfile: Dockerfile-alternate

args

build の 引数(arg) （構築時のオプション）を指定します。ここで指定した引数は、構築の処理中のみ環境変数として利用できます。

まずはじめに、 Dockerfile 内で引数を指定しておきます。

# syntax=docker/dockerfile:1

ARG buildno
ARG gitcommithash

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

そして、 build キーの下で引数を指定します。 マッピング(mapping) またはリストで引数を渡します。

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

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

注釈

buildにおけるargの範囲

Dockerfile で、 FROM 命令の前に ARG 命令を指定すると、 FROM 命令以下の構築処理で ARG を利用できなくなります。もし両方で使いたい場合には、 FROM 命令の下でも指定する必要があります。使い方の詳細についてのドキュメントは ARG と FROM の相互作用を理解 を参照ください。

biuld 引数に対して値を指定しない場合は、Compose を実行時、環境変数の値が構築時の値として使用されます。

args:
  - buildno
  - gitcommithash

Tip

ブール値を使う場合

YAML の ブール値(boolean values) （ "true" , "false" , "yes" , "no" , "on" , "off" ）は、引用符で囲む必要があり、そうするとパーサは文字列としてそれらを解釈します。

cache_from

ヒント

Compose 形式 バージョン 3.2 で追加されました。

Engine がキャッシュの解決に使うイメージの一覧。

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

labels

ヒント

Compose 形式 バージョン 3.3 で追加されました。

Docker ラベル を使い、結果として作成されるイメージにメタデータを追加します。 配列(array) または 連想配列(dictionary) が使えます。

指定するラベルが他のソフトウェアで使われているものと重複を避けるには、 逆引き DNS 記法(reverse-DNS notation) の利用を推奨します。

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

ヒント

Compose 形式 バージョン 3.4 で追加されました。

RUN 命令で構築中に、コンテナが接続するネットワークを指定します。

build:
  context: .
  network: host

build:
  context: .
  network: custom_network_1

none の指定は、構築中にネットワーク機能を無効化します。

build:
  context: .
  network: none

shm_size

ヒント

Compose 形式 バージョン 3.5 で追加されました。

構築用コンテナの /dev/shm パーティションの容量を指定します。（容量の）バイト数を整数の値として表すか、 バイト値 の文字列で表します。

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

target

ヒント

Compose 形式 バージョン 3.4 で追加されました。

Dockerfile の中で定義された ステージ(stage) を指定して構築します。詳細は マルチステージ・ビルド をご覧ください。

build:
  context: .
  target: prod

cap_add, cap_drop

コンテナの ケーパビリティ(capabilities) を追加・削除します。ケーパビリティの一覧は man 7 capabilities をご覧ください。

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

注意

docker stack deploy 使用時の注意 cap_add と cap_drop オプションは swarm mode でスタックのデプロイ 時に無視されます。 docker stack コマンドは、デプロイ前にイメージを構築しません。

cgroup_parent

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

cgroup_parent: m-executor-abcd

注意

docker stack deploy 使用時の注意 cgroup_parent オプションは swarm mode でスタックのデプロイ 時に無視されます。 docker stack コマンドは、デプロイ前にイメージを構築しません。

command

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

command: bundle exec thin -p 3000

コマンドは、 Dockerfile と同じようにリスト形式にもできます。

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

configs

サービスごとに使う configs 設定に基いて、アクセス権限を設定します。2つの構文がサポートされています。

注釈

config は既に存在しているか、 トップレベルの configs 設定に関する定義 がこのスタックファイルに存在している必要があります。そうでなければ、スタックのデプロイに失敗します。

configs に関する詳しい情報は configs をご覧ください。

短い構文

短い構文(short syntax) の形式は、config 名でのみ指定できます。これは、コンテナがコンテナ内で設定にアクセスしたり、 /<設定名> でマウントする権限を与えます。ソース名とマウントポイント先の、どちらも config 名で設定されます。

以下の例は短い構文を使い、 redis サービスに my_config と my_other_config 設定に対するアクセスを許可します。 my_config の値は、ファイル ./my_config.txt と my_other_configs の中で定義されているものに、外部リソースとして設定されます。これはつまり、既に Docker 内で定義されているのを意味しますので、 docker config create コマンドを実行しているか、あるいは、他のスタックによってデプロイされている必要があります。もしも外部設定が存在しなければ、 config not found のエラーをと共に、スタックのデプロイに失敗します。

ヒント

Compose 形式 バージョン 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

長い構文

長い構文(long syntax) の形式は、サービスタスク用のコンテナ内で作成される設定を、より細かく指定します。

  • source ：この設定自身、そのものを識別するための設定です。

  • target ：サービスタスクのコンテナ内でマウントする、ファイル名とパスです。指定が無ければ、 /<source> がデフォルトです。

  • uid と gid ：サービスタスクのコンテナ内で設定ファイルをマウントする所有者を、整数の UID または GID で指定します。指定が無ければ、 Linux 上では 0 がデフォルトです。Windows 上ではサポートされません。

  • mode ：サービスタスク内のコンテナで、マウントするファイルのパーミッションを8進数で書きます。たとえば、 0444 は誰もが読み込めるのを意味します。デフォルトは 0444 です。設定は一時的なファイルシステムにマウントされるため、書き込み可能にできません。そのため、書き込み可能なビットを指定しても、無視されます。実行権限は設定できません。UNIX のファイルパーミッション・モードに慣れていなければ、 パーミッション計算（英語） が役立つでしょう。

以下の例は、 my_config の名前をコンテナ内で redis_config と設定し、モードを 0440 （グループが読み込みできる）に設定し、ユーザとグループを 103 へと設定します。

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

サービスに対して複数の設定を与えられます。また、長い構文と短い構文を混ぜて使えます。config の定義は、サービスがアクセスできる権限の付与を意味しません。

container_name

自動作成されるコンテナ名ではなく、任意のコンテナ名を指定します。

container_name: my-web-container

Docker コンテナ名は重複できません。そのため、任意のコンテナ名を指定した場合、サービスは複数のコンテナにスケールできなくなります。

注意

docker stack deploy 使用時の注意

swarm モードのスタックにデプロイ する場合、 container_name オプションは無視されます。

credential_spec

ヒント

Compose 形式 バージョン 3.3 で追加されました。

credential_spec オプションは v3.3 で追加されました。グループ管理サービスアカウント（gMSA）設定を compose ファイルで使うのがサポートされているのは、バージョン 3.8 以上の形式です。

マネージド・サービス・アカウントに対して credentail spec を指定します。このオプションは Windows コンテナで使うサービスでのみ使えます。 credentail_spec の形式は file://<ファイル名> または registry://<値の名前> の必要があります。

file: を使う場合、参照されるファイルは Docker データディレクトリ内の CredentialSpecs に存在する必要があります。Windows 上でのデフォルトは C:\ProgramData\Docker\ です。以下の例は、ファイル名 C:\ProgramData\Docker\CredentialSpecs\my-credential-spec.json から credential spec を読み込みます。

credential_spec:
  file: my-credential-spec.json

registry: を使う場合は、credential spec をデーモンのホスト上にある Windows レジストリから読み込みます。レジストリの値には、存在している場所も名前に入れる必要があります。

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

以下の例はレジストリ内の my-credentials-spec の名前が付いている値から credential spec を読み込みます。

credential_spec:
  registry: my-credential-spec

gMSA 設定例

gMSA credential spec をサービスに対して設定する時は、以下の例にあるように、 config で credential spec の指定が必要です。

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

サービス間の 依存関係(dependency) を示します。サービス依存関係によって、次の働きをします。

  • docker-compose up は、依存関係の順番でサービスを開始します。以下の例では、 web の前に db と redis を開始します。

  • dokcer-compose up サービス は、 サービス の依存関係を自動的に読み込みます。以下の例では、 docker-compose up web でも db と redis を作成と起動します。

  • docker-compose stop は、依存関係の順番でサービスを停止します。以下の例では、 db と redis の前に web を停止します。

シンプルな例：

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

注釈

depends_on 使用時に注意すべき点 :

  • depends_on では、 web を開始する前に db と redis の「準備」が整うのを待ちません。単に、順番通り開始するだけです。サービスの準備が調うまで待つ必要がある場合、この問題を解決する方法は 開始順番の制御 をご覧ください。

  • depends_on オプションは、Compose ファイル形式バージョン3の swarm mode でスタックのデプロイ 時に無視されます。

deploy

ヒント

Compose 形式 バージョン 3 で追加されました。

サービスのデプロイと実行に関連する設定をします。効果があるのは swarm を使って docker stack deploy でデプロイした時のみです。 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

ヒント

Compose 形式 バージョン 3.2 で追加されました。

外部のクライアントが swarm に接続するため、サービス・ディスカバリ手法を指定します。

  • endpoint_mode: vip - Docker はサービスに仮想 IP (VIP) を割り当てます。これは、クライアントがネットワーク上のサービスに到達するための、フロントエンドとして動作します。クライアントとサービス上で利用可能な worker ノード間とのリクエストを、Docker が経路付けします。この時、クライアントはサービス上で何台のクライアントが動作しているかや、それぞれの IP アドレスやポートを知る必要がありません。（これがデフォルトの挙動です）

  • endpoint_mode: dnsrr - DNS ラウンドロビン（DNSRR）サービスディスカバリは、仮想 IP を1つだけでは使いません。Docker はサービスに対する DNS エントリをセットアップします。これは、DNS の問い合わせがあれば、サービス名に対して IP アドレスの一覧を返します。そして、クライアントは IP アドレスのどれか1つに直接接続します。自分自身でロードバランサを使いたい場合や、Windows と Linux アプリケーションを混在したい場合に、DNS ラウンドロビンが役立ちます。

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 のオプションは、swarm モード CLI コマンド docker service create 上のフラグでも動作します。swarm に関連する docker コマンドをざっと眺めるには、 Swarm モード CLI コマンド をご覧ください。

サービスディスカバリと swarm モードでのネットワーク機能について学ぶには、swarm モードのトピックにある サービスディスカバリの設定 をご覧ください。

labels

対象サービスにラベルを指定します。ラベルはサービスに対して「のみ」指定できます。サービスのコンテナに対しては指定「できません」。

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

コンテナに対してラベルを指定するには、 deploy の外で label キーを使います。

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

mode

global （swarm ノードごとに、1つのコンテナを確実に起動）か replicated （コンテナの数を指定）のどちらかです。デフォルトは replicated です。（詳しく学ぶには swarm ）トピックの 複製とグローバル・サービス をご覧ください。）

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

placement

constraints と preferences の 配置(placement) を指定します。詳細な説明や利用可能な構文については、docker service create ドキュメントの constraints 、 preferences 、 ノードごとの最大複製数を指定 をご覧ください。

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

ヒント

Compose 形式 バージョン 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-file バージョン 3 で変更されました

Compose ファイルのバージョン3から、 古いリソース制限オプション （ cpu_shares 、 cpu_quota 、 cpuset 、 mem_limit 、 memswap_limit 、 mem_swappiness ）は、 resources セクションに変わりました。compose ファイル形式のバージョン2と3の違いについて学ぶには、 バージョン 2.x から 3.x へのアップグレード をご覧ください。

それぞれの値は1つであり、 docker service create での指定に相当します。

以下にある一般的な例では、 redis サービスは、メモリの 50M を越えて利用できず、利用可能な 処理時間(processing time) （CPU）の 0.50 （1コアの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

以下のトピックでは、swarm 内のサービスまたはコンテナに対し、リソースを制限するために指定可能なオプションを説明します。

注意

swarm モードではないコンテナのリソース制限のオプションを探していますか？

ここで説明しているオプションは、 deploy キーと swarm モードでの指定です。もしも swarm 以外のデプロイ対象に対してリソース制限を設定したいのであれば、 Compose ファイル形式バージョン2の CPU、メモリ、その他リソースに関するオプション を使います。

Out of Memory 例外（OOME）

サービスかコンテナが、システムで利用可能なメモリを越えて使おうとすると、Out Of Memory 例外（OOME）が発生し、コンテナか Docker デーモンはカーネル OOM キラーによって強制停止されるでしょう。このような状態が発生しないようにするには、ホスト上で実行するアプリケーションに適切なメモリを割り当て、 メモリ不足時のリスクへの理解 をご覧ください。

restart_policy

もしもコンテナが 終了(exit) すると、どのように再起動するかを設定します。 restart を置き換えたものです。

  • condition ： none 、 on-failure 、 any のどちらかです（デフォルト： any ）。

  • delay ：再起動を試みるまでどれだけ待機するか、 duration （継続時間）として指定します（デフォルト： 5s）。

  • max_attempts ：処理を中止するまで、コンテナの再起動を何回繰り返すか指定します（デフォルト：中止しません）。指定した window 以内に再起動が成功しなければ、設定した max_attempts （最大試行数）の値としてカウントしません。例えば、 max_attempts の指定が 2 で、再起動を試みて1回目が失敗している場合でも、2回以上の再起動を行う場合があります。

  • window ：何秒待機して再起動が成功したと判断するのかを、 duration （継続時間）として指定します（デフォルト： 直ちに判断）。

version: "3.9"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

rollback_config

ヒント

Compose 形式 バージョン 3.7 で追加されました。

更新に失敗した場合、サービスをどのようにして 戻す(rollback) かを設定します。

  • 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 （まず新しいタスクを開始するため、瞬間的に実行中のタスクが重複します）のどちらかです（デフォルト： start-first ）。

update_config

サービスをどのように更新するかを設定します。ローリングアップデートの設定に役立ちます。

  • parallelism ：同時に更新するコンテナの数です。

  • delay ：各コンテナのグループを更新するまで待機する時間です。

  • failure_action ：更新に失敗したらどうするかです。 continue か rollback か pause のどちらかです（デフォルト： pause ）。

  • monitor ：各タスクの更新が失敗したと判断するまでの期間（ ns | us | ms | s | m | h | ）です（デフォルト： 5s）。 メモ ： 0 を指定すると、デフォルトの 5s になります。

  • max_failure_ratio ：更新するまで許容する失敗回数です（デフォルト： 0）。

  • order ：更新処理の順番です。 stop-first （新しいタスクを開始する前に、古いタスクを停止）か、 start-first （まず新しいタスクを開始するため、瞬間的に実行中のタスクが重複します）のどちらかです（デフォルト： start-first ）。 メモ ：v3.4 以上でのみサポート

ヒント

Compose 形式 バージョン 3.4 で追加されました。 order オプションは v3.4 以上の Compose ファイル形式でのみサポートされています。

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 キーで サポートされません 。

Tip

サービス、swarm、docker-stack.yml ファイルでのボリューム設定の仕方 セクションをご覧ください。ボリューム（volumes）はサポートされていますが、swarm とサービスで使うには、名前付きボリュームとして設定するか、サービスを関連付けをし、ボリュームを必要とするノードでアクセスできるように制限する必要があります。

devices

デバイス・マッピング（割り当て）(device mapping) の一覧です。docker クライアントで作成するオプションの --device と同じ形式を使います。

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

注意

docker stack deploy 使用時の注意

swarm モードのスタックにデプロイ する場合、 devices オプションは無視されます。

dns

任意の DNS サーバに設定を変更します。単一の値、もしくはリストになります。

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

entrypoint

デフォルトの entrypoint を上書きします。

entrypoint: /code/entrypoint.sh

entrypoint は Dockerfile と同様にリストにもできます。

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

注釈

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

env_file

ファイル上の定義から環境変数を追加します。単一の値、もしくはリストになります。

Compose ファイルを docker-compose -f ファイル名 で指定する場合は、 env_file ファイルは指定したディレクトリに対する相対パスにあるとみなします。

environment でセクションで宣言された環境変数は、これらの値で上書きされます。つまり、値が保持されるのは、それぞれの値が空白もしくは未定義の場合です。

env_file: .env

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

Compose は各行が VAR=VAL （変数=値）の形式と想定します。 # で始まる行はコメントとして無視します。また、空白行も無視します。

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

注釈

サービスに biuld オプションを指定している場合、環境変数用ファイルで定義された変数は、構築中に自動で見えるようになりません。構築時の環境変数として定義するには、 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

環境変数を追加します。配列もしくは 辞書形式(dictionary) で指定できます。boolean 値 (true、false、yes、no のいずれか) は、YML パーサによって True か False に変換されないよう、クォート（ ' 記号）で囲む必要があります。

キーだけの環境変数は、Compose の実行時にマシン上で指定するものであり、 :ruby:`シークレット <secret>`（訳注：API鍵などの秘密情報）やホスト固有の値を指定するのに便利です。

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

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

注釈

サービスに biuld オプションを指定している場合、環境変数用ファイルで定義された変数は、構築中に自動で見えるようになりません。構築時の環境変数として定義するには、 build の args サブオプションを使います。

expose

コンテナの 公開（露出）(expose) 用のポート番号を指定しますが、ホストマシン上で公開するポートを指定しません。つまり、つながったサービス間でのみアクセス可能になります。内部で使うポートのみ指定できます。

expose:
 - "3000"
 - "8000"

extra_hosts

ホスト名を割り当てます（マッピングします）。これは docker クライアントで --add-host パラメータを使うのと同じ値です。

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

コンテナ内の /etc/hosts に、 IP アドレスとホスト名のエントリが追加されます。例：

162.242.195.82  somehost
50.31.209.229   otherhost

healthcheck

このサービスのコンテナが「 正常(healthy) 」かどうかを判断するために実行する、確認用コマンドを設定します。ヘルスチェックがどのように動作するかの詳細は、 HEALTHCHECK Dockerfile 命令 のドキュメントをご覧ください。

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

interval 、 timeout 、 start_period は 継続時間 として指定します。

ヒント

start_period オプションは、Compose 形式 バージョン 3.4 で追加されました。

test は文字列またはリスト形式のどちらかの必要があります。リスト形式の場合、１番目のアイテムは NONE か CMD か CMD-SHELL のどちらかの必要があります。文字列の場合は、 CMD-SHELL に続けて文字列をを指定するのと同じです。

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

前述したのは /bin/sh でラッピングされています。以下の２つは同じです。

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

イメージが存在していなければ、Compose は pull （取得）を試みます。しかし build を指定している場合は除きます。その場合、指定されたオプションやタグを使って構築します。

init

ヒント

Compose 形式 バージョン 3.7 で追加されました。

コンテナ内で init を実行し、シグナルの転送と、プロセス 再配置(reap) します。サービスに対してこの機能を有効化するには、このオプションで true を指定します。

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

注釈

デフォルトの init バイナリは、 Tiny が使われ、デーモンのホスト上の /usr/libexec/docker-init にインストールされます。 任意の init バイナリ使うには、デーモンに対して init-path 設定オプション を通して指定できます。

isolation

コンテナの 隔離(isolation) 技術を指定します。 Linux 上では、唯一サポートしている値が default です。Windows specify-isolation-technology-for-container-isolation用では、 default 、 process 、 hyperv が指定できます。詳細は、 Docker Engine ドキュメント をご覧ください。

labels

Docker ラベル を使い、コンテナに メタデータ(metadata) を追加します。配列または辞書形式で追加できます。

他のソフトウェアが使うラベルと競合しないようにするため、 逆引き DNS 記法(reverse-DNS notation) の利用を推奨します。

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"

logging

サービスに対して ログ記録(logging) の設定をします。

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

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

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

driver: "json-file"

driver: "syslog"

driver: "none"

注釈

docker-compose up で立ち上げてから docker-compose logs コマンドを使い、ログを表示できるのは json-file と journald ドライバを指定した時のみです。他のドライバを指定しても、ログは何ら表示されません。

ロギング・ドライバのオプションを指定するには options キーを使います。これは docker run コマンド実行時の --log-opt オプションと同じです。

ロギングのオプションはキーバリューのペアです。以下は syslog オプションを指定する例です。

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

デフォルトのドライバは json-file であり、これはログの保存量を制限できます。そのためには、キーバリューのペアで最大容量と最大ファイル数を指定します。

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

上の例では、保存するログファイルは max-size の 200kB に到達するまでで、その後それらがローテートされます。個々のログファイルを保存する数は max-file 値で指定します。ログが上限に到達すると、古いログファイルは削除され、新しいログを保存できるようになります。

これは、ログ記録ストレージの制限をする docker-compose.yaml 例です。

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:[サービス名] という特別な形式を加えます。

network_mode: "bridge"

network_mode: "host"

network_mode: "none"

network_mode: "service:[サービス名]"

network_mode: "container:[コンテナ名/id]"

注意

docker stack deploy 使用時の注意

networks

ネットワークに追加するには、トップレベルの networks キー の項目をご覧ください。

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

aliases

エイリアス(aliases) （別のホスト名）とは、ネットワーク上のサービスに対してです。同一ネットワーク上の他のコンテナが、サービス名か、このエイリアスを使い、サービス用コンテナの１つに接続します。

aliases が適用されるのは 同一ネットワークの範囲内(network-scoped) のみです。そのため、同じサービスでも、ネットワークごとに異なったエイリアスが使えます。

注釈

複数のコンテナだけでなく複数のサービスに対しても、ネットワーク範囲内でエイリアスが利用できます。ただしその場合、どのコンテナに対して名前解決されるのかの保証はありません。

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

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

以下の例では、３つのサービス（ web 、 worker 、 db ）に、２つのネットワーク（ new と legacy ）が提供されています。 db サービスはホスト名 db または database として new ネットワーク上で到達可能です。そして、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

サービスがネットワークへ追加時、コンテナに対して 固定(static) IP アドレスを割り当てます。

トップレベルのネットワーク・セクション では、適切なネットワーク設定に ipam ブロックが必要です。ここで、それぞれの固定アドレスが扱うサブネットやゲートウェイを定義します。

IPv6 を使いたい場合は、最初に Docker デーモンが IPv6 をサポートするように設定する必要があります。詳細な手順は IPv6 の有効化 をご覧ください。まず、バージョン 3.x Compose ファイルで IPv6 での接続ができるようにするため、 /etc/docker/daemon.json に {"ipv6": true, "fixed-cidr-v6": "2001:db8:1::/64"} を追加します。

その後、docker デーモンを再起動し、 docker-compose.yml のサービス以下に、次の記述を追加します。

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

注釈

enable_ipv6 オプションは バージョン 2.x Compose ファイル でのみ利用できます。 IPv6 オプションは現在の swarm モードでは動作しません。

例：

version: "3.9"

services:
  app:
    image: busybox
    command: ifconfig
    networks:
      app_net:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  app_net:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 172.16.238.0/24
          gateway: 172.16.238.1
        - subnet: 2001:3984:3989::/64
          gateway: 2001:3984:3989::1

pid

pid: "host"

PID モードをホスト PID モードに設定します。これは、コンテナとホスト OS 間で、 PID アドレス空間の共有をできるようにします。このフラグを有効化したコンテナを起動すると、ベアメタルマシンでの名前空間等で、他のコンテナにアクセスや操作ができます。

ports

公開用のポートです。

注釈

network_mode: host と互換性のあるポート割り当てです。

短い構文

3つのオプションがあります。

  • 両方のポートを指定（ ホスト:コンテナ ）

  • コンテナのポートだけ指定（ホスト側のポートは、一時的なホスト側ポートが選択）

  • ホスト IP とポート番号の両方を指定（デフォルトは 0.0.0.0 で、全てのインターフェースを意味します）：（ IPアドレス:ホスト側ポート:コンテナ側ポート ）。もしもホスト側ポートの指定が無ければ（例 127.0.0.1:80 ）、ホスト上では一時的なポートのバインドが選択されます。

注釈

ホスト側:コンテナ側 の形式でポートを割り当てる時、コンテナのポートが 60 以下であればエラーが発生します。これは YAML が xx:yy 形式の指定を、60 進数（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 であれば負荷分散する swarm モードのポートです。

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

ヒント

Compose 形式 バージョン 3.2 で追加されました。

profiles



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

profiles は有効なサービスに対する名前付きプロフィール一覧を定義します。設定が無ければ、対象のサービスは「常に」有効です。このサービスは、中心となるアプリケーションに対しては profiles を省略して常に起動すべきでしょう。

プロフィール名では正規表現の書式 [a-zA-Z0-9][a-zA-Z0-9_.-]+ が使えます。

profiles について詳しく学ぶには、 Compose で profiles の使用 をご覧ください。

restart

no がデフォルトの 再起動ポリシー であり、どのような状況でもコンテナを再起動しません。 always を指定すると、コンテナは常に再起動します。 on-failure ポリシーは、エラーが発生時し、終了コードがあれば再起動します。 unless-stopped は常にコンテナの再起動を行いますが、コンテナの停止時（手動やその他）は除きます。

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

注意

docker stack deploy 使用時の注意

swarm モードのスタックにデプロイ する場合、 restart オプションは無視されます。

secrets

サービスごとの secrets 設定に基いて、機微情報（シークレット）へのアクセスを許可します。2つの構文がサポートされます。

注意

docker stack deploy 使用時の注意

secret は既に存在しているか、compose ファイルで トップレベルの secrets 定義 がなければ、デプロイに失敗します。

secrets に関する詳しい情報は、 /engine/swarm/secrets をご覧ください。

短い構文

短い構文の書き方は、シークレット名のみ指定します。これによって、対象のコンテナはシークレットにアクセスできるようになり、コンテナ内で /run/secrets/<シークレット名> でマウントします。ソース名とマウントポイントのどちらもシークレット名が指定されます。

以下の例では短い構文を使い、 redis サービスに my_secret と my_other_secret シークレットに対するアクセスを許可します。 my_secret の値には ./my_secret.txt ファイルを指定します。また、 my_other_secret には外部リソースを定義しています。つまりこれは既に Docker で定義済みか、 docker secret create コマンのを実行したか、あるいは他のスタックでデプロイ済みです。もし外部シークレットがなければ、 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

長い構文

長い構文によって、サービスタスク内のコンテナでどのようにシークレットを作成するか、より詳しく設定します。

  • source ：この設定を定義するためのシークレットを指定します。

  • target ：サービスタスク内のコンテナで、 /run/secrets/ にマウントするファイル名を指定します。指定がなければ、デフォルトは source です。

  • uid と gid ：サービスタスク内のコンテナで、 /run/secrets/ にあるファイルを所有する UID と GID を整数で指定します。

  • mode ：サービスタスク内のコンテナで、 /run/secrets/ にマウントするファイルのパーミッションを8進数で指定します。たとえば 0444 は誰でも読める状態を表します。 Docker 1.13.1 のデフォルトは 0000 ですが、以降のバージョンでは 0444 です。シークレットは一時的なファイルシステムへマウントするため、書き込みができません。そのため、書き込み用のビットを指定しても無視されます。実行ビットも設定できません。UNIX ファイルのパーミッションに慣れていなければ、 permissions calculator が役立ちます。

以下の例は、 my_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

サービスがアクセスできるシークレットは複数指定できますし、短い構文と長い構文の両方を混ぜて使えます。シークレットの定義は、サービスがシークレットに対してアクセスできるのを意味しません。

security_opt

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

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

注意

docker stack deploy 使用時の注意

swarm モードのスタックにデプロイ する場合、 security_opt オプションは無視されます。

stop_grace_period

コンテナを停止するために SIGTERM （あるいは、 stop_signal で指定した何らかの停止シグナル）を処理出来ない場合、 SIGKILL を送信するまで、どれだけ待機するか指定します。 期間 として指定します。

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 が使えるのはカーネルの名前空間内のみです。Docker はコンテナ内の sysctls 変更をサポートしていませんし、ホストシステム上の変更もできません。サポートしている sysctls の概要は、 :red:`実行時に名前空間内でのカーネルパラメータ（sysctls）を設定 configure-namespaced-kernel-parameters-sysctls-at-runtime` をご覧ください。

注釈

docker stack deploy 使用時の注意

このオプションは Docker Engine 19.03 以上か、swarm モードのスタックにデプロイ する時に利用できます。

tmpfs

ヒント

Compose 形式 バージョン 3.6 で追加されました。

コンテナ内にテンポラリ・ファイルシステムをマウントします。単一の値もしくはリストです。

tmpfs: /run

tmpfs:
  - /run
  - /tmp

注意

docker stack deploy 使用時の注意

Compose ファイル（バージョン 3～3.5 ）で swarm モードのスタックにデプロイ をする場合、 このオプションは無視されます。

コンテナ内の一時的なファイルシステムをマウントします。tmpfs マウントの容量は size パラメータにバイト単位で指定します。デフォルトは無制限です。

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

ulimits

コンテナのデフォルト ulimits を上書きします。単一の整数値で上限を指定できるだけでなく、ソフト／ハード・リミットの両方も指定できます。

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

userns_mode

userns_mode: "host"

Docker デーモンでユーザ名前空間の指定があっても、このサービスに対する ユーザ名前空間(user namespace) を無効にします。詳しい情報は dockerd をご覧ください。

注意

docker stack deploy 使用時の注意

swarm モードのスタックにデプロイ する場合、 userns_mode オプションは無視されます。

volumes

ホスト上のパスや 名前付きボリューム(named volumes) のマウントを、サービスのサブオプションとして指定します。

ホスト上のパスに対するマウントは、単一サービス向け定義の一部として記述できます。また、その場合はトップレベルの volumes キー定義は不要です。

ですが、複数のサービスを横断してボリュームを再利用したい場合は、名前付きボリュームを トップレベルの volume キー としての定義が必要です。

注釈

バージョン 3 ファイル形式で変わりました

トップレベルの volumes キー定義は、名前付きボリュームを定義し、各サービスの volumes 一覧から参照できるようになります。これは Compose ファイル形式の初期バージョンの volumes_from を置き換えるものです。

次の例が表すのは、名前付きボリューム（ mydata ）は web サービスが使用しつつ、単一のサービス（ db サービスの volumes にある1行目のパス）に対するバインドマウントです。また、 db サービスも名前付きボリューム dbdata （2つめのパスは db サービス以下の volumes ）を使いますが、古い書式の文字を使って名前付きボリュームを定義しています。名前付きボリュームを使うには、以下にあるようにトップレベルの 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:

注釈

volumes の一般的な情報は、ドキュメントの ボリュームの利用 と ボリュームプラグイン をご覧ください。

短い書式

短い書式(short syntax) は、一般的に [ソース:]ターゲット[:モード] の形式を使います。 ソース の場所にはホスト上のパスまたはボリューム名のどちらかを指定できます。 ターゲット とはボリュームがマウントされるコンテナ上のパスです。標準的なモードは、 ro は 読み込み専用(read-only) と rw の 読み書き(read-write) （デフォルト）です。

ホスト上の相対パスをマウント可能です。相対パスは Compose 設定ファイルが使っているディレクトリを基準とします。相対パスは . または .. で始まります。

volumes:
  # パスを指定する場合は、Engine がボリュームを作成
  - /var/lib/mysql

  # 絶対パスを指定しての割り当て
  - /opt/data:/var/lib/mysql

  # ホスト上のパスを指定する時は、Compose ファイルからの相対パスを指定
  - ./cache:/tmp/cache

  # ユーザ用ディレクトリのパスを使用
  - ~/configs:/etc/configs/:ro

  # 名前付きボリューム（Named volume）
  - datavolume:/var/lib/mysql

長い書式

ヒント

ファイル形式 バージョン 3.2 で追加されました。

長い書式(long syntax) は、短い書式では表現できない追加フィールドを設定できるようにします。

  • type ：マウントの 種類(type) で volume 、 bind 、 tmpfs 、 npipe のどれか

  • source ： マウント元(source) であり、バインド・マウントするホスト上のパスか、 トップレベルの volume キー で定義済みのボリューム名。tmpfs マウントでの利用には、不適切

  • target ：コンテナ内で、ボリュームをマウントするパス

  • read_only ：ボリュームを読み込み専用に指定するフラグ

  • bind ：バインドの追加オプションを指定

    • propagation ：バインドには プロパゲーション・モード(propagation mode) を使用

  • volueme ：ボリュームの追加オプションを指定

    • 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:

注釈

バインド・マウントを作成する場合、長い構文では参照するフォルダを事前に作成しておく必要があります。短い構文では、対象フォルダが存在しなければ即時作成します。詳しい情報は バインド・マウントのドキュメント をご覧ください。

サービス、swarm、stack ファイルでのボリューム

注釈

docker stack deploy 使用時の注意

サービス、swarm、 docker-stack.yml ファイルを扱う場合、気を付けることがあります。それは、タスク（コンテナ）の背後にあるサービスが swarm 上のどこかにあるノードにデプロイされるため、サービスを更新するたびにノードが異なる可能性があります。

名前付きボリュームのソースとして指定した場所が存在していなければ、Docker はサービスの後ろにある各タスクに対し、それぞれ匿名ボリュームを作成します。匿名ボリュームは、関連付けられたコンテナが削除されると、存続しません。

データを保持し続けたい場合は、名前付きボリュームを使い、かつ、複数のホストで扱えるボリュームドライバを使いますので、あらゆるノード上でアクセス可能なデータとなります。あるいは、サービスにタイして制約（constraint）を指定し、ボリュームが存在しているノード上にタスクがデプロイされるようにします。

Docker Labs にある投票アプリ例 向けの docker-stack.yml を例に挙げると、 postgres データベースを動かすための db と呼ぶサービスを定義します。swarm 上でデータを保持するため、名前付きボリュームを定義します。また、 manager ノードでのみ実行するよう制約を加えています。先の yaml ファイルから関連する部分だけ取り出したのがこちらです。

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

それぞれの単一の値であり、 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

期間の指定

設定オプションのいくつかには、 healthcheck 用サブオプションの interval と timeout のように、期間を文字列で指定可能な形式があります。次のように指定します。

2.5s
10s
1m30s
2h32m
5h34m56s

サポートしている単位は、 us 、 ms 、 s 、 m 、 h です。

バイト値の指定

設定オプションのいくつかには、 blkio_config 用サブオプションの device_read_bps のように、バイト値を文字列で指定可能な形式があります。次のように指定します。

2b
1024kb
2048k
300m
1gb

サポートしている単位は、 b 、 k 、 m 、 g と、他にも kb 、 mb 、 gd の記法です。

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

サービス宣言の一部として ボリューム を臨機応変に宣言できますが、このセクションでは、複数のサービス間（ volumes_from に依存）を横断して再利用可能な 名前付きボリューム(named volume) を作成します。それから、 docker コマンドラインや API を使って、簡単に取り出したり調査したりします。

ボリューム上での一般的な情報は、 ボリュームの使用 と ボリューム・プラグインの記述 をご覧下さい。

以下は2つのサービスをセットアップする例です。データベースの（ data-volume という名前の）データ・ディレクトリを、他のサービスからはボリュームとして共有するため、定期的なバックアップのために利用できます。

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 の外でボリュームを作成します（訳者注：Compose が管理していない Docker ボリュームを利用します、という意味）。 docker-compose up を実行してもボリュームを作成しません。もしボリュームが存在していなければ、エラーを返します。

バージョン 3.3 形式以下では、external は他のボリューム用の設定キー（ driver 、driver_opts 、 labels ） と一緒に使えません。この制限は、バージョン 3.4 以上ではありません。

以下の例は、 [プロジェクト名]_data という名称のボリュームを作成する代わりに、Compose は data という名前で外部に存在するボリュームを探し出し、それを db サービスのコンテナの中にマウントします。

version: '3.4'

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

volumes:
  data:
    external: true

注意

バージョン 3.4 ファイル形式で非推奨となりました

external.name はバージョン 3.4 ファイル形式から非推奨となり、代わりに name を使います。

また、Compose ファイルの中で使われている名前を参照し、ボリューム名を指定可能です。

volumes
  data:
    external:
      name: actual-name-of-volume（実際のボリューム名）

注意

docker stack deploy 使用時の注意

docker stack deploy を使い、 swarm モード を使って（ docker compose up に代わりに）アプリケーションを起動するとき、 外部ボリューム(extra volumes) が存在しなければ作成します。swarm モードでは、サービスの定義時にボリュームが自動的に作成されます。サービスタスクが新しいノードにスケジュールされると、 swarmkit はローカルノード上にボリュームを作成します。詳しく知るには、 moby/moby#29976 をご覧ください。

labels

ヒント

ファイル形式 バージョン 2.1 で追加されました。

Docker ラベル を使い、コンテナにメタデータを追加します。配列もしくは 辞書形式(dictionary) で指定できます。

他のソフトウェアが使うラベルと競合しないようにするため、ラベルには逆引き 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 で追加されました。

このボリュームに対してカスタム名を設定します。この名前の領域は、特別な文字列を含むボリュームとして参照できます。この名前はそのまま全体を通して使用されますので、他の場所ではボリューム名として使用 できません 。

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 でしょうし、 Swarm 上であれば overlay でしょう。

ドライバが使えなければ、Docker Engine はエラーを返します。

driver: overlay

bridge

単一ホスト上では、Docker はデフォルトで bridge ネットワークを使用します。ブリッジネットワークの動作については、 Docker Labs チュートリアルにある Bridge networking をご覧ください。

overlay

overlay ドライバは /engine/swarm 上の複数のノードを横断する名前付きネットワークを作成します。

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 と none ）、サービスが各ネットワークに接続するには、それらの別名でアクセス権限を与えます。

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

ヒント

Compose 形式 バージョン 3.2 で追加されました。

driver を overlay に設定した時のみ利用できます。これを true に指定すると、スタンドアロン・コンテナが対象ネットワークに加え、サービスに対しても接続できるようになります。もしもスタンドアロン・コンテナがオーバレイネットワークにアタッチすると、サービスとスタンドアロン・コンテナが通信可能となります。さらに、他の Docker デーモンからもオーバレイ・ネットワークに接続できるようになります。

networks:
  mynet1:
    driver: overlay
    attachable: true

enable_ipv6

このネットワーク上で IPv6 通信を有効にします。

警告

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

enable_ipv6 が必要な場合は、バージョン 2 Compose ファイルを使います。また、この指定は Swarm モードでも未サポートです。

ipam

IPAM （IPアドレス管理）のカスタム設定を指定します。様々なプロパティ（設定）を持つオブジェクトですが、各々の指定はオプションです。

  • driver ：デフォルトの代わりに、カスタム IPAM ドライバを指定します。

  • config ：ゼロもしくは複数の設定ブロック一覧です。次のキーを使えます。

    • subnet ：ネットワーク・セグメントにおける CIDR のサブネットを指定します。

  • options ：キーバリュー形式で、ドライバ固有のオプションを指定します。

全てを使った例：

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

注釈

gateway のような追加の IPAM 設定は、現時点ではバージョン 2 のみ有効です。

internal

Docker は外部との接続をするために、デフォルトではブリッジネットワークにも接続します。外部への隔たれたオーバレイ・ネットワークを作成したい場合は、このオプションを true に指定できます。

labels

Docker ラベル を使ってコンテナにメタデータを追加します。アレイ形式か辞書形式が使えます。

他のソフトウェアが使っているラベルとの重複を避けるため、逆引き 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 の外にネットワークを作成します（訳者注：Compose が管理していない Docker ネットワークを利用します、という意味）。 docker-compose up を実行してもネットワークを作成しません。もしネットワークが存在していなければ、エラーを返します。

バージョン 3.3 形式までは、external は他のネットワーク用の設定キー（ driver 、driver_opts 、 ipam ） と一緒に使えません。この制限はバージョン 3.4 以上にはありません。

以下の例は、外の世界とのゲートウェイに proxy を使います。 [プロジェクト名]_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ファイル形式で非推奨になりました

external.name はバージョン 3.5 形式で非推奨となり、代わりに name を使います。

また、Compose ファイルの中で使われている名前を参照し、ネットワーク名を指定可能です。

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

name

ヒント

Compose 形式 バージョン 3.5 で追加されました。

このネットワークにカスタム名を指定します。 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 の定義やリファレンスを宣言します。また、対象スタック上のサービスに対しても権限を与えられます。設定の元になるのは file か external です。

  • file ：指定したパスにあるファイル内容から、設定を作成します。

  • external ：true に設定するのは、設定が既に作成済みの場合です。Docker は設定を作成しようとしませんが、もし存在していなければ、 config not found エラーを出します。

  • name ：Docker 内の設定オブジェクトに対する名前です。このフィールドには、対象の設定に対するリファレンス（参照）として用いることができる特別な文字を含められます。この名前は設定でのみ利用できるもので、スタック名の範囲内では 使えません 。バージョン 3.5 ファイル形式から導入されました。

  • driver と driver_opts ：カスタムシークレット・ドライバの名前と、ドライバ固有のオプションをキーバリューのペアで渡します。バージョン 3.8 ファイル形式から導入されました。また、 docker stack の利用時のみサポートされます。

  • template_driver ：使用するテンプレーティング・ドライバの名前です。これは、シークレットのペイロード（内容）をテンプレートとして、どこでどのように扱うかを制御します。現在サポートされているドライバは golang のみで、使うには golang と書きます。バージョン 3.8 ファイル形式から導入され、 docker stack 利用時のみサポートされます。テンプレート化設定の例については テンプレート化設定を使う をご覧ください。

この例では、スタックがデプロイされると my_first_config が（ <スタック名>_my_first_config``として ）作成されます。そして、 ``my_second_config は Docker 内に既に存在しています。

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

外部設定の他の書き方は、既存のサービス内に存在するものとは異なる名前で Docker 上で設定名を使うものです。以下の例は、先ほどの例を redis_config と呼ぶ外部設定を使います。

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

なお、スタック上の各サービスに対しても configs に対するアクセス権限 が必要です。

secrets 設定リファレンス

トップレベルの secrets は configs の定義やリファレンスを宣言します。また、対象スタック上のサービスに対しても権限を与えられます。設定の元になるのは file か external です。

  • file ：指定したパスにあるファイル内容から、設定を作成します。

  • external ：true に設定するのは、設定が既に作成済みの場合です。Docker は設定を作成しようとしませんが、もし存在していなければ、 config not found エラーを出します。

  • name ：Docker 内の設定オブジェクトに対する名前です。このフィールドには、対象の設定に対するリファレンス（参照）として用いることができる特別な文字を含められます。この名前は設定でのみ利用できるもので、スタック名の範囲内では 使えません 。バージョン 3.5 ファイル形式から導入されました。

  • driver と driver_opts ：カスタムシークレット・ドライバの名前と、ドライバ固有のオプションをキーバリューのペアで渡します。バージョン 3.8 ファイル形式から導入されました。また、 docker stack の利用時のみサポートされます。

  • template_driver ：使用するテンプレーティング・ドライバの名前です。これは、シークレットのペイロード（内容）をテンプレートとして、どこでどのように扱うかを制御します。現在サポートされているドライバは golang のみで、使うには golang と書きます。バージョン 3.8 ファイル形式から導入され、 docker stack 利用時のみサポートされます。テンプレート化設定の例については テンプレート化設定を使う をご覧ください。

この例では、スタックがデプロイされると my_first_secret が（ <スタック名>_my_first_secret``として ）作成されます。そして、 ``my_second_secret は Docker 内に既に存在しています。

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

外部設定の他の書き方は、既存のサービス内に存在するものとは異なる名前で Docker 上で設定名を使うものです。以下の例は、先ほどの例を redis_config と呼ぶ外部設定を使います。

Compose ファイル v3.5 以上

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

Compose ファイル v3.4 以下

my_second_secret:
  external:
    name: redis_secret

なお、スタック上の各サービスに対しても secrets に対するアクセス権限 が必要です。

変数の置き換え

設定オプションでは環境変数も含めることができます。シェル上の Compose は docker-compose の実行時に環境変数を使えます。たとえば、シェルで POSTGRES_VERSION=9.3 という変数を設定ファイルで扱うには、次のようにします。

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

この設定で docker-compose up を実行したら、Compose は POSTGRES_VERSION 環境変数をシェル上で探し、それを値と置き換えます。この例では、Compose は設定を実行する前に image に postgres:9.3 を割り当てます。

環境変数が設定されていなければ、Compose は空の文字列に置き換えます。先の例では、 POSTGRES_VERSION が設定されなければ、 image オプションは postgres: です。

環境変数のデフォルト値は doc:.env ファイル <env-file> を使って指定できます。Compose はプロジェクトのディレクトリ内（Compose ファイルが置いてある親フォルダ）を自動的に探します。シェル環境における値は、 .env ファイル内のもので上書きします。

注意

.env ファイル機能が使えるのは docker-compose up コマンドを使った時のみです。 docker stack deploy では機能しません。

$変数 と ${変数} の両方がサポートされています。加えて、 2.1 ファイル形式を使う時は、典型的なシェル構文を用いて、デフォルトの値を指定できます。

  • ${変数:-default} は、環境変数における 変数 が未定義もしくは空の場合、値は default になります。

  • ${変数-default} は、環境変数における 変数 が未定義の場合のみ、値は default になります。

同様に、以下の構文によって省略できない変数を指定できます。

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

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

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

$$ （二重ドル記号）を指定する時は、設定ファイル上でリテラルなドル記号の設定が必要です。Compose は値を補完しませんので、 $$ の指定により、 Compose によって処理されずに環境変数を参照します。

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

もしも間違えてドル記号（ $ ）だけにしたら、 Compose は環境変数の値を解釈し、次のように警告を表示します。

The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.

拡張フィールド

ヒント

Compose 形式 バージョン 3.4 で追加されました。

拡張フィールドを使い、設定の一部の再利用できる場合があります。それぞれの特別フィールドは、Compose ファイルの存在する場所（ルート）に位置する限り利用でき、それらの名前は x- で始まる文字に続きます。

注釈

3.7 形式以降（の 3.x 系統）と、2.4 形式（以降の 2.x 形式）では、拡張フィールドでも 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 merge type を使い、拡張フィールド値の部分的に上書きもできます。例：

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