docker-compose文件语法解析（v3.x）

时间 2019-11-20

标签 docker compose 文件语法解析 v3.x 栏目 Docker 繁體版

原文原文链接

文件配置php

compose文件是一个定义服务（service）、网络（network）和卷（volume）的YAML文件。Compose 文件的默认路径是 ./docker-compose.yml前端

提示：能够是用 .yml 或 .yaml 做为文件扩展名node

服务（service）定义包含应用于为该服务启动的每一个容器的配置，就像传递命令行参数给docker container create同样。一样，网络和卷的定义相似于给 docker network create 和 docker volume create传递参数。mysql

正如 docker container create 在 Dockerfile 指定选项，如 CMD、 EXPOSE、VOLUME、ENV，在默认状况下，不须要在docker-compose.yml中再次指定它们。linux

可使用 Bash 类 ${VARIABLE} 语法在配置值中使用环境变量。nginx

配置选项git

１.bulidweb

服务除了能够基于指定的镜像（从docker hub中拉取），还能够基于Dockerfile构建的镜像，在使用 up 启动时执行构建任务，这个构建标签就是 build，它能够指定 Dockerfile 所在目录的路径。Compose 将会利用它自动构建这个镜像，而后使用这个镜像启动服务容器redis

build: /path/to/build/dirsql

也能够是相对路径，当提供的值是相对路径时，它被解释为相对于Compose文件的位置

build: ./dir

设定上下文根目录，而后以该目录为准指定 Dockerfile

build:

context: ./

dockerfile: path/of/Dockerfile

示例：

version: '3'

services:

webapp:

build: ./dir

若是 context 中有指定的路径，而且能够指定Dockerfile和args。那么arg这个标签，就像 Dockerfile 中的 ARG 指令同样，它能够在构建过程当中指定环境变量，可是在构建成功后取消，在docker-compose.yml 文件中也支持这样的写法：

version: '3'

services:

webapp:

build:

context: ./dir

dockerfile: Dockerfile-alternate

args:

buildno: 1

与 ENV 不一样的是，ARG 能够为空值

args:

- buildno

- password

若是要指定 image 以及 build ，选项格式为

build: ./dir

image: webapp:tag

这会在 ./dir 目录生成一个名为 webaapp 和标记为 tag 的镜像

注意：当用(Version 3) Compose 文件在群集模式下部署堆栈时，该选项被忽略。由于 docker stack 命令只接受预先构建的镜像

2. context

context 选项能够是 Dockerfile 的文件路径，也能够是到连接到 git 仓库的 url

当提供的值是相对路径时，它被解析为相对于撰写文件的路径，此目录也是发送到 Docker 守护进程的 context

build:

context: ./dir

３. dockerfile

使用此 dockerfile 文件来构建，必须指定构建路径

build:

context: .

dockerfile: Dockerfile-alternate

４. args

添加构建参数，这些参数是仅在构建过程当中可访问的环境变量

首先，在Dockerfile中指定参数：

ARG buildno

ARG password

RUN echo "Build number: $buildno"

RUN script-requiring-password.sh "$password"

而后指定 build 下的参数，能够传递映射或列表

build:

context: .

args:

buildno: 1

password: secret

或

build:

context: .

args:

- buildno=1

- password=secret

指定构建参数时能够省略该值，在这种状况下，构建时的值默认构成运行环境中的值

args:

- buildno

- password

Note： YAML 布尔值（true，false，yes，no，on，off）必须使用引号括起来，觉得了可以正常被解析为字符串

５. cache_from

编写缓存解析镜像列表

build:

context: .

cache_from:

- alpine:latest

- corp/web_app:3.14

6. labels

使用 Docker标签将元数据添加到生成的镜像中，可使用数组或字典。

建议使用反向 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"

7.shm_size

3.5版本中新增

设置容器 /dev/shm 分区的大小，值为表示字节的整数值或表示字符的字符串

build:

context: .

shm_size: '2gb'

或

build:

context: .

shm_size: 10000000

8. target

3.4版本中新增

根据对应的 Dockerfile 构建指定 Stage，即停留在特定的构建阶段

build:

context: .

target: prod

9. cap_add、cap_drop

添加或删除容器功能，权限清单详见：http://linux.die.net/man/7/capabilities

cap_add:

- ALL

cap_drop:

- NET_ADMIN

- SYS_ADMIN

注意：当用(Version 3) Compose 文件在群集模式下部署堆栈时，该选项被忽略。由于 docker stack 命令只接受预先构建的镜像

10. command

覆盖容器启动后默认执行的命令

command: bundle exec thin -p 3000

该命令也能够是一个列表，方法相似于 dockerfile:

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

11. configs

使用服务 configs 配置，为每一个服务赋予相应的访问权限，支持两种不一样的语法。

注意：配置必须存在或在configs堆栈文件的顶层中定义，不然堆栈部署失效

11.1.SHORT 语法

SHORT 语法只能指定配置名称，这容许容器访问配置并将其安装在 /<config_name> 容器内，源名称和目标装入点都设为配置名称。

version: "3.3"

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

以上实例使用 SHORT 语法将 redis 服务访问授予 my_config 和 my_other_config ,并被 my_other_config 定义为外部资源，这意味着它已经在 Docker 中定义。能够经过 docker config create 命令或经过另外一个堆栈部署。若是外部部署配置都不存在，则堆栈部署会失败并出现config not found 错误。

注意：config定义仅在 3.3 版本或在更高版本中受支持，YAML 的布尔值（true, false, yes, no, on, off）必需要使用引号引发来（单引号、双引号都可），不然会当成字符串解析。

11.2. LONG 语法

LONG 语法提供了建立服务配置的更加详细的信息

source：Docker中存在的config的名称
target：要在服务的任务中装载的文件的路径或名称。若是未指定则默认为/<source>
uid和gid：在服务的任务容器中拥有安装的配置文件的数字UID或GID。若是未指定，在Linux上默认为0。Windows不支持。
mode：在服务的任务容器中安装的文件的权限，以八进制表示法。例如，0444 表明文件可读的。默认是 0444。若是配置文件没法写入，是由于它们安装在临时文件系统中，因此若是设置了可写位，它将被忽略，可设置执行位。

下面示例在容器中将 my_config 名称设置为 redis_config，将mode设置为 0440（group-readable）并将用户和组设置为103。redis服务没法访问my_other_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

能够同时授予多个配置的服务相应的访问权限，也能够混合使用 LONG 和 SHORT 语法，定义配置并不意味着授予服务访问权限。

12. cgroup_parent

能够为容器选择一个可选的父 cgroup

cgroup_parent: m-executor-abcd

注意：当使用（Version 3）Compose 文件在群集模式下部署堆栈时，忽略此选项

13. container_name

为自定义的容器指定一个名称，而不是使用默认的名称

container_name: my-web-container

由于 docker 容器名称必须是惟一的，所以若是已指定自定义名称，则没法将服务扩展到1个容器以外

14. credential_spec

3.3版本中新增

为托管服务帐户配置凭据规范，此选项仅适用于 Windows 容器服务

在 credential_spec 上的配置列表格式为 file://<filename> 或 registry://<value-name>

使用 file: 应该注意引用的文件必须存在于CredentialSpecs,docker 数据目录的子目录中。在 Windows 上，该目录默认为 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

15. deploy

仅用于v3版本中

指定与部署和运行服务相关的配置

只有当使用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

这里有几个子选项

1. endpoint_mode

仅3.3版本

指定链接到群组外部客户端服务发现方法

endpoint_mode:vip ：Docker为该服务分配了一个虚拟IP(VIP)，做为客户端到达网络服务的“前端”， Docker在客户端和服务的可用工做节点之间路由请求，而无需客户端知道有多少节点参与服务或其IP地址或端口（默认设置）。
endpoint_mode: dnsrr : DNS轮询（DNSRR）服务发现不使用单个虚拟 IP。Docker为服务设置 DNS 条目，使得服务名称的 DNS 查询返回一个 IP 地址列表，而且客户端直接链接到其中的一个。若是想使用本身的负载均衡器，或者混合 Windows 和 Linux 应用程序，则 DNS 轮询调度（round-robin）功能就很是实用。

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:

2.labels

指定服务的标签，这些标签仅在服务上设置，而不是在服务的任何容器上设置。

version: "3"

services:

web:

image: web

deploy:

labels:

com.example.description: "This label will appear on the web service"

要在容器上设置标签，而不是在deploy中设置，在deploy外设置：

version: "3"

services:

web:

image: web

labels:

com.example.description: "This label will appear on all containers for the web service"

3.mode

global：集群中每一个节点只会为服务启动一个容器
replicated：指定容器数量（默认）

version: '3'

services:

worker:

image: dockersamples/examplevotingapp_worker

deploy:

mode: global

4. placement

指定 constraints 和 preferences

version: '3'

services:

db:

image: postgres

deploy:

placement:

constraints:

- node.role == manager

- engine.labels.operatingsystem == ubuntu 14.04

preferences:

- spread: node.labels.zone

５.replicas

若是服务是 replicated（默认)，须要指定运行的容器数量

version: '3'

services:

worker:

image: dockersamples/examplevotingapp_worker

networks:

- frontend

- backend

deploy:

mode: replicated

replicas: 6

6. resources

配置资源限制

version: '3'

services:

redis:

image: redis:alpine

deploy:

resources:

limits:

cpus: '0.50'

memory: 50M

reservations:

cpus: '0.25'

memory: 20M

此例子中，redis 服务限制使用不超过50M 的内存和 0.50（50％）可用处理时间（CPU），而且保留 20M 了内存和 0.25 CPU时间

7. restart_policy

配置容器的从新启动，取代restart

condition：值能够为 none 、on-failure 以及 any(默认)
delay：尝试重启的等待时间，默认为 0
max_attempts：在放弃以前尝试从新启动容器次数（默认：never give up）。若是在window配置中从新启动没有成功，则此尝试不计入配置max_attempts 值。例如，若是 max_attempts 值为 2，而且第一次尝试从新启动失败，则可能会尝试从新启动两次以上。
window：在决定从新启动是否成功以前的等时间，指定为持续时间（默认值：decide immediately）。

version: "3"

services:

redis:

image: redis:alpine

deploy:

restart_policy:

condition: on-failure

delay: 5s

max_attempts: 3

window: 120s

8、rollback_config

3.7版本及以上支持

配置在更新失败的状况下应如何回滚服务。

parallelism：同时回滚的容器数。若是设置为0，则全部容器同时回滚。
delay：每一个容器组的回滚之间等待的时间（默认为0）。
failure_action：若是回滚失败该怎么办。continue或pause（默认pause）
monitor：每次更新任务后的持续时间以监视失败(ns|us|ms|s|m|h)（默认为0）。
max_failure_ratio：回滚期间容忍的失败率（默认值为0）。
order：回滚期间的操做顺序。其中之一：
stop-first（旧任务在启动新任务以前中止），或
start-first（首先启动新任务，而且正在运行的任务暂时重叠）（默认stop-first）。

9. update_config

配置更新服务，用于无缝更新应用（rolling update)

parallelism：一次性更新的容器数量
delay：更新一组容器之间的等待时间。
failure_action：若是更新失败，能够执行的的是 continue、rollback 或 pause （默认）
monitor：每次任务更新后监视失败的时间(ns|us|ms|s|m|h)（默认为0）
max_failure_ratio：在更新期间能接受的失败率
order：更新次序设置，top-first（旧的任务在开始新任务以前中止）、start-first（新的任务首先启动，而且正在运行的任务短暂重叠）（默认 stop-first）

注意：order仅支持v3.4及更高版本

version: '3.4'

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 的几个子选项
build、cgroup_parent、container_name、devices、tmpfs、external_links、links、network_mode、restart、security_opt、stop_signal、sysctls、userns_mode

16. devices

设置映射列表，与 Docker 客户端的 --device 参数相似 :

devices:

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

注意：使用（版本3）Compose文件在群集模式下部署堆栈时，将忽略此选项

17. depends_on

此选项解决了启动顺序的问题

在使用 Compose 时，最大的好处就是不多须要输入启动命令，可是通常项目容器启动的顺序是有要求的，若是直接从上到下启动容器，必然会由于容器依赖问题而启动失败。例如在没启动数据库容器的时候启动了应用容器，这时候应用容器会由于找不到数据库而退出，为了不这种状况咱们须要加入一个标签，就是 depends_on，这个标签解决了容器的依赖、启动前后的问题。

指定服务之间的依赖关系，有两种效果：

docker-compose up 以依赖顺序启动服务，下面例子中redis和db服务在web启动前启动
docker-compose up SERVICE 自动包含 SERVICE 的依赖性，下面例子中，例以下面容器会先启动 redis 和 db 两个服务，最后才启动 web 服务：

version: '3'

services:

web:

build: .

depends_on:

- db

- redis

redis:

image: redis

db:

image: postgres

注意：

1)、默认状况下使用 docker-compose up web 这样的方式启动 web 服务时，也会启动 redis 和 db 两个服务，由于在配置文件中定义了依赖关系

2)、版本3再也不支持condition形式depends_on

3）、使用版本3 Compose文件在swarm模式下部署堆栈depends_on时，将忽略该选项

18. dns

自定义 DNS 服务器，与 --dns 具备同样的用途，能够是单个值或列表

dns: 8.8.8.8

dns:

- 8.8.8.8

- 9.9.9.9

19. dns_search

自定义 DNS 搜索域，能够是单个值或列表

dns_search: example.com

dns_search:

- dc1.example.com

- dc2.example.com

20. tmpfs

适用于版本2及以上

挂载临时文件目录到容器内部，与 run 的参数同样效果，能够是单个值或列表

tmpfs: /run

tmpfs:

- /run

- /tmp

注意：使用（版本3-3.5）Compose文件在swarm模式下部署堆栈时，将忽略此选项。

3.6版本及以上：

在容器内安装临时文件系统。Size参数指定tmpfs mount的大小（以字节为单位），默认无限制。

- type: tmpfs

target: /app

tmpfs:

size: 1000

21. entrypoint

在 Dockerfile 中有一个指令叫作 ENTRYPOINT 指令，用于指定入口点。在 docker-compose.yml 中能够定义入口点，覆盖 Dockerfile中的定义：

entrypoint: /code/entrypoint.sh

entrypoint 也能够是一个列表，方法相似于dockerfile

entrypoint:

- php

- -d

- zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so

- -d

- memory_limit=-1

- vendor/bin/phpunit

21. env_file

从文件中添加环境变量，能够是单个值或是列表
若是已经用docker-compose -f FILE 指定了 Compose 文件，那么 env_file 路径值为相对于该文件所在的目录

但environment环境中的设置的变量会覆盖这些值，不管这些值未定义仍是为 None

env_file: .env

或者根据 docker-compose.yml 设置多个：

env_file:

- ./common.env

- ./apps/web.env

- /opt/secrets.env

环境配置文件 env_file 中的声明每行都是以 VAR=VAL 格式，以#开头的行被视为注释并被忽略，空行也被忽略。

# Set Rails/Rack environment

RACK_ENV=development

注意环境变量配置列表的顺序，例以下面例子

docker_compose.yml

services:

some-service:

env_file:

- a.env

- b.env

a.env 文件

# a.env

VAR=1

b.env文件

# b.env

VAR=hello

对于在文件a.env 中指定的相同变量但在文件 b.env 中分配了不一样的值，则在 a.env 设置的值被 b.env 相同变量的值覆盖，此时 $VAR 值为 hello。此外，这里所说的环境变量是对宿主机的 Compose 而言的，若是在配置文件中有 build 操做，这些变量并不会进入构建过程当中，若是要在构建中使用变量仍是首选 arg 标签

22. environment

添加环境变量，可使用数组或字典，任何布尔值：true，false，yes，no，须要用引号括起来，以确保YML解析器不会将它们转换为True或False。与上面的 env_file 选项彻底不一样，反而和 arg 有几分相似，这个标签的做用是设置镜像变量，它能够保存变量到镜像中，也就是说启动的容器也会包含这些变量设置，这是与 arg 最大的不一样。
通常 arg 标签的变量仅用在构建过程当中。而 environment 和 Dockerfile 中的 ENV 指令同样会把变量一直保存在镜像、容器中，相似 docker run -e 的效果

environment:

RACK_ENV: development

SHOW: 'true'

SESSION_SECRET:

或

environment:

- RACK_ENV=development

- SHOW=true

- SESSION_SECRET

23. expose

暴露端口，但不映射到宿主机，只被链接的服务访问。这个标签与 Dockerfile 中的 EXPOSE 指令同样，用于指定暴露的端口，可是只是做为一种参考，实际上 docker-compose.yml 的端口映射还得 ports 这样的标签

expose:

- "3000"

- "8000"

24. external_links

连接到 docker-compose.yml 外部的容器，甚至并不是Compose 项目文件管理的容器，尤为是对于提供共享或公共服务的容器。参数格式跟过期的 links 相似

在使用Docker过程当中，会有许多单独使用 docker run 启动的容器的状况，为了使 Compose 可以链接这些不在docker-compose.yml 配置文件中定义的容器，那么就须要一个特殊的标签，就是 external_links，它可让Compose 项目里面的容器链接到那些项目配置外部的容器（前提是外部容器中必须至少有一个容器是链接到与项目内的服务的同一个网络里面，链接到同一网络上的各个容器才可以相互通讯）。

格式以下：

external_links:

- redis_1

- project_db_1:mysql

- project_db_1:postgresql

注意：在群集模式下使用（版本3）Compose文件部署堆栈时，将忽略此选项

25. extra_hosts

添加主机名的标签，就是往 /etc/hosts 文件中添加一些记录，与Docker客户端中的--add-host相似：

extra_hosts:

- "somehost:162.242.195.82"

- "otherhost:50.31.209.229"

具备 IP 地址和主机名的条目在 /etc/hosts 内部容器中建立。启动以后查看容器内部 hosts ，例如：

162.242.195.82 somehost

50.31.209.229 otherhost

26.healthcheck

2.1版本及以上

用于检查测试服务使用的容器是否正常

healthcheck:

test: ["CMD", "curl", "-f", "http://localhost"]

interval: 1m30s

timeout: 10s

retries: 3

start_period: 40s

interval，timeout 以及 start_period 都定为持续时间

注意：start_period仅支持v3.4及更高版本

test 必须是字符串或列表，若是它是一个列表，第一项必须是 NONE，CMD 或 CMD-SHELL ；若是它是一个字符串，则至关于指定CMD-SHELL 后跟该字符串。

# Hit the local web app

test: ["CMD", "curl", "-f", "http://localhost"]

# As above, but wrapped in /bin/sh. Both forms below are equivalent.

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

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

若是须要禁用镜像的全部检查项目，可使用 disable: true，至关于 test:["NONE"]

healthcheck:

disable: true

27. image

从指定的镜像中启动容器，能够是存储仓库、标签以及镜像 ID

image: redis

image: ubuntu:14.04

image: tutum/influxdb

image: example-registry.com:4000/postgresql

image: a4bc65fd

若是镜像不存在，Compose 会自动拉去镜像

除非还指定了build，在这种状况下，它使用指定的选项构建，并使用这里指定的镜像名称镜像名称及tag，命名及标记构建的镜像。

28、init

3.7版本中添加

在容器内运行init，转发信号并从新获取进程。设置布尔值以使用默认值init，或指定自定义路径的路径。

version: '3.7'

services:

web:

image: alpine:latest

init: true

version: '2.2'

services:

web:

image: alpine:latest

init: /usr/libexec/docker-init

29. isolation

指定容器的隔离技术。在Linux上，惟一支持的值是default。在Windows中，可接受的值是default，process和hyperv

30. labels

使用 Docker 标签将元数据添加到容器，可使用数组或字典。与 Dockerfile 中的 LABELS 相似：

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"

31.links

警告：

--link是Docker的遗留功能。它最终可能被删除。除非绝对须要继续使用它，不然建议使用用户定义的网络来促进两个容器之间的通讯，而不是使用--link。
当不支持用户定义的网络，可使用--link功能在容器之间共享环境变量。可是，也可以使用其余机制（如卷）以更可控的方式在容器之间共享环境变量

连接到其它服务的中的容器，能够指定服务名称也能够指定连接别名（SERVICE:ALIAS)，或仅指定服务名称（此时别名和服务名称相同）。与Docker客户端的--link效果同样，会链接到其它服务中的容器

web:

links:

- db

- db:database

- redis

使用的别名alias将会自动在服务容器中的/etc/hosts 里建立。例如：

172.12.2.186 db

172.12.2.186 database

172.12.2.187 redis

相应的环境变量也将被建立

32. logging

配置日志服务

logging:

driver: syslog

options:

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

driver指定服务器的日志记录驱动程序，默认值为 json-file，与 --log-diver 选项同样

driver: "json-file"

driver: "syslog"

driver: "none"

注意：只有驱动程序 json-file 和 journald 驱动程序能够直接从 docker-compose up 和 docker-compose logs 获取日志。使用任何其余方式不会显示任何日志。

对于可选值，可使用 options 指定日志记录中的日志记录选项

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.yml 限制日志存储的示例

services:

some-service:

image: some-service

logging:

driver: "json-file"

options:

max-size: "200k"

max-file: "10"

33. network_mode

网络模式，用法相似于 Docke 客户端的 --network选项，及特殊形式service:[service name]

network_mode: "bridge"

network_mode: "host"

network_mode: "none"

network_mode: "service:[service name]" #使用某个服务使用的网络

network_mode: "container:[container name/id]" #使用某个容器使用的网络

能够指定使用服务或者容器的网络

34. networks

要加入的网络，引用顶级networks下的条目

services:

some-service:

networks:

- some-network

- other-network

注意：

在群集模式下使用（版本3）Compose文件部署堆栈时，将忽略此选项。
network_mode: "host"不能与links混在一块儿使用。

35. aliases

网络上此服务的别名。同一网络上的其余容器可使用服务名称或此别名链接到其中一个服务的容器。

由于aliases是网络范围的，所以相同的服务能够在不一样的网络上具备不一样的别名。

注意：网络范围的别名能够由多个容器共享，甚至能够由多个服务共享。

services:

some-service:

networks:

some-network:

aliases:

- alias1

- alias3

other-network:

aliases:

- alias2

下面实例中，提供 web 、worker以及db 服务，有两个网络 new 和 legacy 。

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:

相同的服务能够在不一样的网络能够有不一样的别名

36. ipv4_address、ipv6_address

为服务的容器指定一个静态IP地址

顶级网络部分中的相应网络配置必须具包含每一个静态地址的子网配置的块。若是须要IPv6寻址，则必须设置选项enable_ipv6，而且必须使用版本2.x Compose文件，以下所示。

注意：这些选项目前不适用于群集模式。

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

37. PID

pid: "host"

将 PID 模式设置为主机 PID 模式，能够打开容器与主机操做系统之间的共享 PID 地址空间。使用此标志启动的容器能够访问和操做宿主机的其余容器，反之亦然。

38. ports

映射端口

注意：端口映射与network_mode: host不兼容

1. SHORT 语法

可使用 HOST:CONTAINER 的方式指定端口，也能够指定容器端口（选择临时主机端口），宿主机会随机映射端口

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"

注意：当使用 HOST:CONTAINER 格式来映射端口时，若是使用的容器端口小于 60 可能会获得错误得结果，由于YAML 将会解析 xx:yy 这种数字格式为 base-60值，因此建议采用字符串格式。

2. LONG 语法

LONG 语法支持 SHORT 语法不支持的附加字段

published：公开的端口，即映射到宿主机上的端口
target：容器内的端口
protocol：端口协议（tcp或udp）
mode：host用于在每一个节点上发布主机端口，或ingress用于负载平衡的群集模式端口

ports:

- target: 80

published: 8080

protocol: tcp

mode: host

39. secrets

经过secrets为每一个服务授予相应的访问权限

注意：secret必须已存在或在此堆栈文件的顶级配置中定义secrets，不然堆栈部署将失败

1. SHORT语法

短语法仅指定secret名称。这容许容器访问secret并将其安装在容器内/run/secrets/<secret_name>。源名称和目标安装点都设置为secret名称。

如下示例使用短语法授予redis服务访问my_secret和my_other_secret secret的权限。my_secret的值设置为文件./my_secret.txt的内容，且my_other_secret定义为外部资源，这意味着它已经在Docker中定义，能够经过运行docker secret create命令或经过其余堆栈部署来定义。若是外部secret不存在，则堆栈部署失败并显示secret not found错误

version: "3.1"

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

2.. LONG 语法

长语法提供了在服务的任务容器中如何建立secret的更多粒度。

source：Docker中存在的secret名称。
target：在服务任务容器中须要装载在 /run/secrets/ 中的文件名称，若是未指定，则默认为source。
uid和gid：/run/secrets/在服务的任务容器中拥有该文件的UID或GID。若是未指定，则默认为默认值0。
mode：以八进制表示法将文件装载到服务的任务容器中 /run/secrets/ 的权限。例如，0444 表明可读。Docker 1.13.1中的默认值是0000，可是在较新的版本中为0444。secret不能写，由于它们安装在临时文件系统中，所以若是设置了可写位，则会被忽略。能够设置可执行位

version: "3.1"

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

40. security_opt

为每一个容器覆盖默认的标签。简单说来就是管理所有服务的标签，好比设置所有服务的 user 标签值为 USER

security_opt:

- label:user:USER

- label:role:ROLE

注意：使用（版本3）Compose文件在群集模式下部署堆栈时，将忽略此选项

41. stop_grace_period

在发送 SIGKILL 以前指定 stop_signal ，若是试图中止容器（若是它没有处理 SIGTERM（或指定的任何中止信号）），则须要等待的时间

stop_grace_period: 1s

stop_grace_period: 1m30s

默认状况下，stop 在发送SIGKILL以前等待10秒钟容器退出

42. stop_signal

设置另外一个信号来中止容器。在默认状况下使用的 SIGTERM来中止容器。设置另外一个信号可使用 stop_signal 标签：

stop_signal: SIGUSR1

注意：使用（版本3）Compose文件在群集模式下部署堆栈时，将忽略此选项。

43. sysctls

在容器中设置的内核参数，能够为数组或字典

sysctls:

net.core.somaxconn: 1024

net.ipv4.tcp_syncookies: 0

sysctls:

- net.core.somaxconn=1024

- net.ipv4.tcp_syncookies=0

注意：使用（版本3）Compose文件在群集模式下部署堆栈时，将忽略此选项。

44. ulimits

覆盖容器的默认限制，能够单一地将限制值设为一个整数，也能够将soft/hard 限制指定为映射

ulimits:

nproc: 65535

nofile:

soft: 20000

hard: 40000

注意：使用（版本3）Compose文件在群集模式下部署堆栈时，将忽略此选项。

45. userns_mode

userns_mode: "host"

若是Docker守护程序配置了用户名称空间，则禁用此服务的用户名称空间。

注意：使用（版本3）Compose文件在群集模式下部署堆栈时，将忽略此选项。

46. volumes

注意：顶级卷定义了命名卷，并从每一个服务volumes列表中引用它。取代了早期版本Compose文件中的volumes_from

挂载一个目录或命名卷，能够直接使用 HOST:CONTAINER 这样的格式，或者使用 HOST:CONTAINER:ro 这样的格式，后者对于容器来讲，数据卷是只读的，这样能够有效保护宿主机的文件系统

能够将宿主机路径做为单个服务的定义的一部分进行挂载（即绑定挂载），而无需在顶级volumes中定义它

若是要跨多个服务重用卷，须要在顶级volumes中定义命名卷，将命名卷与服务，群组和堆栈文件一块儿使用。

示例:

version: "3.2"

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:

1、SHORT语法

（可选）指定主机（HOST:CONTAINER）上的路径或访问模式（HOST:CONTAINER:ro）。

能够在主机上安装相对路径，该路径相对于正在使用的Compose配置文件所在目录，相对路径应始终以.或开头..。

volumes:

# Just specify a path and let the Engine create a volume

- /var/lib/mysql

# Specify an absolute path mapping

- /opt/data:/var/lib/mysql

# Path on the host, relative to the Compose file

- ./cache:/tmp/cache

# User-relative path

- ~/configs:/etc/configs/:ro

# Named volume

- datavolume:/var/lib/mysql

2、LONG语法

长格式语法容许配置没法以简短形式表示的其余字段。

type：挂载类型能够为volume，bind或tmpfs
source：mount的源，宿主机上用于绑定挂载的路径，或顶级volumes中定义的卷的名称。不适用于tmpfs挂载。
target：容器中安装卷的路径
read_only：将卷设置为只读
bind：配置其余绑定选项

propagation：用于绑定的propagation模式（volume固定为rprivate，不可更改；bind mount默认为rprivate可更改）

volume：配置其余卷选项

nocopy：用于在建立卷时禁用从容器复制数据

tmpfs：配置其余tmpfs选项

size：tmpfs mount的大小（以字节为单位）

version: "3.2"

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:

注意：长语法是v3.2中的新增功能

47. 用于服务service、群集swarm以及堆栈文件的卷

在使用服务，群集和 docker-stack.yml 文件时，记住支持服务的任务（容器）能够部署在群集中的任何节点上，而且每次更新服务时均可能是不一样的节点。

在不指定源的命名卷的状况下，Docker为支持服务的每一个任务建立一个匿名卷，关联的容器被移除后，匿名卷不会保留。

若是但愿数据持久存在，使用可识别多主机的命名卷和卷驱动程序，以即可以从任何节点访问数据。或对该服务设置约束，以便将其任务部署在具备该卷的节点上。

示例：

Docker Labs 中 votingapp 示例的 docker-stack.yml文件中定义了一个称为 db 的服务，被配置为一个命名卷来保存swarm上的数据，而且仅限于在manager节点上运行。

下面是该文件的部份内容：

version: "3"

services:

db:

image: postgres:9.4

volumes:

- db-data:/var/lib/postgresql/data

networks:

- backend

deploy:

placement:

constraints: [node.role == manager]

48. restart

默认值为 no ，即在任何状况下都不会从新启动容器；当值为 always 时，容器老是从新启动；当值为 on-failure 时， on-failure 若是退出代码指示的故障错误政策，重启容器。

restart: "no"

restart: always

restart: on-failure

restart: unless-stopped

注意：使用（版本3）Compose文件在群集模式下部署堆栈时，将忽略此选项，改用restart_policy

49. 其余选项

关于标签： domainname、hostname、ipc、mac_address、privileged、read_only、shm_size、stdin_open、tty、user、working_dir

上面这些都是一个单值的标签，相似于使用docker run的效果

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

50、指定持续时间Specifying durations

某些配置选项（例如interval和timeout子选项check）接受持续时间做为字符串，格式以下所示：

2.5s

10s

1m30s

2h32m

5h34m56s

支持的单位有 us、ms、s、m 以及 h

51. 指定字节值Specifying byte values

某些配置选项接受字节值做为字符串，格式以下所示：

1024kb

2048k

300m

1gb

支持的单位是 b，k，m 以及 g，或 kb， mb 和 gb。目前不支持十进制值

52、卷配置参考Volume configuration reference

虽然能够在文件上声明卷做为服务声明的一部分，但这里容许建立可在多个服务中重用的命名卷（不依赖于volumes_from），而且可使用docker命令行轻松检索和检查API。

如下是双服务设置的示例，其中数据库的数据目录与另外一个服务共享卷，以即可以按期备份：

version: "3"

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下的条目能够为空，在这种状况下，它使用引擎配置的默认驱动程序（在大多数状况是local驱动程序）。（可选）可使用如下选项进行配置：

driver

为此卷指定应使用哪一个卷驱动程序。默认为Docker Engine配置使用的任何驱动程序，在大多数状况下是local。若是驱动程序不可用，则在docker-compose up尝试建立卷时Engine会返回错误。

driver: foobar

driver_opts

将选项列表指定为键值对，以传递给此卷的驱动程序。这些选项取决于驱动程序，可选。

driver_opts:

foo: "bar"

baz: 1

external

若是设置为true，则指定在Compose以外建立此卷。docker-compose up不会尝试建立它，若是它不存在则引起错误。

external不能与其余卷配置项（driver，driver_opts）一块儿使用

在下面的示例中，不会尝试建立名为[projectname]_data的卷，Compose查找名为data的卷，并将其挂载到db服务的容器中。

version: '2'

services:

db:

image: postgres

volumes:

- data:/var/lib/postgresql/data

volumes:

data:

external: true

不支持在3.4版本中使用external.name，可以使用name代替。

还能够在Compose文件中与用于引用它的名称分别指定卷的名称：

volumes:

data:

external:

始终使用docker stack deploy建立外部卷

若是使用docker stack deploy以swarm群集模式启动应用程序（而不是docker compose up），则会建立不存在的外部卷。在群集模式下，当服务定义卷时，会自动建立卷。因为服务任务是在新节点上调度的，所以swarmkit会在本地节点上建立卷。

labels

使用Docker标签向容器添加元数据。可以使用数组或字典。

建议使用反向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.4'

volumes:

data:

也可与external属性结合使用：

version: '3.4'

volumes:

data:

external: true

53、网络配置参考Network configuration reference

顶级networks选项容许指定要建立的网络。

driver

为此网络指定应该使用哪一个驱动程序。

默认驱动程序取决于正在使用的Docker Engine的配置方式，但在大多数状况下，为位于独立容器上的bridge和位于Swarm上的overlay。

若是驱动程序不可用，Docker引擎会返回错误。

driver: overlay

bridge

Docker默认使用bridge独立独立容器上的网络。

overlay

overlay驱动程序建立一个跨多个节点命名的网络群。

host或 none

使用主机的网络堆栈，或不使用网络。至关于docker run --network=host或docker run --network=none。仅在使用docker stack命令时使用。若是使用docker-compose命令，改用network_mode。

使用内置的网络， host和none语法略有不一样。使用名称host或none（Docker已自动建立）和Compose可使用的别名（hostnet或nonet在这些示例中）定义外部网络，而后使用别名授予对该网络的服务访问权限。

services:

web:

...

networks:

hostnet: {}

networks:

hostnet:

external: true

services:

web:

...

networks:

nonet: {}

networks:

nonet:

external: true

driver_opts

将选项列表指定为键值对，以传递给此网络的驱动程序。这些选项取决于驱动程序，可选。

driver_opts:

foo: "bar"

baz: 1

attachable

注意：仅支持v3.2及更高版本。

仅在driver设置为overlay时使用。若是设置为true，则除swarm服务外，独立容器能够附加到此网络。若是独立容器链接到覆盖网络，它能够与也从其余Docker守护程序链接到overlay网络的服务和独立容器进行通讯。

networks:

mynet1:

driver: overlay

attachable: true

enable_ipv6

在此网络上启用IPv6网络。

版本3不支持

enable_ipv6要求使用版本2 的Compose文件，由于Swarm模式下尚不支持此指令。

ipam

指定自定义IPAM配置。这是一个具备多个属性的对象，每一个属性都是可选的：

driver：自定义IPAM驱动程序，而不是默认值。
config：包含零个或多个配置块的列表，每一个配置块包含如下任意选项：

subnet：CIDR格式的子网，表示网段

一个完整的例子：

ipam:

driver: default

config:

- subnet: 172.28.0.0/16

注意：其余IPAM配置，例如，gateway仅适用于版本2。

internal

默认状况下，Docker还将桥接网络链接到它以提供外部链接。若是要建立外部隔离的overlay，能够将此选项设置为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以外建立的网络。docker-compose up不会尝试建立它，若是它不存在则引起错误。

external能够不与其它网络配置选项（结合使用driver，driver_opts，ipam，internal）混用

在下面的示例中，proxy是通往外部世界的网关。而不是尝试建立一个名为[projectname]_outside的网络，Compose寻找一个简单调用的现有网络outside，并将proxy服务的容器链接到它。

version: '2'

services:

proxy:

build: ./proxy

networks:

- outside

- default

app:

build: ./app

networks:

- default

networks:

outside:

external: true

不支持在版本3.5中使用external.name，可以使用name。

还能够在Compose文件中与用于引用它的名称分开指定网络名称：

networks:

outside:

external:

name

在3.5版本中添加

为此网络设置自定义名称

version: '3.5'

networks:

network1:

它也能够与external属性结合使用：

version: '3.5'

networks:

network1:

external: true

54、configs配置参考configs configuration reference

顶级configs声明定义或引用能够授予此堆栈中的服务的configs。配置的来源是file或external。

file：使用指定路径上的文件内容建立configs。
external：若是设置为true，则指定已建立的外部configs。Docker不会尝试建立它，若是它不存在，则会发生config not found错误。
name：Docker中configs对象的名称，3.5版本中引入。

在此示例中，当部署堆栈时，my_first_config被建立（如<stack_name>_my_first_config)，my_second_config已存在于Docker中）。

configs:

my_first_config:

file: ./config_data

my_second_config:

external: true

外部configs的另外一个变体是Docker中的configs名称与服务中存在的名称不一样。

如下示例修改前一个示例以使用调用的外部redis_config

configs:

my_first_config:

file: ./config_data

my_second_config:

external:

仍然须要为堆栈中的每一个服务授予对configs的访问权限。

55、secrets配置参考

顶级secrets声明定义或引用能够授予此堆栈中的服务的secrets。secret的来源是file或external。

file：使用指定路径上的文件内容建立secrets。
external：若是设置为true，则指定已建立的外部secrets。Docker不会尝试建立它，若是它不存在，则会发生secret not found错误。
name：Docker中的secrets对象的名称，3.5版本引入。

在此示例中，当部署堆栈时，my_first_secret被建立（如<stack_name>_my_first_secret)，my_second_secret已存在于Docker中）。

secrets:

my_first_secret:

file: ./secret_data

my_second_secret:

external: true

外部secret的另外一个变体是当Docker中的secrets名称与服务中存在的名称不一样。

如下示例修改前一个示例以使用调用的外部redis_secret。

secrets:

my_first_secret:

file: ./secret_data

my_second_secret:

external:

仍然须要授予对堆栈中每一个服务的secrets的访问权限。

56、变量替换Variable substitution

配置选项能够包含环境变量。Compose使用docker-compose运行的shell环境中的变量值。例如，假设shell包含POSTGRES_VERSION=9.3并提供此配置：

db:

image: "postgres:${POSTGRES_VERSION}"

docker-compose up使用此配置运行时，Compose会在shell中查找环境变量POSTGRES_VERSION并将替换为其值。对于此示例，Compose在运行配置以前解析image为postgres:9.3。

若是未设置环境变量，Compose使用空字符串替换。在上面的示例中，若是POSTGRES_VERSION未设置，则image选项的值为postgres:。

可使用.env文件为环境变量设置默认值（Compose会自动查找），shell环境中设置的值将覆盖.env文件中设置的值。

重要说明：

.env file功能仅在使用docker-compose up命令时才有效，对docker stack deploy不起做用。

支持$VARIABLE和${VARIABLE}两种语法。此外，使用2.1版本时，可使用典型的shell语法提供内联默认值：

${VARIABLE:-default}环境中VARIABLE未设置或为空，变量值设为default
${VARIABLE-default}只有当环境中VARIABLE未设置时，变量值才设置为default

一样，如下语法容许指定必需变量：

${VARIABLE:?err}或为空的错误消息，退出显示errif。
${VARIABLE?err}只有当在环境中变量未设置时，退出显示err。

其余扩展的shell样式功能，例如，${VARIABLE/foo/bar}不支持

当配置须要文字$符号时，可使用$$（双美圆符号），所以$$容许引用不但愿由Compose处理的环境变量。

web:

build: .

command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"

若是忘记并使用了单个美圆符号（$），Compose会将该值解释为环境变量并发出警告：

未设置VAR_NOT_INTERPOLATED_BY_COMPOSE，并替换空字符串。

57、Extension fields

在3.4版本中添加

可使用扩展字段重用配置片断。这些特殊字段能够是任何格式，只要它们位于Compose文件的根目录，而且它们的名称以x-字符序列开头。

注意

从3.7（对于3.x系列）和2.4（对于2.x系列）开始，还容许在services，volumes，networks，configs和secrets定义的根目录中使用扩展字段。

version: '2.1'

x-custom:

items:

- a

- b

options:

max-size: '12m'

Compose会忽略这些字段的内容，但可使用YAML锚点（即&）将它们插入到资源定义中。例如，若是但愿多个服务使用相同的日志记录配置：

logging:

options:

max-size: '12m'

max-file: '5'

driver: json-file

能够按以下方式编写Compose文件：

version: '3.4'

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.4'

x-volumes:

&default-volume

driver: foobar-storage

services:

web:

image: myapp/web:latest

volumes: ["vol1", "vol2", "vol3"]

volumes:

vol1: *default-volume

vol2:

<< : *default-volume

vol3:

<< : *default-volume

driver: default