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

文件配置

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

提示：可以是用 .yml 或 .yaml 作为文件扩展名

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

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

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

配置选项

１.bulid

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

build: /path/to/build/dir

也可以是相对路径，当提供的值是相对路径时，它被解释为相对于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

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

2b

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:

name:
actual-name-of-volume

始终使用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:

name:
my-app-data

也可与external属性结合使用：

version: '3.4'

volumes:

data:

external:
true

name:
my-app-data

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

name: host

services:

web:

...

networks:

nonet: {}

networks:

nonet:

external:
true

name: none

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:
actual-name-of-network

name

在3.5版本中添加

为此网络设置自定义名称

version: '3.5'

networks:

network1:

name:
my-app-net

它也可以与external属性结合使用：

version: '3.5'

networks:

network1:

external:
true

name:
my-app-net

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:

name:
redis_config

仍然需要为堆栈中的每个服务授予对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:

name:
redis_secret

仍然需要授予对堆栈中每个服务的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'

name:
"custom"

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

name:
volume02

vol3:

<< :
*default-volume

driver:
default

name:
volume-local