🐋

Compose file version3のリファレンス

2020/09/24に公開

docker-composeで利用するversion 3の設定をまとめる.

Compose file version 3 reference

Docker Engineが対応するファイルフォーマットのバージョン

Compose and Docker compatibility matrix

1.13.0+ 以降がCompose file verison 3.0に対応する.

設定

build

ビルド時に設定が適用される.

指定したディレクトリにあるdockerfileでコンテナを起動する.
context, dockerfile, argsで指定もできる.

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

buildに合わせてimageを指定すると,Composeはimageで指定されたwebappとオプションのtagを使用して,イメージを作成します.

build: ./dir
image: webapp:tag

上記の例では./dirディレクトリからtagタグのwebappイメージが作成される.

CONTEXT

Dockerfileが含まれるディレクトリ,またはGitリポジトリのURLを入力する.

相対パスを指定すると,Compose fileの位置に関連して解釈される.
このディレクトリはDocker daemonの作成コンテキストにも送られる.

build:
  context: ./dir

DOCKERFILE

Dockerfileの代替.
Composeはビルドに使用する代替ファイルを使用する.ビルドパスの指定も必要になる.

build:
  context: .
  dockerfile: Dockerfile-alternate

ARGS

ビルド引数で,ビルドプロセスの間だけアクセスできる環境変数.
まず引数をDockerfileに指定する.

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

CACHE_FROM

Dockerエンジンがキャッシュの解決に使用するイメージのリスト

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

LABELS

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

ビルド中にRUN命令のために接続するネットワークコンテナを設定する.

build:
  context: .
  network: host
build:
  context: .
  network: custom_network_1

ビルド中のネットワークを無効化するにはnoneを使う.

build:
  context: .
  network: none

SHM_SIZE

コンテナをビルドするために/dev/shmパーティションのサイズを設定する.
バイト数を表す整数値またはbyte valueを表す文字列として指定する.

build:
  context: .
  shm_size: '2gb'
build:
  context: .
  shm_size: 10000000

TARGET

Dockerfile の中で定義されたように,指定したステージをビルドする.詳細はmulti-stage buildを参照.

build:
  context: .
  target: prod

cap_add, cap_drop

コンテナの権限を制限して起動する.
man 7 capabilities の権限が指定できる.

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

command

デフォルトのコマンドを上書きして起動する.

command: bundle exec thin -p 3000

コマンドはdockerfileと同様の方法で配列にもできる,

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

configs

1サービスのconfigs構成を基準とした,サービスごとのconfig群へのアクセスを許可する.
2つの構文をサポートする.

より多くの情報は configs を参照.

SHORT SYNTAX

短縮構文の変数はcofig名のみを指定する.このコンテナの認可はconfigにアクセスし,コンテナ内の/<config_name> にマウントする.

redisサーバで configs を利用した例.

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

長い構文はサービスのタスクコンテナ内でconfigを作成する方法の粒度が細かくなります.

  • source: Dockerに存在する構成の名前
  • target: サービスのタスクコンテナにマウントされるファイルのパスと名前.指定しない場合,デフォルトは /<source>
  • uid and gid: サービスのタスクコンテナ内にマウントされたconfigファイルのUIDとGIDの数値.Linuxでデフォルトはともに 0.Windowsはサポートされていない.
  • mode: サービスのタスクコンテナ内にマウントされるファイルの8進表記のアクセス許可.デフォルトは 0444 です.Configは一時ファイルシステムにマウントされているため書き込み可能ではないため、書き込み可能ビットを設定しても無視される. 実行可能ビットを設定できます. UNIXファイルのアクセス許可モードに慣れていない場合は、このアクセス許可計算ツールが役立つことがある.
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

container_name

カスタムコンテナ名を指定する.

container_name: my-web-container

Dockerコンテナ名はユニークである必要があり,カスタム名では複数のコンテナにスケーリングができない.

credential_spec

マネージドサービスアカウントの資格情報を設定します.
このオプションはWindowsコンテナを使用するサービスのみ使用されます.

file: を使用する場合,参照されるファイルはDockerデータディレクトリ内の CredentialSpecs サブディレクトリに存在する必要があります.
Windowsでは C:\ProgramData\Docker\ がデフォルトです.
次の例では名前を付けたファイルから資格情報をロードします.

C:\ProgramData\Docker\CredentialSpecs\my-credential-spec.json
credential_spec:
  file: my-credential-spec.json
redential_spec:
  file: c:/WINDOWS/my-credential-spec.txt

credential_spec:
  registry: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

registry: を使用する時,資格情報はデーモンが実行するホストのWindowsレジストリから読む.レジストリの値は次の名前で与えられた場所に配置する必要がある

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

次の例ではレジストリ中の my-credential-spec と名前がついた値の資格情報を読み取る例である

credential_spec:
  registry: my-credential-spec

EXAMPLE GMSA CONFIGURATION

サービスにgMSA認証情報を設定する時, 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 は依存関係の順序でサービスを開始します次の例では web の前にdbredis を起動します
  • docker-compose up SERVICESERVICE の依存関係を自動的に含みます.以下の例では docker-compose up webdbredis を作成して開始します.
  • docker-compose stop は依存関係の順番に沿ってサービスを停止します. 以下の例では webdbredis の前に停止します.
version: "3.9"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

deploy

サービスの実行とデプロイに関連する構成を指定する.
swarmのdocker stack deployでデプロイした時にのみ作用する.
そして, docker-compose updocker-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

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

  • endpoint_mode: vip - Dockerはクライアントへネットワーク上のサービスに到達するフロントエンドとして振る舞う,仮想IPをサービスに割り当てます. Dockerはサービスに参加しているノードの数やIPまたはポートをクライアントが知らなくても,クライアントとサービスで使用可能なわーカードノードの間でリクエストをルーティングします.(デフォルト設定)
  • endpoint_mode: dnsrr - DNSラウンドロビンのサービスディスカバリは単一の仮想IPを使いません. Dockerはサービス名のDNSクエリがIPアドレスのリストを返すようにサービスのDNSエントリを設定します.クライアントはこれらの一つに直接接続します.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 のオプションはswarm mode CLIコマンド docker service create のフラグとしても機能します.

swarm modeのサービスディスカバリとネットワークを更に知るには, swarm mode topicsの Configure service discovery を参照してください.

labels

serviceの識別ラベル.これらのラベルはserviceにだけセットされ,サービスのコンテナにはセットされません.

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

コンテナにラベルを付与するには deploy の外側で labels キーを使用します.

To set labels on containers instead, use the labels key outside of deploy:

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

devices

ホストのデバイスをコンテナのデバイスに割り当てる.
docker stack deploy を使ったswarm modeでは無視される.

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

depends_on

コンテナの依存関係を定義する.
次の例では, webdbredis に依存する.

docker stack deploy を使ったswarm modeでは無視される.

version: '3'
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

依存は起動の順序に関係し, dbredis が起動してから web が起動する.

dbが起動し,且つredisが起動 -> webが次に起動

dns

DNSサーバを指定する.
docker stack deploy を使ったswarm modeでは無視される.

dns: 8.8.8.8
dns:
  - 8.8.8.8
  - 9.9.9.9

DNSで検索するドメインを指定する。
docker stack deploy を使ったswarm modeでは無視される.

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

tmpfs

コンテナ内でtmpfsを使用するディレクトリを指定する。
docker stack deploy を使ったswarm modeでは無視される.

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

entrypoint

コンテナが実行するファイルを設定する。
デフォルトのエントリポイントを上書きする。
entrypoint を指定すると、既存の ENTRYPOINT CMD は実行しない。

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

env_file

コンテナの環境変数を別ファイルにまとめて指定ができる。
既存の環境変数があれば env_file の値で上書きする。
build オプションと合わせて指定すると、build中は enviroment で指定した、環境変数は見えないことに注意。
build に変数を渡す場合は args オプションで指定する。

env_file: .env

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

env_file の中身は VAR=VAL 形式で設定する。

# Set Rails/Rack environment
RACK_ENV=development

environment

コンテナの環境変数を追加する。
env_file の違いはdocker-comose.yamlに直接記述すること。
build オプションと合わせて指定すると、build中は enviroment で指定した、環境変数は見えないことに注意。
build に変数を渡す場合は args オプションで指定する。

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

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

expose

コンテナ内に限定して公開するポートを指定する。
exposeで公開したポートは linked servicesからのみアクセスが可能。

ホスト向けに公開したい場合は ports オプションを使用すること。

expose:
 - "3000"
 - "8000"

docker-composeのスコープ外にあるコンテナと通信する.

  • docker-compose.yaml のスコープ外
  • Composeのスコープ外

docker-composeで起動するコンテナ群が,他コンテナに共通サービスを提供している場合に活用できる.
<container name>:<alias name>link のように動作する.

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

extra_hosts

コンテナ内にホスト名とIPアドレスの対応表を設定する.

xtra_hosts:
 - "somehost:162.242.195.82"
 - "otherhost:50.31.209.229"

設定内容は /etc/hosts に反映する.

162.242.195.82  somehost
50.31.209.229   otherhost

healthcheck

コンテナのサービス死活監視に利用するコマンドを設定する.

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

imageで設定されたヘルスチェックを無効にしたい場合は disable:true を設定する.

healthcheck:
  disable: true

isolation

コンテナの分離技術を指定する.

  • Linux: default
  • Windows: default, process, hyperv

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"

コンテナと他のサービスを繋げる.
リンクに属するサービスの名前を別名で定義することもできる.
SERVICE:ALIAS

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

生成したリンクの名前は,到達可能なホスト名とみなされる.

注記

  • linksnetworks を両方定義した場合,リンクを有するサービスは通信するために1つ以上のネットワークを共有する必要がある.
  • docker stack deploy を使ったswarm modeでは無視される.

logging

サービスのロギングを設定する.

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

コンテナのサービスに対するロギング形式は driver で指定する.
--log-driver と同じ意味を持つ.

デフォルトはjson-file

driver: "json-file"
driver: "syslog"
driver: "none"

注記

json-filejournaldドライバは,次のログから直接取得する.

  • docker-compose up
  • docker-compose logs

他のドライバはログを出力しない

syslog

ロギングはオプションをkey-valueで指定する.

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

json-file

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

network_mode

ネットワークモードを指定する.
service:[service name] の形式と合わせて,docker client の --network と同じ意味を持たせる.

network_mode: "bridge"
network_mode: "host"
network_mode: "none"
network_mode: "service:[service name]"
network_mode: "container:[container name/id]"

注記

  • docker stack deploy を使ったswarm modeでは無視される.
  • network_mode: "host"links と組み合わせられない.

networks

networks を最上位として,使用するネットワークを列挙する.

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

ALIASES

ネットワーク上のサービスを 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: '2'

services:
  web:
    build: ./web
    networks:
      - new

  worker:
    build: ./worker
    networks:
      - legacy

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

networks:
  new:
  legacy:

注記

ネットワーク全体のエイリアスは複数のコンテナが例え複数のサービスであっても共有できる.
そうならば,コンテナ名を解決することは保証できない.

IPV4_ADDRESS, IPV6_ADDRESS

固定のIPv4アドレス,IPv6アドレスを指定する.

networks セクションの最上位に対応するネットワーク構成には,
静的アドレスをカバーするサブネット構成を持つ ipam ブロックが必要.

version: '2.1'

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
      -
        subnet: 2001:3984:3989::/64

pid

pid: "host"

PIDモードをホストPIDモードに設定する.
これはコンテナとホストのオペレーティングシステムとのPIDアドレス空間の共有を有効にする.

このフラグで起動されたコンテナはベアメタルマシン上の他コンテナにアクセスと操作ができる.
他コンテナから逆のことも可能.

ports

ポートを公開する.

注記

HOST:CONTAINER 形式で 60より小さいポートを指定すると,エラーとなる.
YAMLが xx:yy の形式を60進数と解釈するため.
回避するにはポート番号を明示的に文字列で指定する.

SHORT SYNTAX

HOST:CONTAINER でホストとコンテナのポートを併記する.
HOSTが指定されなければ,ランダムなポートが割り振られる.

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

LONG SYNTAX

short syntaxで表現しきれない追加設定を許可する.

  • target : コンテナ内のポート
  • published : 公開されているポート
  • protocol : 公開するポートのプロトコル(TCP/UDP)
  • mode :
    • host : 各ノードにホストのポートを公開する
    • ingress : swarm modeの入力でロードバランスされるポート
ports:
  - target: 80
    published: 8080
    protocol: tcp
    mode: host

注記

long syntaxは3.2以降から利用可能.

secrets

サービスごとの secrets 設定を用いて,機密へのアクセス権限を許可する.

注記

機密は最上位に既に存在しているか,定義しなければならない.

SHORT SYNTAX

short syntax形式の変数はsecret nameだけ指定できる.
これによりコンテナの機密にアクセスできる.
そして,コンテナ内に /run/secrets/<secret_name> としてマウントする.

指定元の名前とマウントポイントはどちらもsecret nameとなる.

Docker 1.13.1での制限

Docker 1.13.1のバグにより,短い構文を使用するとアクセス権000のsecretがマウントされる.
コマンドがルートユーザとして実行されない場合, short syntaxで定義されたsecretがコンテナ内で読み取れないことを意味する.

Docker 1.13.1でこの問題を回避するには short syntaxを使うこと.

LONG SYNTAX

long syntaxはサービスのタスクコンテナ内で,secretがどのように生成するかを詳細に与える.

  • source : dockerに存在するconfigの名前
  • target : サービスのタスクコンテナにマウントされるパス付きのファイル名.デフォルトは /<source>
  • uid , gid : サービスのタスクコンテナ内でマウントしたconfigのUIDまたはGIDを数字で表現する.デフォルトは 0 .Windowsではサポートしない.
  • mode : サービスタスクのコンテナ内でマウントするファイルのパーミッション.8進数で表現し,Linuxの権限設定に準ずる.デフォルトは 0444
    • Configは一時的なファイルシステムにマウントされるため,書き込みビットを立てても無視される.実行ビットはセットできる.

次の例は my_config を コンテナ内で redis_config として指定する例.

version: "3.3"
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

short syntaxとlong syntaxは混在することが可能.

cgroup_parent

コンテナへオプションの親cgroupを指定する.

cgroup_parent: m-executor-abcd

注記

version 3のswarm modeでは無視される.

container_name

コンテナ名を指定する。指定がない場合はデフォルト名が生成される。
次の例では my-web-container というコンテナ名になる。

container_name: my-web-container

コンテナ名を指定すると1コンテナしか起動できない。
これはコンテナ名は一意を保つ必要があるため。
複数起動をするとエラーになる。

注記

version 3のswarm modeでは無視される.

credential_spec

管理サービスアカウントの資格情報の設定。(Windowsのみ)
credential_specfile://<filename> または registry://<value-name> で記述する必要がある.

file を使う時,Dockerのデータディレクトリに CredentialSpecs ディレクトリを作って参照するファイルを置く.
データディレクトリのデフォルトは C:\ProgramData\Docker\ になる.

次の例は C:\ProgramData\Docker\CredentialSpecs\my-credential-spec.json に証明書を置いた例.

credential_spec:
  file: my-credential-spec.json

regisitry: を使うと,デーモンのホストのWindowsレジストリから証明書を読む.

credential_spec:
  registry: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

注記

このオプションはv3.3で追加

deploy

デプロイと動作中のサービスに関連する設定を指定する.
このオプションは docker stack deploy の swarm に作用し, docker-compose updocker-compose run に無視される.

version: '3'
services:
  redis:
    image: redis:alpine
    deploy:
      replicas: 6
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

注記

version 3限定

ENDPOINT_MODE

swarmに繋がっている外部クライアントに向けてサービスディスカバリ方法を指定する.

  • endpoint_mode: vip

デフォルト値.DockerのサービスをVirtual IPに割り当てる.

  • endpoint_mode: dnsrr

DNSラウンドロビンを使う.

version: "3.3"

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 でも動作する.
サービスディスカバリとネットワークの設定を更に学びたい場合は, Configure service discovery を参照すること.

注記

version 3.3限定

LABELS

サービスのラベルを指定する.これらのラベルはサービスの集合に対してのみ指定する.
サービスのコンテナに指定するものではない.

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

コンテナへのラベルの代わりに, deploy の外側でlabel を使用する.

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

参考

Compose file version 3 reference
Compose ファイル・リファレンス
docker-compose.ymlの命令を理解して、よりDockerを有効活用したい!
Docker Compose - docker-compose.yml リファレンス
コンテナの連結と操作 - Docker User Guide

Discussion