撰写文件版本 3 参考
重要的
Docker 的文档引用并描述了 Compose V2 功能。
自 2023 年 7 月起,Compose V1 停止接收更新,并且不再出现在新的 Docker Desktop 版本中。 Compose V2 已取代它,并且现已集成到所有当前的 Docker Desktop 版本中。有关更多信息,请参阅 迁移到 Compose V2。
参考和指南
这些主题描述了 Compose 文件格式的版本 3。
Compose 和 Docker 兼容性矩阵
Compose 文件格式有多个版本 - 1、2、2.x 和 3.x。下表是一个快速浏览。有关每个版本包含的内容以及如何升级的完整详细信息,请参阅关于版本和升级。
此表显示哪些 Compose 文件版本支持特定的 Docker 版本。
撰写文件格式 | Docker 引擎发布 |
---|---|
撰写规范 | 19.03.0+ |
3.8 | 19.03.0+ |
3.7 | 18.06.0+ |
3.6 | 18.02.0+ |
3.5 | 17.12.0+ |
3.4 | 17.09.0+ |
3.3 | 17.06.0+ |
3.2 | 17.04.0+ |
3.1 | 1.13.1+ |
3.0 | 1.13.0+ |
2.4 | 17.12.0+ |
2.3 | 17.06.0+ |
2.2 | 1.13.0+ |
2.1 | 1.12.0+ |
2.0 | 1.10.0+ |
除了表中显示的 Compose 文件格式版本之外,Compose 本身也在发布计划中,如 Compose 版本中所示,但文件格式版本不一定随每个版本而增加。例如,Compose 文件格式 3.0 首次在 Compose 版本 1.10.0中引入,并在后续版本中逐渐版本化。
最新的 Compose 文件格式由Compose 规范定义 ,并由 Docker Compose 1.27.0+实现。
撰写文件结构和示例
以下是Docker 初学者实验室 主题“ 将应用程序部署到 Swarm”中使用的投票应用程序示例中的示例 Compose 文件 :
version: "3.8"
services:
redis:
image: redis:alpine
ports:
- "6379"
networks:
- frontend
deploy:
replicas: 2
update_config:
parallelism: 2
delay: 10s
restart_policy:
condition: on-failure
db:
image: postgres:9.4
volumes:
- db-data:/var/lib/postgresql/data
networks:
- backend
deploy:
placement:
max_replicas_per_node: 1
constraints:
- "node.role==manager"
vote:
image: dockersamples/examplevotingapp_vote:before
ports:
- "5000:80"
networks:
- frontend
depends_on:
- redis
deploy:
replicas: 2
update_config:
parallelism: 2
restart_policy:
condition: on-failure
result:
image: dockersamples/examplevotingapp_result:before
ports:
- "5001:80"
networks:
- backend
depends_on:
- db
deploy:
replicas: 1
update_config:
parallelism: 2
delay: 10s
restart_policy:
condition: on-failure
worker:
image: dockersamples/examplevotingapp_worker
networks:
- frontend
- backend
deploy:
mode: replicated
replicas: 1
labels: [APP=VOTING]
restart_policy:
condition: on-failure
delay: 10s
max_attempts: 3
window: 120s
placement:
constraints:
- "node.role==manager"
visualizer:
image: dockersamples/visualizer:stable
ports:
- "8080:8080"
stop_grace_period: 1m30s
volumes:
- "/var/run/docker.sock:/var/run/docker.sock"
deploy:
placement:
constraints:
- "node.role==manager"
networks:
frontend:
backend:
volumes:
db-data:
此参考页面上的主题按顶级键的字母顺序组织,以反映 Compose 文件本身的结构。定义配置文件中的部分(例如build
、deploy
、depends_on
、
networks
等)的顶级键与支持它们的选项一起作为子主题列出。这映射到<key>: <option>: <value>
Compose 文件的缩进结构。
服务配置参考
Compose 文件是
定义
服务、
网络和
卷的YAML文件。 Compose 文件的默认路径是../docker-compose.yml
提示:您可以为此文件使用
.yml
或扩展名。.yaml
他们都工作。
服务定义包含应用于为该服务启动的每个容器的配置,就像将命令行参数传递给
docker run
.同样,网络和卷定义类似于
docker network create
和docker volume create
。
与 一样docker run
,默认情况下会考虑 Dockerfile 中指定的选项,例如CMD
、
EXPOSE
、VOLUME
、 、ENV
,您无需在 中再次指定它们docker-compose.yml
。
您可以使用类似 Bash 的语法在配置值中使用环境变量
${VARIABLE}
- 有关完整详细信息,请参阅
变量替换。
本节包含版本 3 中服务定义支持的所有配置选项的列表。
建造
在构建时应用的配置选项。
build
可以指定为包含构建上下文路径的字符串:
version: "3.8"
services:
webapp:
build: ./dir
或者,作为一个对象,其路径在 context下指定,并且可选 Dockerfile和 args:
version: "3.8"
services:
webapp:
build:
context: ./dir
dockerfile: Dockerfile-alternate
args:
buildno: 1
如果您指定image
以及,则 Compose 会使用中指定的和 选项build
来命名构建的映像:webapp
tag
image
build: ./dir
image: webapp:tag
这会产生一个名为webapp
并标记为tag
、由 构建的图像./dir
。
使用docker stack deploy时的注意事项
在 swarm 模式下部署堆栈时,该
build
选项将被忽略 该命令在部署之前不会构建映像。docker stack
语境
包含 Dockerfile 的目录的路径,或 git 存储库的 url。
当提供的值是相对路径时,它将被解释为相对于 Compose 文件的位置。该目录也是发送到 Docker 守护进程的构建上下文。
Compose 构建并使用生成的名称对其进行标记,然后使用该图像。
build:
context: ./dir
docker文件
备用 Dockerfile。
Compose 使用备用文件进行构建。还必须指定构建路径。
build:
context: .
dockerfile: Dockerfile-alternate
参数
添加构建参数,这些参数是仅在构建过程中可访问的环境变量。
首先,在 Dockerfile 中指定参数:
# syntax=docker/dockerfile:1
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
build-args 的范围
在您的 Dockerfile 中,如果您在指令
ARG
之前指定FROM
,ARG
则在 下的构建指令中不可用FROM
。如果您需要在两个地方都提供一个参数,也请在FROM
指令下指定它。有关使用详细信息,请参阅 文档中的了解 ARGS 和 FROM 如何交互部分。
您可以在指定构建参数时省略该值,在这种情况下,其在构建时的值是 Compose 运行环境中的值。
args:
- buildno
- gitcommithash
使用布尔值时的提示
YAML 布尔值 (
"true"
,"false"
,"yes"
,"no"
,"on"
,"off"
) 必须用引号引起来,以便解析器将它们解释为字符串。
缓存来源
3.2版本添加 文件格式
引擎用于缓存解析的图像列表。
build:
context: .
cache_from:
- alpine:latest
- corp/web_app:3.14
标签
3.3版本添加 文件格式
使用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"
网络
3.4版本添加 文件格式
设置网络容器连接以获取RUN
构建期间的说明。
build:
context: .
network: host
build:
context: .
network: custom_network_1
用于none
在构建期间禁用网络:
build:
context: .
network: none
shm_大小
3.5版本添加 文件格式
/dev/shm
设置此构建容器的分区大小。指定为表示字节数的整数值或表示
字节值的字符串。
build:
context: .
shm_size: '2gb'
build:
context: .
shm_size: 10000000
目标
3.4版本添加 文件格式
构建指定阶段,如Dockerfile
.有关详细信息,请参阅
多阶段构建文档。
build:
context: .
target: prod
上限添加、上限删除
添加或删除容器功能。请参阅man 7 capabilities
参考资料 获取完整列表。
cap_add:
- ALL
cap_drop:
- NET_ADMIN
- SYS_ADMIN
cgroup_父级
为容器指定一个可选的父 cgroup。
cgroup_parent: m-executor-abcd
使用docker stack deploy时的注意事项
在 Swarm 模式下部署堆栈时,该
cgroup_parent
选项将被忽略
命令
覆盖默认命令。
command: bundle exec thin -p 3000
该命令也可以是一个列表,其方式类似于 dockerfile:
command: ["bundle", "exec", "thin", "-p", "3000"]
配置
使用每个服务配置授予对每个服务的配置的访问权限configs
。支持两种不同的语法变体。
注意:该配置必须已存在或已 在 此堆栈文件的顶级
configs
配置中定义,否则堆栈部署将失败。
有关配置的更多信息,请参阅 configs。
简短语法
短语法变体仅指定配置名称。这将授予容器对配置的访问权限并将其安装在/<config_name>
容器内。源名称和目标安装点均设置为配置名称。
以下示例使用短语法授予redis
服务对my_config
和my_other_config
配置的访问权限。的值
my_config
设置为文件的内容./my_config.txt
,并被
my_other_config
定义为外部资源,这意味着它已经在 Docker 中通过运行命令docker config create
或通过另一个堆栈部署进行了定义。如果外部配置不存在,堆栈部署将失败并出现错误config not found
。
在3.3 版本中添加 文件格式。
config
仅 3.3 版及更高版本的 compose 文件格式支持定义。
version: "3.8"
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
长语法
长语法提供了如何在服务的任务容器中创建配置的更细粒度。
source
:在此配置中定义的配置标识符。target
:要在服务的任务容器中安装的文件的路径和名称。/<source>
如果未指定则默认为。uid
和gid
:拥有服务任务容器中已安装配置文件的数字 UID 或 GID。0
如果未指定,两者都默认在 Linux 上。 Windows 上不支持。mode
:在服务的任务容器中安装的文件的权限(以八进制表示法)。例如,0444
代表世界可读。默认为0444
.配置无法写入,因为它们安装在临时文件系统中,因此如果设置可写位,它将被忽略。可以设置可执行位。如果您不熟悉 UNIX 文件权限模式,您可能会发现此 权限计算器 很有用。
以下示例将容器内的名称设置为my_config
to redis_config
,将模式设置为0440
(组可读)并将用户和组设置为103
。该redis
服务无权访问my_other_config
配置。
version: "3.8"
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: my-web-container
由于 Docker 容器名称必须是唯一的,因此如果指定了自定义名称,则无法将服务扩展至超过 1 个容器。尝试这样做会导致错误。
使用docker stack deploy时的注意事项
在 Swarm 模式下部署堆栈时,该
container_name
选项将被忽略
凭证规范
在3.3 版本中添加 文件格式。
该
credential_spec
选项是在 v3.3 中添加的。文件格式版本 3.8 或更高版本支持将组托管服务帐户 (gMSA) 配置与撰写文件结合使用。
配置托管服务帐户的凭据规范。此选项仅用于使用 Windows 容器的服务。必须采用或 的credential_spec
格式。file://<filename>
registry://<value-name>
使用 时file:
,引用的文件必须存在于CredentialSpecs
Docker 数据目录的子目录中,C:\ProgramData\Docker\
在 Windows 上默认为该子目录。以下示例从名为 的文件加载凭据规范
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
gMSA 配置示例
为服务配置 gMSA 凭据规范时,只需使用 指定凭据规范config
,如以下示例所示:
version: "3.8"
services:
myservice:
image: myimage:latest
credential_spec:
config: my_credential_spec
configs:
my_credentials_spec:
file: ./my-credential-spec.json|
依赖于取决于
表达服务之间的依赖关系。服务依赖性会导致以下行为:
docker-compose up
按依赖顺序启动服务。在以下示例中,db
和redis
均在 之前启动web
。docker-compose up SERVICE
自动包含SERVICE
的依赖项。在下面的示例中,docker-compose up web
还创建并启动db
和redis
。docker-compose stop
按依赖顺序停止服务。在以下示例中,web
停止在db
和之前redis
。
简单的例子:
version: "3.8"
services:
web:
build: .
depends_on:
- db
- redis
redis:
image: redis
db:
image: postgres
使用时有以下几点需要注意
depends_on
:
depends_on
在开始之前不会等待db
并redis
“准备好”web
- 仅直到它们已经开始。如果您需要等待服务准备就绪,请参阅 控制启动顺序 以了解有关此问题的更多信息以及解决该问题的策略。- 当使用版本 3 Compose 文件以 swarm 模式部署堆栈时,该
depends_on
选项将被忽略 。
部署
添加 版本 3文件格式。
指定与服务部署和运行相关的配置。以下子选项仅在使用
docker stack deploy部署到swarm
时生效,并且被和忽略,除了。docker-compose up
docker-compose run
resources
version: "3.8"
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
有几个子选项可用:
端点模式
在3.2 版本中添加 文件格式。
为连接到 swarm 的外部客户端指定服务发现方法。
endpoint_mode: vip
- Docker 为服务分配一个虚拟 IP (VIP),充当客户端访问网络上的服务的前端。 Docker 在客户端和可用的服务工作节点之间路由请求,而客户端不知道有多少节点参与该服务或其 IP 地址或端口。 (这是默认设置。)endpoint_mode: dnsrr
- DNS 循环 (DNSRR) 服务发现不使用单个虚拟 IP。 Docker 为服务设置 DNS 条目,以便对服务名称的 DNS 查询返回 IP 地址列表,并且客户端直接连接到其中之一。当您想要使用自己的负载均衡器或混合 Windows 和 Linux 应用程序时,DNS 循环非常有用。
version: "3.8"
services:
wordpress:
image: wordpress
ports:
- "8080:80"
networks:
- overlay
deploy:
mode: replicated
replicas: 2
endpoint_mode: vip
mysql:
image: mysql
volumes:
- db-data:/var/lib/mysql/data
networks:
- overlay
deploy:
mode: replicated
replicas: 2
endpoint_mode: dnsrr
volumes:
db-data:
networks:
overlay:
的选项endpoint_mode
也可用作 swarm 模式 CLI 命令
docker service create上的标志。有关所有 Swarm 相关命令的快速列表docker
,请参阅
Swarm 模式 CLI 命令。
要了解有关 Swarm 模式中的服务发现和网络的更多信息,请参阅 在 Swarm 模式中配置服务发现主题。
标签
指定服务的标签。这些标签仅设置在服务上,而不设置在服务的任何容器上。
version: "3.8"
services:
web:
image: web
deploy:
labels:
com.example.description: "This label will appear on the web service"
要在容器上设置标签,请使用labels
之外的键deploy
:
version: "3.8"
services:
web:
image: web
labels:
com.example.description: "This label will appear on all containers for the web service"
模式
global
(每个集群节点只有一个容器)或(replicated
指定数量的容器)。默认为replicated
. (要了解更多信息,请参阅
群主题
中的复制和全局服务。)
version: "3.8"
services:
worker:
image: dockersamples/examplevotingapp_worker
deploy:
mode: global
放置
指定约束和首选项的位置。有关语法和可用的 约束类型、 首选项以及 指定每个节点的最大副本数的完整说明,请参阅 docker 服务创建文档。
version: "3.8"
services:
db:
image: postgres
deploy:
placement:
constraints:
- "node.role==manager"
- "engine.labels.operatingsystem==ubuntu 22.04"
preferences:
- spread: node.labels.zone
每个节点的最大副本数
在3.8 版本中添加 文件格式。
如果服务是replicated
(这是默认的),则
限制
可以在节点上随时运行的副本数量。
当请求的任务多于正在运行的节点时,
no suitable node (max replicas per node limit exceed)
会引发错误。
version: "3.8"
services:
worker:
image: dockersamples/examplevotingapp_worker
networks:
- frontend
- backend
deploy:
mode: replicated
replicas: 6
placement:
max_replicas_per_node: 1
复制品
如果服务是replicated
(这是默认值),请指定在任何给定时间应运行的容器数量。
version: "3.8"
services:
worker:
image: dockersamples/examplevotingapp_worker
networks:
- frontend
- backend
deploy:
mode: replicated
replicas: 6
资源
配置资源限制。
在 compose-file 版本 3 中更改
该
resources
部分替换了 版本 3 之前的 Compose 文件中较旧的资源约束选项cpu_shares
( ,cpu_quota
,cpuset
,mem_limit
,memswap_limit
,mem_swappiness
)。请参阅 将版本 2.x 升级到 3.x 以了解 compose-file 格式版本 2 和 3 之间的差异。
其中每个都是单个值,类似于其 docker service create对应项。
在这个一般示例中,redis
服务被限制为使用不超过 50M 的内存和0.50
(单核的 50%)可用处理时间(CPU),并且保留了20M
内存和0.25
CPU 时间(始终可用)。
version: "3.8"
services:
redis:
image: redis:alpine
deploy:
resources:
limits:
cpus: '0.50'
memory: 50M
reservations:
cpus: '0.25'
memory: 20M
以下主题描述了对集群中的服务或容器设置资源限制的可用选项。
正在寻找在非集群模式容器上设置资源的选项?
此处描述的选项特定于
deploy
key 和 swarm 模式。如果要在非 Swarm 部署上设置资源限制,请使用 Compose 文件格式版本 2 CPU、内存和其他资源选项。如果您还有其他问题,请参阅 GitHub 问题docker/compose/4513上的讨论 。
内存不足异常 (OOME)
如果您的服务或容器尝试使用比系统可用的内存更多的内存,您可能会遇到内存不足异常 (OOME),并且容器或 Docker 守护程序可能会被内核 OOM 杀手杀死。为了防止这种情况发生,请确保您的应用程序在具有足够内存的主机上运行,并参阅 了解内存不足的风险。
重启策略
配置容器退出时是否以及如何重新启动。取代
restart
.
condition
none
: 、on-failure
或之一any
(默认值:any
)。delay
:重新启动尝试之间等待的时间,指定为 持续时间(默认值:5 秒)。max_attempts
:放弃之前尝试重新启动容器的次数(默认值:永不放弃)。如果在配置的时间内重新启动未成功window
,则此尝试不计入配置的max_attempts
值。例如,如果max_attempts
设置为“2”,并且第一次尝试重新启动失败,则可能会尝试两次以上重新启动。window
:在决定重新启动是否成功之前等待多长时间,指定为 持续时间(默认值:立即决定)。
version: "3.8"
services:
redis:
image: redis:alpine
deploy:
restart_policy:
condition: on-failure
delay: 5s
max_attempts: 3
window: 120s
回滚配置
在3.7 版本中添加 文件格式。
配置更新失败时应如何回滚服务。
parallelism
:一次回滚的容器数量。如果设置为 0,则所有容器同时回滚。delay
:每个容器组回滚之间等待的时间(默认0s)。failure_action
: 回滚失败怎么办。continue
或之一pause
(默认pause
)monitor
:每个任务更新后监视失败的持续时间(ns|us|ms|s|m|h)
(默认 5 秒)注意:设置为 0 将使用默认 5 秒。max_failure_ratio
:回滚期间容忍的失败率(默认 0)。order
:回滚时的操作顺序。stop-first
(旧任务在启动新任务之前停止)或start-first
(新任务首先启动,并且正在运行的任务短暂重叠)之一(默认stop-first
)。
更新配置
配置应如何更新服务。对于配置滚动更新很有用。
parallelism
:一次更新的容器数量。delay
:更新一组容器之间等待的时间。failure_action
: 更新失败怎么办?continue
、rollback
、 或之一pause
(默认值:pause
)。monitor
:每个任务更新后监视失败的持续时间(ns|us|ms|s|m|h)
(默认 5 秒)注意:设置为 0 将使用默认 5 秒。max_failure_ratio
:更新期间可容忍的失败率。order
:更新期间的操作顺序。stop-first
(旧任务在启动新任务之前停止)或start-first
(新任务首先启动,并且正在运行的任务短暂重叠)之一(默认stop-first
)注意:仅支持 v3.4 及更高版本。
在3.4 版本中添加 文件格式。
order
仅 v3.4 及更高版本的 compose 文件格式支持该选项。
version: "3.8"
services:
vote:
image: dockersamples/examplevotingapp_vote:before
depends_on:
- redis
deploy:
replicas: 2
update_config:
parallelism: 2
delay: 10s
order: stop-first
不支持 docker stack 部署
或键不支持以下子选项( 和 受docker-compose up
支持docker-compose run
)。docker stack deploy
deploy
提示
请参阅有关如何为服务、群和 docker-stack.yml 文件配置卷的部分 。支持卷,但要与群和服务一起使用,必须将它们配置为命名卷或与仅限有权访问必需卷的节点的服务关联。
设备
设备映射列表。使用与--device
docker 客户端创建选项相同的格式。
devices:
- "/dev/ttyUSB0:/dev/ttyUSB0"
使用docker stack deploy时的注意事项
在 Swarm 模式下部署堆栈时,该
devices
选项将被忽略
域名系统
自定义 DNS 服务器。可以是单个值或列表。
dns: 8.8.8.8
dns:
- 8.8.8.8
- 9.9.9.9
域名解析搜索
自定义 DNS 搜索域。可以是单个值或列表。
dns_search: example.com
dns_search:
- dc1.example.com
- dc2.example.com
入口点
覆盖默认入口点。
entrypoint: /code/entrypoint.sh
入口点也可以是一个列表,其方式类似于 dockerfile:
entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]
笔记
设置
entrypoint
两者都会覆盖使用 Dockerfile 指令在服务映像上设置的任何默认入口点ENTRYPOINT
,并清除映像上的任何默认命令 - 这意味着如果CMD
Dockerfile 中有指令,它将被忽略。
环境文件
从文件添加环境变量。可以是单个值或列表。
如果您使用 指定了 Compose 文件docker-compose -f FILE
,则 中的路径
env_file
是相对于该文件所在目录的路径。
在环境部分 中声明的环境变量 会覆盖这些值——即使这些值是空的或未定义的,这也成立。
env_file: .env
env_file:
- ./common.env
- ./apps/web.env
- /opt/runtime_opts.env
Compose 期望 env 文件中的每一行都采用VAR=VAL
格式。以 开头的行#
被视为注释并被忽略。空行也会被忽略。
# Set Rails/Rack environment
RACK_ENV=development
Compose 还可以识别内联注释,例如:
MY_VAR = value # this is a comment
为了避免将“#”解释为内联注释,请使用引号:
MY_VAR = "All the # inside are taken as part of the value"
笔记
如果您的服务指定了 构建选项,则环境文件中定义的变量在构建过程中不会自动可见。使用 args子选项来
build
定义构建时环境变量。
的值VAL
按原样使用,根本不进行修改。例如,如果该值被引号括起来(shell 变量经常出现这种情况),则引号将包含在传递给 Compose 的值中。
请记住,列表中文件的顺序对于确定分配给多次出现的变量的值非常重要。列表中的文件是从上到下处理的。对于在 file 中指定的相同变量
a.env
并在 file 中分配不同的值b.env
,如果b.env
在下面(后面)列出,则值b.env
保持不变。例如,给出以下声明docker-compose.yml
:
services:
some-service:
env_file:
- a.env
- b.env
以及以下文件:
# a.env
VAR=1
和
# b.env
VAR=hello
$VAR
是hello
。
环境
添加环境变量。您可以使用数组或字典。任何布尔值(true、false、yes、no)都需要用引号引起来,以确保它们不会被 YML 解析器转换为 True 或 False。
仅具有键的环境变量会解析为运行 Compose 的计算机上的值,这对于秘密值或特定于主机的值很有帮助。
environment:
RACK_ENV: development
SHOW: 'true'
SESSION_SECRET:
environment:
- RACK_ENV=development
- SHOW=true
- SESSION_SECRET
笔记
如果您的服务指定了 构建选项,则在构建过程中定义的变量
environment
不会自动可见。使用 args子选项来定义构建时环境变量。build
暴露
公开端口而不将它们发布到主机 - 它们只能由链接的服务访问。只能指定内部端口。
expose:
- "3000"
- "8000"
外部链接
链接到在此docker-compose.yml
之外甚至在 Compose 之外启动的容器,特别是对于提供共享或通用服务的容器。
在指定容器名称和链接别名 ( ) 时,external_links
遵循与旧选项类似的语义。links
CONTAINER:ALIAS
external_links:
- redis_1
- project_db_1:mysql
- project_db_1:postgresql
笔记
使用docker stack deploy时的注意事项
在 Swarm 模式下部署堆栈时,该
external_links
选项将被忽略
额外主机
添加主机名映射。使用与 docker 客户端参数相同的值--add-host
。
extra_hosts:
- "somehost:162.242.195.82"
- "otherhost:50.31.209.229"
/etc/hosts
在内部容器中为此服务创建一个包含 IP 地址和主机名的条目,例如:
162.242.195.82 somehost
50.31.209.229 otherhost
健康检查
配置运行以确定该服务的容器是否“健康”的检查。 有关运行状况检查如何工作的详细信息,请参阅HEALTHCHECK Dockerfile 指令的文档 。
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 1m30s
timeout: 10s
retries: 3
start_period: 2m
interval
,timeout
并start_period
指定为
持续时间。
在3.4 版本中添加 文件格式。
该
start_period
选项已添加到文件格式 3.4 中。
test
必须是字符串或列表。如果它是一个列表,第一项必须是NONE
,CMD
或CMD-SHELL
。如果它是一个字符串,则相当于指定CMD-SHELL
后跟该字符串。
# Hit the local web app
test: ["CMD", "curl", "-f", "http://localhost"]
如上所述,但包裹在/bin/sh
.下面的两种形式是等效的。
test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
test: curl -f https://localhost || exit 1
要禁用映像设置的任何默认运行状况检查,您可以使用disable: true
。这相当于指定test: ["NONE"]
.
healthcheck:
disable: true
图像
指定启动容器的镜像。可以是存储库/标签或部分图像 ID。
image: redis
image: ubuntu:22.04
image: tutum/influxdb
image: example-registry.com:4000/postgresql
image: a4bc65fd
如果图像不存在,Compose 会尝试拉取它,除非您还指定了 build,在这种情况下,它会使用指定的选项构建它并使用指定的标签对其进行标记。
在里面
在3.7 版本中添加 文件格式。
在容器内运行 init 来转发信号并获取进程。将此选项设置为true
可为服务启用此功能。
version: "3.8"
services:
web:
image: alpine:latest
init: true
使用的默认 init 二进制文件是 Tini,并且安装
/usr/libexec/docker-init
在守护程序主机上。您可以通过init-path
配置选项将守护程序配置为使用自定义 init 二进制文件 。
隔离
指定容器的隔离技术。在 Linux 上,唯一支持的值是default
。在 Windows 上,可接受的值为default
、process
和
hyperv
。有关详细信息,请参阅
Docker 引擎文档
。
标签
使用Docker 标签将元数据添加到容器 。您可以使用数组或字典。
建议您使用反向 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"
链接
警告
该
--link
标志是 Docker 的一个遗留功能。它最终可能会被删除。除非您绝对需要继续使用它,否则我们建议您使用 用户定义的网络 来促进两个容器之间的通信,而不是使用--link
.用户定义的网络不支持但您可以使用的一项功能
--link
是在容器之间共享环境变量。但是,您可以使用其他机制(例如卷)以更受控制的方式在容器之间共享环境变量。
链接到另一个服务中的容器。同时指定服务名称和链接别名 ( "SERVICE:ALIAS"
),或者仅指定服务名称。
web:
links:
- "db"
- "db:database"
- "redis"
可以通过与别名相同的主机名或服务名称(如果未指定别名)访问链接服务的容器。
不需要链接即可使服务进行通信 - 默认情况下,任何服务都可以通过该服务的名称访问任何其他服务。 (另请参阅 Networking in Compose 中的链接容器部分。)
链接还以与depends_on相同的方式表达服务之间的依赖关系 ,因此它们决定服务启动的顺序。
笔记
如果您同时定义了 链路 和 网络,则它们之间具有链路的服务必须共享至少一个公共网络才能进行通信。
使用docker stack deploy时的注意事项
在 Swarm 模式下部署堆栈时,该
links
选项将被忽略
记录
服务的日志记录配置。
logging:
driver: syslog
options:
syslog-address: "tcp://192.168.0.42:123"
该driver
名称指定服务容器的日志记录驱动程序,就像--log-driver
docker run 的选项一样(
在此处记录)。
默认值为 json 文件。
driver: "json-file"
driver: "syslog"
driver: "none"
笔记
只有
json-file
和驱动程序才能直接从和journald
获取日志。使用任何其他驱动程序不会打印任何日志。docker-compose up
docker-compose logs
使用 键指定日志记录驱动程序的日志记录选项options
,与--log-opt
的选项一样docker run
。
日志记录选项是键值对。选项示例syslog
:
driver: "syslog"
options:
syslog-address: "tcp://192.168.0.42:123"
默认驱动程序 json-file具有限制存储日志量的选项。为此,请使用键值对来确定最大存储大小和最大文件数:
options:
max-size: "200k"
max-file: "10"
上面显示的示例将存储日志文件,直到它们达到max-size
200kB,然后轮换它们。存储的各个日志文件的数量由该max-file
值指定。当日志增长超过最大限制时,旧的日志文件将被删除以允许存储新日志。
docker-compose.yml
以下是限制日志存储的示例文件:
version: "3.8"
services:
some-service:
image: some-service
logging:
driver: "json-file"
options:
max-size: "200k"
max-file: "10"
可用的日志记录选项取决于您使用的日志记录驱动程序
上面控制日志文件和大小的示例使用特定于 json-file driver 的选项。这些特定选项在其他日志记录驱动程序上不可用。有关受支持的日志记录驱动程序及其选项的完整列表,请参阅 日志记录驱动程序文档。
网络模式
网络模式。使用与 docker 客户端参数相同的值--network
,加上特殊形式service:[service name]
。
network_mode: "bridge"
network_mode: "host"
network_mode: "none"
network_mode: "service:[service name]"
network_mode: "container:[container name/id]"
笔记
- 在集群模式下部署堆栈时,此选项将被忽略 。
network_mode: "host"
不能与链接混合 。
网络
要加入的网络,引用顶级networks
key下的条目
。
services:
some-service:
networks:
- some-network
- other-network
别名
该服务在网络上的别名(备用主机名)。同一网络上的其他容器可以使用服务名称或此别名来连接到服务的容器之一。
由于aliases
是网络范围的,因此相同的服务在不同的网络上可以有不同的别名。
笔记
网络范围的别名可以由多个容器甚至多个服务共享。如果是,则无法保证该名称到底解析为哪个容器。
一般格式如下所示。
services:
some-service:
networks:
some-network:
aliases:
- alias1
- alias3
other-network:
aliases:
- alias2
在下面的示例中,提供了三个服务(web
、worker
和db
)以及两个网络(new
和legacy
)。该db
服务可以通过主机名db
或database
网络访问new
,并且db
可以在网络mysql
上访问legacy
。
version: "3.8"
services:
web:
image: "nginx:alpine"
networks:
- new
worker:
image: "my-worker-image:latest"
networks:
- legacy
db:
image: mysql
networks:
new:
aliases:
- database
legacy:
aliases:
- mysql
networks:
new:
legacy:
ipv4_地址、ipv6_地址
加入网络时为该服务的容器指定静态 IP 地址。
顶级网络部分中的相应网络配置
必须有一个
ipam
包含覆盖每个静态地址的子网配置的块。
如果您想使用 IPv6,则必须首先确保 Docker 守护进程配置为支持 IPv6。有关详细说明,请参阅
启用 IPv6 。然后,您可以通过编辑以下内容来访问 3.x 版本 Compose 文件中的 IPv6 寻址/etc/docker/daemon.json
:
{"ipv6": true, "fixed-cidr-v6": "2001:db8:1::/64"}
然后,重新加载 docker 守护进程并编辑 docker-compose.yml 以在服务下包含以下内容:
sysctls:
- net.ipv6.conf.all.disable_ipv6=0
该 选项仅在2.x 版本的 Compose 文件
enable_ipv6
中可用 。 IPv6 选项当前无法在集群模式下工作。
一个例子:
version: "3.8"
services:
app:
image: nginx:alpine
networks:
app_net:
ipv4_address: 172.16.238.10
ipv6_address: 2001:3984:3989::10
networks:
app_net:
ipam:
driver: default
config:
- subnet: "172.16.238.0/24"
- subnet: "2001:3984:3989::/64"
PID
pid: "host"
将PID模式设置为主机PID模式。这将开启容器和主机操作系统之间共享 PID 地址空间。使用此标志启动的容器可以访问和操作裸机名称空间中的其他容器,反之亦然。
港口
暴露端口。
笔记
端口映射不兼容
network_mode: host
笔记
docker-compose run
忽略,ports
除非您包含--service-ports
.
简短语法
有以下三种选择:
- 指定两个端口 (
HOST:CONTAINER
) - 仅指定容器端口(为主机端口选择临时主机端口)。
- 指定要绑定到 AND 两个端口的主机 IP 地址(默认值为 0.0.0.0,表示所有接口):(
IPADDR:HOSTPORT:CONTAINERPORT
)。如果 HOSTPORT 为空(例如127.0.0.1::80
),则选择绑定到主机上的临时端口。
笔记
以该
HOST:CONTAINER
格式映射端口时,如果使用低于 60 的容器端口,您可能会遇到错误结果,因为 YAML 将该格式中的数字解析xx:yy
为以 60 为基数的值。因此,我们建议始终将端口映射显式指定为字符串。
ports:
- "3000"
- "3000-3005"
- "8000:8000"
- "9090-9091:8080-8081"
- "49100:22"
- "127.0.0.1:8001:8001"
- "127.0.0.1:5000-5010:5000-5010"
- "127.0.0.1::5000"
- "6060:6060/udp"
- "12400-12500:1240"
长语法
长格式语法允许配置无法以短格式表达的附加字段。
target
:容器内的端口published
:公开暴露的端口protocol
: 端口协议 (tcp
或udp
)mode
:host
用于在每个节点上发布主机端口,或ingress
用于要负载平衡的集群模式端口。
ports:
- target: 80
published: 8080
protocol: tcp
mode: host
在3.2 版本中添加 文件格式。
长语法是 v3.2 文件格式中的新语法。
简介
profiles: ["frontend", "debug"]
profiles:
- frontend
- debug
profiles
定义要在其下启用的服务的命名配置文件列表。如果未设置,则该服务始终启用。对于构成核心应用程序的服务,您应该省略,profiles
以便它们始终启动。
有效的配置文件名称遵循正则表达式格式[a-zA-Z0-9][a-zA-Z0-9_.-]+
。
另请参阅将 配置文件与 Compose 结合使用以了解有关配置文件的更多信息。
重新开始
no
是默认的
重启策略,任何情况下都不会重启容器。指定后always
,容器始终重新启动。on-failure
如果退出代码指示失败错误,则策略将重新启动容器。
unless-stopped
始终重新启动容器,除非容器停止(手动或以其他方式)。
restart: "no"
restart: always
restart: on-failure
restart: unless-stopped
使用docker stack deploy时的注意事项
在集群模式下部署堆栈时,该
restart
选项将被忽略 。
秘密
使用每服务secrets
配置按服务授予对机密的访问权限。支持两种不同的语法变体。
使用docker stack deploy时的注意事项
该密钥必须已存在或已 在 compose 文件的顶级
secrets
配置中定义,否则堆栈部署将失败。
有关秘密的更多信息,请参阅 秘密。
简短语法
短语法变体仅指定秘密名称。这将授予容器对机密的访问权限并将其安装在/run/secrets/<secret_name>
容器内。源名称和目标安装点均设置为秘密名称。
以下示例使用短语法授予redis
服务对my_secret
和my_other_secret
密钥的访问权限。的值
my_secret
设置为文件的内容./my_secret.txt
,并被
my_other_secret
定义为外部资源,这意味着它已经在 Docker 中通过运行命令docker secret create
或通过另一个堆栈部署进行了定义。如果外部机密不存在,堆栈部署将失败并出现错误secret not found
。
version: "3.8"
services:
redis:
image: redis:latest
deploy:
replicas: 1
secrets:
- my_secret
- my_other_secret
secrets:
my_secret:
file: ./my_secret.txt
my_other_secret:
external: true
长语法
长语法提供了如何在服务的任务容器中创建机密的更细粒度。
source
:此配置中定义的机密标识符。target
/run/secrets/
:要挂载到服务任务容器中的文件的名称。source
如果未指定则默认为。uid
和:拥有服务任务容器中gid
的文件的数字 UID 或 GID 。如果未指定,/run/secrets/
两者均默认为。0
mode
/run/secrets/
:要在服务的任务容器中安装的文件的权限,以八进制表示法。例如,0444
代表世界可读。 Docker 1.13.1 中的默认值为,但在较新的版本中0000
也是如此 。0444
秘密无法写入,因为它们安装在临时文件系统中,因此如果设置可写位,它将被忽略。可以设置可执行位。如果您不熟悉 UNIX 文件权限模式,您可能会发现此 权限计算器 很有用。
my_secret
以下示例将容器内的名称设置为redis_secret
,将模式设置为0440
(组可读)并将用户和组设置为103
。该redis
服务无权访问该my_other_secret
机密。
version: "3.8"
services:
redis:
image: redis:latest
deploy:
replicas: 1
secrets:
- source: my_secret
target: redis_secret
uid: '103'
gid: '103'
mode: 0440
secrets:
my_secret:
file: ./my_secret.txt
my_other_secret:
external: true
您可以授予服务访问多个机密的权限,并且可以混合使用长语法和短语法。定义秘密并不意味着授予服务访问它的权限。
安全选项
覆盖每个容器的默认标签方案。
security_opt:
- label:user:USER
- label:role:ROLE
使用docker stack deploy时的注意事项
在集群模式下部署堆栈时,该
security_opt
选项将被忽略 。
停止宽限期
stop_signal
指定在发送 SIGKILL 之前尝试停止容器(如果容器不处理 SIGTERM(或使用 指定的任何停止信号))时要等待的时间
。指定为
持续时间。
stop_grace_period: 1s
stop_grace_period: 1m30s
默认情况下,stop
在发送 SIGKILL 之前等待 10 秒让容器退出。
停止信号
设置替代信号来停止容器。默认情况下stop
使用 SIGTERM。使用stop_signal
原因
设置替代信号stop
以发送该信号。
stop_signal: SIGUSR1
系统命令
要在容器中设置的内核参数。您可以使用数组或字典。
sysctls:
net.core.somaxconn: 1024
net.ipv4.tcp_syncookies: 0
sysctls:
- net.core.somaxconn=1024
- net.ipv4.tcp_syncookies=0
您只能使用内核中命名空间的 sysctls。 Docker 不支持在容器内更改 sysctls 并同时修改主机系统。有关支持的 sysctls 的概述,请参阅 运行时配置命名空间内核参数 (sysctls)。
使用docker stack deploy时的注意事项
在 Swarm 模式下部署堆栈时,此选项需要 Docker Engine 19.03 或更高版本 。
临时文件系统
在3.6 版本中添加 文件格式。
在容器内挂载临时文件系统。可以是单个值或列表。
tmpfs: /run
tmpfs:
- /run
- /tmp
使用docker stack deploy时的注意事项
使用(版本 3-3.5)Compose 文件以集群模式部署堆栈时,将忽略此选项 。
在容器内挂载临时文件系统。 Size 参数指定 tmpfs 安装的大小(以字节为单位)。默认无限制。
- type: tmpfs
target: /app
tmpfs:
size: 1000
极限值
覆盖容器的默认 ulimit。您可以将单个限制指定为整数,也可以将软/硬限制指定为映射。
ulimits:
nproc: 65535
nofile:
soft: 20000
hard: 40000
用户模式
userns_mode: "host"
如果 Docker 守护进程配置了用户命名空间,则禁用此服务的用户命名空间。请参阅 dockerd了解更多信息。
使用docker stack deploy时的注意事项
在集群模式下部署堆栈时,该
userns_mode
选项将被忽略 。
卷
挂载主机路径或命名卷,指定为服务的子选项。
您可以将主机路径安装为单个服务定义的一部分,并且无需在顶级volumes
密钥中定义它。
但是,如果您想在多个服务中重用一个卷,请在
顶级volumes
key中定义一个命名卷。将命名卷与
服务、群和堆栈文件一起使用。
版本 3文件格式已更改 。
顶级 卷键定义了一个命名卷并从每个服务的
volumes
列表中引用它。这取代了volumes_from
早期版本的 Compose 文件格式。
mydata
此示例显示服务正在使用的命名卷 ( )web
以及为单个服务定义的绑定安装(db
service
下的第一个路径volumes
)。该服务还使用名为( service下的第二个路径)db
的命名卷,但使用旧的字符串格式定义它以安装命名卷。命名卷必须列在顶级
键下,如图所示。dbdata
db
volumes
volumes
version: "3.8"
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:
笔记
简短语法
短语法使用通用[SOURCE:]TARGET[:MODE]
格式,其中
SOURCE
可以是主机路径或卷名称。TARGET
是安装卷的容器路径。标准模式ro
用于只读和rw
读写(默认)。
您可以在主机上安装相对路径,该路径相对于正在使用的 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
长语法
在3.2 版本中添加 文件格式。
长格式语法允许配置无法以短格式表达的附加字段。
type
: 安装类型volume
,bind
,tmpfs
或npipe
source
:挂载的源、主机上用于绑定挂载的路径或 顶级volumes
键中定义的卷的名称。不适用于 tmpfs 安装。target
:卷挂载的容器中的路径read_only
:将卷设置为只读的标志bind
:配置附加绑定选项propagation
:用于绑定的传播模式
volume
:配置附加音量选项nocopy
:创建卷时禁止从容器复制数据的标志
tmpfs
:配置额外的 tmpfs 选项size
:tmpfs 挂载的大小(以字节为单位)
version: "3.8"
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:
笔记
创建绑定挂载时,使用长语法需要事先创建引用的文件夹。如果文件夹不存在,则使用短语法动态创建该文件夹。 有关更多信息,请参阅 绑定安装文档。
服务、群和堆栈文件的卷
使用docker stack deploy时的注意事项
使用服务、群和
docker-stack.yml
文件时,请记住,支持服务的任务(容器)可以部署在群中的任何节点上,并且每次更新服务时,这可能是不同的节点。
在没有具有指定源的命名卷的情况下,Docker 会为支持服务的每个任务创建一个匿名卷。删除关联的容器后,匿名卷不会保留。
如果您希望数据持久存在,请使用命名卷和支持多主机的卷驱动程序,以便可以从任何节点访问数据。或者,对服务设置约束,以便将其任务部署在存在卷的节点上。
例如,Docker 实验室中的 voteapp 示例docker-stack.yml
的文件
定义了一个运行数据库的
服务。它被配置为命名卷以将数据保存在 swarm 上,并且仅限于在节点上运行。这是该文件的相关片段:db
postgres
manager
version: "3.8"
services:
db:
image: postgres:9.4
volumes:
- db-data:/var/lib/postgresql/data
networks:
- backend
deploy:
placement:
constraints: [node.role == manager]
域名、主机名、ipc、mac_address、特权、只读、shm_size、stdin_open、tty、用户、工作目录
其中每个都是单个值,类似于其
docker run对应项。请注意,这mac_address
是一个遗留选项。
user: postgresql
working_dir: /code
domainname: foo.com
hostname: foo
ipc: host
mac_address: 02:42:ac:11:65:43
privileged: true
read_only: true
shm_size: 64M
stdin_open: true
tty: true
指定持续时间
某些配置选项(例如 的interval
和timeout
子选项)
check
接受持续时间作为字符串,格式如下:
2.5s
10s
1m30s
2h32m
5h34m56s
支持的单位为us
、ms
、s
和。m
h
指定字节值
某些配置选项(例如shm_size
的子选项
build
)接受字节值作为字符串,格式如下:
2b
1024kb
2048k
300m
1gb
支持的单位是b
, k
,m
和g
, 以及它们的替代符号kb
,
mb
和gb
。目前不支持十进制值。
卷配置参考
虽然可以动态
声明卷作为服务声明的一部分,但本节允许您创建可在多个服务之间重用(不依赖于volumes_from
)的命名卷,并且可以使用 docker 命令行或API。
有关更多信息,请参阅
docker volume子命令文档。
以下是双服务设置的示例,其中数据库的数据目录作为卷与另一个服务共享,以便可以定期备份:
version: "3.8"
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
驱动程序)。或者,您可以使用以下键对其进行配置:
司机
指定该卷应使用哪个卷驱动程序。默认为 Docker 引擎配置使用的任何驱动程序,在大多数情况下是
local
.如果驱动程序不可用,引擎在
docker-compose up
尝试创建卷时会返回错误。
driver: foobar
驱动程序选项
将选项列表指定为键值对,以传递给该卷的驱动程序。这些选项取决于驱动程序 - 请参阅驱动程序文档以获取更多信息。选修的。
volumes:
example:
driver_opts:
type: "nfs"
o: "addr=10.40.0.199,nolock,soft,rw"
device: ":/docker/example"
外部的
如果设置为true
,则指定该卷是在 Compose 外部创建的。docker-compose up
不会尝试创建它,如果它不存在,则会引发错误。
对于 3.3 及以下版本的格式,不能与其他卷配置键( 、、
)external
一起使用。3.4 及以上版本不再存在此限制
。driver
driver_opts
labels
在下面的示例中,
[projectname]_data
Compose 不会尝试创建名为 的卷,而是查找简单名为 的现有卷data
并将其挂载到db
服务的容器中。
version: "3.8"
services:
db:
image: postgres
volumes:
- data:/var/lib/postgresql/data
volumes:
data:
external: true
在版本 3.4文件格式中已弃用 。
external.name 在版本 3.4 中已弃用,
name
改为使用文件格式。
您还可以将卷的名称与 Compose 文件中用于引用它的名称分开指定:
volumes:
data:
external:
name: actual-name-of-volume
使用docker stack deploy时的注意事项
如果您使用 docker stack deploy以Swarm 模式(而不是 docker compose up) 启动应用程序,则会创建不存在的外部卷。在 Swarm 模式下,当服务定义卷时,会自动创建卷。当服务任务在新节点上调度时, swarmkit 在本地节点上创建卷。要了解更多信息,请参阅 moby/moby#29976。
标签
使用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"
姓名
在3.4 版本中添加 文件格式。
为此卷设置自定义名称。名称字段可用于引用包含特殊字符的卷。该名称按原样使用,不会与堆栈名称限定范围。
version: "3.8"
volumes:
data:
name: my-app-data
它也可以与属性结合使用external
:
version: "3.8"
volumes:
data:
external: true
name: my-app-data
网络配置参考
顶级networks
键允许您指定要创建的网络。
- 有关 Compose 使用 Docker 网络功能和所有网络驱动程序选项的完整说明,请参阅 网络指南。
- 有关 网络的Docker 实验室教程,请从设计可扩展、可移植的 Docker 容器网络 开始
司机
指定该网络应使用哪个驱动程序。
默认驱动程序取决于您使用的 Docker 引擎的配置方式,但在大多数情况下,它位于bridge
单个主机和overlay
Swarm 上。
如果驱动程序不可用,Docker 引擎将返回错误。
driver: overlay
桥
bridge
Docker 默认在单个主机上使用网络。有关如何使用桥接网络的示例,请参阅有关
桥接网络的 Docker 实验室教程。
覆盖
驱动程序在swarmoverlay
中跨多个节点创建一个命名网络
。
有关如何在集群模式下构建和使用带有服务的网络的工作示例 ,请参阅有关Overlay 网络和服务发现的
overlay
Docker 实验室教程 。要深入了解其底层工作原理,请参阅 Overlay Driver Network Architecture上的网络概念实验室。
主机或无
使用主机的网络堆栈,或者不使用网络。相当于
docker run --net=host
或docker run --net=none
。仅当您使用命令时才使用
docker stack
。如果您使用该docker-compose
命令,请改用
network_mode。
如果您想在公共构建上使用特定网络,请network
按照第二个 yaml 文件示例中所述进行使用。
使用内置网络(例如host
和 )的语法none
略有不同。使用名称host
或none
(Docker 已自动创建)和 Compose 可以使用的别名(hostnet
或nonet
在以下示例中)定义外部网络,然后使用别名授予服务访问该网络的权限。
version: "3.8"
services:
web:
networks:
hostnet: {}
networks:
hostnet:
external: true
name: host
services:
web:
...
build:
...
network: host
context: .
...
services:
web:
...
networks:
nonet: {}
networks:
nonet:
external: true
name: none
驱动程序选项
将选项列表指定为键值对,以传递给该网络的驱动程序。这些选项取决于驱动程序 - 请参阅驱动程序文档以获取更多信息。选修的。
driver_opts:
foo: "bar"
baz: 1
可连接的
在3.2 版本中添加 文件格式。
driver
仅当设置为 时才使用overlay
。如果设置为true
,则除了服务之外,独立容器还可以附加到该网络。如果独立容器连接到覆盖网络,它可以与也从其他 Docker 守护进程连接到覆盖网络的服务和独立容器进行通信。
networks:
mynet1:
driver: overlay
attachable: true
启用ipv6
在此网络上启用 IPv6 网络。
撰写文件版本 3 不支持
enable_ipv6
要求您使用版本 2 Compose 文件,因为 Swarm 模式尚不支持此指令。
伊帕姆
指定自定义 IPAM 配置。这是一个具有多个属性的对象,每个属性都是可选的:
driver
:自定义 IPAM 驱动程序,而不是默认的。config
:包含零个或多个配置块的列表,每个配置块包含以下任意键:subnet
:CIDR格式的子网,表示一个网段
一个完整的例子:
ipam:
driver: default
config:
- subnet: 172.28.0.0/16
笔记
其他 IPAM 配置(例如
gateway
)目前仅适用于版本 2。
内部的
默认情况下,Docker 还会连接一个桥接网络以提供外部连接。如果要创建外部隔离的覆盖网络,可以将此选项设置为true
。
标签
使用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"
外部的
如果设置为true
,则指定该网络是在 Compose 外部创建的。docker-compose up
不会尝试创建它,如果它不存在,则会引发错误。
对于 3.3 及以下版本的格式,不能与其他网络配置键( 、、
、 )external
一起使用。3.4 及以上版本不再存在此限制
。driver
driver_opts
ipam
internal
在下面的示例中,proxy
是通往外部世界的网关。 Compose不会尝试创建一个名为 的网络[projectname]_outside
,而是查找一个简单的名为 的现有网络,并将
服务的容器outside
连接到该网络。proxy
version: "3.8"
services:
proxy:
build: ./proxy
networks:
- outside
- default
app:
build: ./app
networks:
- default
networks:
outside:
external: true
在版本 3.5文件格式中已弃用 。
external.name 在版本 3.5 中已弃用,
name
改为使用文件格式。
您还可以将网络名称与 Compose 文件中用于引用网络的名称分开指定:
version: "3.8"
networks:
outside:
external:
name: actual-name-of-network
姓名
在3.5 版本中添加 文件格式。
为此网络设置自定义名称。名称字段可用于引用包含特殊字符的网络。该名称按原样使用,不会与堆栈名称限定范围。
version: "3.8"
networks:
network1:
name: my-app-net
它也可以与属性结合使用external
:
version: "3.8"
networks:
network1:
external: true
name: my-app-net
configs配置参考
顶级configs
声明定义或引用
可以授予此堆栈中的服务的配置。配置的来源是file
或external
。
file
:配置是使用指定路径下的文件内容创建的。external
:如果设置为 true,则指定此配置已创建。 Docker 不会尝试创建它,如果它不存在,config not found
就会发生错误。name
:Docker 中配置对象的名称。该字段可用于引用包含特殊字符的配置。该名称按原样使用,不会与堆栈名称限定范围。以 3.5 版本文件格式引入。driver
和driver_opts
:自定义秘密驱动程序的名称,以及作为键/值对传递的特定于驱动程序的选项。在 3.8 版本文件格式中引入,仅在使用docker stack
.template_driver
:要使用的模板驱动程序的名称,它控制是否以及如何将秘密有效负载评估为模板。如果未设置驱动程序,则不使用模板。当前唯一支持的驱动程序是golang
,它使用golang
.在 3.8 版本文件格式中引入,仅在使用docker stack
. 有关模板化配置的示例,请参阅 使用模板化配置。
在此示例中,my_first_config
已创建(
<stack_name>_my_first_config)
部署堆栈时,并且my_second_config
已存在于 Docker 中)。
configs:
my_first_config:
file: ./config_data
my_second_config:
external: true
外部配置的另一个变体是 Docker 中的配置名称与服务中存在的名称不同。以下示例修改前一个示例以使用名为 的外部配置
redis_config
。
configs:
my_first_config:
file: ./config_data
my_second_config:
external:
name: redis_config
您仍然需要 向堆栈中的每个服务授予对配置的访问权限。
机密配置参考
顶级secrets
声明定义或引用
可以授予该堆栈中的服务的秘密。秘密的来源是file
或external
。
file
:秘密是使用指定路径下的文件内容创建的。external
:如果设置为 true,则指定此机密已创建。 Docker 不会尝试创建它,如果它不存在,secret not found
就会发生错误。name
:Docker 中秘密对象的名称。该字段可用于引用包含特殊字符的机密。该名称按原样使用,不会与堆栈名称限定范围。以 3.5 版本文件格式引入。template_driver
:要使用的模板驱动程序的名称,它控制是否以及如何将秘密有效负载评估为模板。如果未设置驱动程序,则不使用模板。当前唯一支持的驱动程序是golang
,它使用golang
.在 3.8 版本文件格式中引入,仅在使用docker stack
.
在此示例中,my_first_secret
是
<stack_name>_my_first_secret
在部署堆栈时创建的,并且my_second_secret
已存在于 Docker 中。
secrets:
my_first_secret:
file: ./secret_data
my_second_secret:
external: true
外部机密的另一个变体是 Docker 中的机密名称与服务中存在的名称不同。以下示例修改前一个示例以使用名为 的外部机密
redis_secret
。
撰写文件 v3.5 及以上版本
secrets:
my_first_secret:
file: ./secret_data
my_second_secret:
external: true
name: redis_secret
撰写文件 v3.4 及以下版本
my_second_secret:
external:
name: redis_secret
您仍然需要 向堆栈中的每个服务授予对机密的访问权限。
变量替换
您的配置选项可以包含环境变量。 Compose 使用docker compose
运行时的 shell 环境中的变量值。例如,假设 shell 包含POSTGRES_VERSION=9.3
并且您提供以下配置:
db:
image: "postgres:${POSTGRES_VERSION}"
当您使用此配置运行时,Compose在 shell 中docker compose up
查找
环境变量并替换其值。对于此示例,Compose在运行配置之前将 解析为。POSTGRES_VERSION
image
postgres:9.3
如果未设置环境变量,Compose 将替换为空字符串。在上面的示例中,如果POSTGRES_VERSION
未设置,则该image
选项的值为postgres:
。
.env
您可以使用file设置环境变量的默认值
,Compose 会自动在项目目录(Compose 文件的父文件夹)中查找该文件。 shell 环境中设置的值会覆盖.env
文件中设置的值。
使用docker stack deploy时的注意事项
该
.env file
功能仅在您使用该docker compose up
命令时有效,不适用于docker stack deploy
.
$VARIABLE
和语法均受${VARIABLE}
支持。此外,当使用
2.1 文件格式时,可以使用典型的 shell 语法提供内联默认值:
${VARIABLE:-default}
评估环境中default
是否未设置或为空。VARIABLE
${VARIABLE-default}
default
仅当VARIABLE
环境中未设置时才计算为。
同样,以下语法允许您指定强制变量:
${VARIABLE:?err}
退出并显示一条错误消息,其中包含err
ifVARIABLE
未设置或环境中为空。${VARIABLE?err}
退出并显示一条错误消息,其中包含err
ifVARIABLE
未在环境中设置。
${VARIABLE/foo/bar}
不支持其他扩展的 shell 样式功能,例如。
$$
当您的配置需要文字美元符号时,您可以使用(双美元符号)。这也可以防止 Compose 插入值,因此 a$$
允许您引用您不希望由 Compose 处理的环境变量。
web:
build: .
command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"
如果您忘记并使用单个美元符号 ( $
),Compose 会将该值解释为环境变量并警告您:
The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.
扩展字段
在3.4 版本中添加 文件格式。
可以通过扩展字段重用配置片段。这些特殊字段可以是任何格式,只要它们位于 Compose 文件的根目录并且其名称以x-
字符序列开头即可。
笔记
从 3.7 格式(对于 3.x 系列)和 2.4 格式(对于 2.x 系列)开始,服务、卷、网络、配置和秘密定义的根目录中也允许使用扩展字段。
version: "3.8"
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.8"
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.8"
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