Compose file version3のリファレンス
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
andgid
: サービスのタスクコンテナ内にマウントされた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
の前にdb
とredis
を起動します -
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
deploy
サービスの実行とデプロイに関連する構成を指定する.
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
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
コンテナの依存関係を定義する.
次の例では, web
は db
と redis
に依存する.
docker stack deploy
を使ったswarm modeでは無視される.
version: '3'
services:
web:
build: .
depends_on:
- db
- redis
redis:
image: redis
db:
image: postgres
依存は起動の順序に関係し, db
と redis
が起動してから 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_search
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"
external_links
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"
links
コンテナと他のサービスを繋げる.
リンクに属するサービスの名前を別名で定義することもできる.
SERVICE:ALIAS
web:
links:
- db
- db:database
- redis
生成したリンクの名前は,到達可能なホスト名とみなされる.
注記
-
links
とnetworks
を両方定義した場合,リンクを有するサービスは通信するために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-file
と journald
ドライバは,次のログから直接取得する.
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_spec
は file://<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 up
と docker-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