Compose services 字段参考文档

2023-10-18

字数统计: 4.4k字 | 阅读时长≈ 17分

参考文档: Compose file versions and upgrading

Docker Compose 文件是一个 YAML 文件，用于定义 Docker 应用程序的服务，网络和卷。现在，下面的参考文件中描述了 Compose 文件格式。

Compose 文件版本3

下面的主题描述了 Compose 文件格式的版本3。这是最新版本

Compose 版本与 Docker 的兼容性

有多种版本的 Compose 文件格式，1,2,2.x 和 3.x。下表是快速浏览。有关每个版本包括什么以及如何升级的完整详细信息，请参阅关于版本和升级.

下表显示了哪些 Compose 文件版本支持特定的 Docker 版本。

Compose 文件格式	Docker 引擎版本
Compose Specification	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+
1.0	1.9.1+

除了表中显示的 Compose 文件格式版本外，Compose 本身也处于发布计划中，如 Compose 版本中所示，但是文件格式版本不一定会随着每个版本而增加。例如，Compose 文件格式 3.0 最初是在 Compose 版本 1.10 中引入的，并在随后的版本中逐渐版本化。

最新的 Compose 文件格式是由 Compsoe 规范定义，并由 Docker Compose 19.03.0+ 实现。

Compose 文件结构和示例

下面是 Docker for Beginners 实验主题中有关应用程序部署到 swarm 的投票应用程序示例的 Compose 文件示例。

versions: "3.9"
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
        windows: 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 等。并带有支持它们的选项作为子主题列出。这映射到 Compose 文件的缩进结构 <key>: <option>: <value> 。

Compose 文件配置属性参考

下表列出了 Compose 文件中 services 常用的属性配置参考

名称	参数	描述
build		在构建时应用的配置选项。
	context	包含 Dockerfile 的目录的路径，或 git 存储库的 URL
	dockerfile	备用的 Dockerfile
	args	添加构建参数，它们是只能再构建过程中访问的环境变量
	cache_from	使用镜像缓存列表构建，该参数在 3.2 版本后开始支持
	labels	使用 Docker 标签将元数据添加到生成的 images中。该参数在 3.3 版本后开始至此
	network	在构建过程中，配置容器的网络模式，该参数在 3.4 版本后开始支持
	shm_size	设置容器中 `/dev/shm` 分区的大小，该参数在 3.5 版本后开始支持
	target	根据 Dockerfile 中的定义构建指定的阶段。适用于多阶段构建, 该参数在 3.4 版本后开始支持
cap_add,cap_drop		添加或删除容器功能
cgroup_parent		为容器指定一个可选的父 cgroup
command		覆盖容器中默认的启动执行进程
configs		按服务授予对配置的访问权限
	SHORT SYNTAX	短语句方式，该参数在 3.3 版本后开始支持
	LONG SYNTAX	长语句模式，提供了在服务的任务容器中如何创建配置的更多粒度
container_name		指定自定义容器名称，而不是生成的默认名称。
credential_spec		配置托管服务帐户的凭据规范。在 3.3 版本后开始支持
depends_on		定义服务之间的依赖性
deploy		指定服务的部署与运行有关的配置，这仅在通过 docker stack deploy 部署到集群时才生效，而使用 docker-compose up 和 docker-compose run 时会被忽略
	endpoint_mode	为连接到集群的外部客户端指定服务发现方法。值存在 vip（virtual IP）或 dnsrr；在 3.2 版本后开始支持
	labels	指定服务标签。这些标签仅在服务上设置，而不在服务的任何容器上设置。要在容器上设置标签，请在 deploy 外部使用标签键
	mode	global 或者 replicated。默认值为 replicated。
	placement	指定约束和首选项的位置。首选项的可用类型以及指定每个节点的最大副本数。
	max_replicas_per_node	如果 mode 设置为 replicated（默认值），请限制可随时在节点上运行的副本数
	replicas	如果 mode 设置为 replicated（默认值），请指定任何时间应运行的容器数
	resources	配置资源约束，资源部分替换了版本3之前的Compose文件中较旧的资源约束选项（cpu_shares，cpu_quota，cpuset，mem_limit，memswap_limit，mem_swappiness）
	restart_policy	配置是在退出容器时如何重新启动容器。
	rollback_config	配置在更新失败的情况下应该如何回滚服务
	update_config	配置应如何更新服务。对于配置滚动更新很有用
devices		设备映射列表。使用 --device docker client create 选项相同的格式。
dns		自定义 DNS 服务器，可以是单个值或列表
dns_search		自定义 DNS 搜索域，可以是单个值或列表
entrypoint		覆盖默认入口命令
env_file		从文件添加环境变量，可以是单个值或列表
environment		添加环境变量，您可以使用数组或字典。任何布尔值（true，false，yes，no）都需要用引号引起来，以确保YML解析器不会将其转换为True或False。
expose		公开端口而不将其发布到主机上，只有链接的服务才能访问他们。只能指定内部端口
external_links		链接到 docker-compose.yml 之外甚至在 Compose 之外启动的容器，特别是对于提供共享或公共服务的容器。
extra_hosts		添加主机名映射
healthcheck		配置运行检查
image		指定启动容器的镜像
init		在容器内运行一个初始化程序，以转发信号并获取进程。将此选项设置为 true 可以为服务启用此功能，在3.7 版本后开始支持
isolation		指定容器的隔离技术
labels		使用 Docker 标签将元数据添加到容器
links		链接到另一个服务中的容器。官方不建议使用，建议使用 networks 将容器连接到一起
logging		服务的日志记录配置
network_mode		网络模式
networks		要加入的网络
	ALIASES	网络上此服务的别名。同一网络上的其他容器可以使用服务名称或此别名来连接到服务的容器之一
	ipv4_address,ipv6_address	加入网络后为此服务的容器指定一个静态IP地址
pid		设置容器的 pid 模式，当值为 host 时，这将使容器和主机操作系统之间共享PID 地址空间
ports		露出端口
	SHORT SYNTAX	要么指定两个端口(HOST:CONTAINER)，要么仅指定容器端口；
	LONG SYNTAX	长格式语法允许配置其他不能以短格式表示的字段，比如端口协议，模式等。在3.2版本后开始支持
restart		重启策略，no 是默认的重启策略，在任何情况下都不会重启启动容器
secrets		按服务授予对机密的访问权限
security_opt		覆盖每个容器的默认标签方案
stop_grace_period		指定在发送 SIGKILL 之前，如果容器无法处理 SIGTERM 时，尝试停止该容器要等待的时间。
stop_signal		设置替代信号以停止容器，默认情况下，stop 使用 SIGTERM
sysctl		在容器中设置内核参数。可以使用数组或者字典
tmpfs		在容器中安装一个临时文件系统
ulimits		覆盖容器的默认 ulimit
userns_mode		如果 Docker 守护程序配置了用户名称空间，则禁用此服务的用户名称空间
volumes		挂载主机路径或命名卷，指定为服务的子选项
domainname,hostname,ipc, mac_address,privileged,read_only, shm_size,stdin_open,tty, user,working_dir		其中每个都是一个值，类似 docker run 对应项，请注意，mac_address 是旧选项。

service 配置参考

Compose 文件是一个 YAML 文件，用于定义服务，网络和卷。Compose 文件的默认路径是 ./docker-compose.yml。

提示：你可以为此文件使用 .yml 或 .yaml 扩展名。

服务定义包含应用于该服务启动的每个容器的配置，就像将命令行参数传递给 docker run 一样。同样，网络和卷定义类似 docker 创建网络和 docker 创建卷。

与 docker run 一样，默认情况下，会使用 Dockerfile 中指定的选项，例如 CMD，EXPOSE，VOLUME，ENV，你无须在 docker-compose.yml 中再次指定它们，你可以使用类似 Bash 的 ${VARIABLE} 语法在配置值中使用环境变量，有关完整详细信息，请参考变量替换.

以下包含版本 3 中的服务定义支持的部分配置选项的详细说明。完整信息请查看官方文档。

build

在构建时应用的配置选项。可以将 build 指定为包含构建上下文路径的字符串：

version: "3.9"
services:
  webapp:
    build: ./dir

或者，作为具有上下文和(可选) Dockerfile 和 args 下指定的路径的对象

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

如果你指定 image 来构建，那么 Compose 会使用 image 中指定的 webapp 和可选标签来命名构建的 image。

1 2	build: ./dir image: webapp:tag

如上，会将 ./dir 作为上下文构建名为 webapp 并且带头 tag 标签的镜像。

CONTEXT: 包含 Dockerfile 的目录路径，或 git 存储库的 URL。当提供的值是相对路径时，它将被解释为相对于 Compose 文件的位置。该目录也是发送到 Docker 守护程序的构建上下文。Compose 用生成的名称构建并标记它，然后使用该镜像。
1
2
build:
context: ./dir
DOCKERFILE: 备用的 Dockerfile，Compose 使用一个替代文件进行构建。还必须制定一个构建路径。
1
2
3
build:
context: .
dockerfile: Dockerfile-alternate
ARGS: 添加构建参数，它们是只能在构建过程中访问的环境变量。

首先，在 Dockerfile 中指定参数：
1
2
3
4
5
ARG buildno
ARG gitcommithash

RUN echo "Build number: $buildno"
RUN echo "Based on cimmit: $gitcommithash"
然后再 build 键下指定参数。你可以传递映射或者列表
1
2
3
4
5
build:
context: .
args:
buildno: 1
gitcommithash: cdc3b19
1
2
3
4
5
build:
context: .
args:
- buildno=1
- gitcommithash=cdc3b19
在你的 Dockerfile中，如果在 FROM 指令之前指定 ARG，则在 FROM 下的构建指令中 ARG 不可用。如果你需要一个参数在两个地方都可用，请在 FROM 指令下指定该参数。

你可以在指定构建参数时忽略该值，在这种情况下，构建时的值就是运行 Compose 的环境中的值。
1
2
3
args:
- buildno
- gitcommithash
YAML 的布尔值（”true”, “false”, “yes”, “no”, “on”, “off”）必须使用引号引起来，以便解释器将它们解释为字符串。

CACHE_FROM: 擎解析使用 images 缓存列表。在 3.2 版本格式中添加；

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

LABELS: 使用 Docker 标签将元数据添加到生成的图像中。你可以使用数组或字典。建议你使用反向 DNS 表示法，以防止标签与其他软件使用的标签冲突。在 3.3 版本格式中添加；

build: .
context: .
labels:
    com.example.description: "Accounting webapp"
    com.example.department: "Finance"
    com.example.label-with-empty-value: ""

build:
context: .
labels:
    - "com.example.description=Accounting webapp"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"

NETWORK: 在构建过程中，设置容器的网络链接给 RUN 指令。在 3.4 版本格式中添加；
1
2
3
build:
context: .
network: host
1
2
3
build:
context: .
network: custom_network_1
在构建过程中可以使用 none 来禁用网络连接
1
2
3
build:
context: .
network: none
SHM_SIZE: 设置此版本容器的 /dev/shm 分区的大小。指定为表示字节数的整数值或表示字节值的字符串。在 3.5 版本格式中添加;
1
2
3
build:
context: .
shm_size: '2gb'
1
2
3
build:
context: .
shm_size: 10000000
TARGET: 根据 Dockerfile 中的定义构建指定的阶段。有关详细信息，请参见多阶段构建文档。在 3.4 版本格式中添加；
1
2
3
build:
context: .
target: prod

cap_add, cap_drop

添加或删除容器功能，有关完整列表，请参见完整列表的[man 7 功能]

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

在 stack 模式下部署 swarm 集群时，将忽略 cap_add 和 cap_drop 选项。

cgroup_parent

为容器指定一个可选的父 cgroup

1	cgroup_parent: m-executor-abcd

在 stack 模式下部署 swarm 集群时，将忽略 cap_add 和 cap_drop 选项。

command

覆盖 Dockerfile 中的默认命令

1	command: bundle exec thin -p 3000

该命令也可以是是列表，类似 Dockerfile

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

configs

使用服务配置，按服务授予对配置的访问权限。支持两种不同的语法变体。注意，该配置必须已经存在或已在此 stack 文件的顶级配置中定义，否则 stack 部署失败。更多信息查看 configs

SHORT SYNTAX: 简短的语法变体仅指定配置名称。这将授予容器对配置的访问权限，并将其安装在容器内的 /<config_name> 上。在 3.3 版本格式中添加

version: "3.9"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

LONG SYNTAX: 长语法提供了在服务的任务容器中如何创建配置的更多粒度。
- source: Docker 中存在的配置名称;
- target: 服务的任务容器中要挂载的文件的路径和名称，如果未指定，则默认为 /<source>;
- uid 和 gid: 服务的任务容器中拥有已挂在的配置文件的数字 UID 或 GID。如果未指定，则两者在 Linux 上均默认为 0。Windows 不支持。
- mode: 服务的任务容器中装入的文件的权限，以八进制表示法，例如，0444 表示所有可读。默认值为 0444。由于配置文件已挂载在临时文件系统中，因此它们不可写，因此，如果设置可写位，则会将其忽略。可执行位可以设置。

以下示例在容器内将 my_config 的名称设置为 redis_config，将模式设置为 0440（组可读），并将用户和组设置为 103。redis 服务无权限访问 my_other_config 配置。

version: "3.9"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - source: my_config
        target: /redis_config
        uid: '103'
        gid: '103'
        mode: 0440
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

你可以授予服务访问多个配置的权限，并且可以混合长短语法。定义配置并不意味着授予对它的服务访问权限。

container_name

指定自定义容器名称，而不是默认生成的名称

1	container_name: my-web-container

由于 Docker 容器名称必须唯一，因此如果你指定了自定义名称，则不能将服务扩展到超过1个容器。尝试这样做会导致错误。

credential_spec

配置托管服务账户的凭据规范。此选项仅用于使用 Windows 容器的服务。凭据规范必须采用 file://<filename> 或者 registry://<value-name> 的格式。

当使用 file: 时，引用的文件必须存在于 Docker 数据目录的 CredentialSpecs 子目录中，在 Windows 上默认为 C:\ProgramData\Docker\。

1	C:\ProgramData\Docker\CredentialSpecs\my-credential-spec.json

以下示例从名为 my-credential-spec.json 文件加载凭据规范

1 2	credential_spec: file: my-credential-spec.json

当使用 registry: 时，将从守护程序主机上的 Windows 注册表中读取凭据规范。具有给定明后才能的注册表值必须位于

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

以下示例从注册表中名为 my-credential-spec 的值中加载凭据规范：

1 2	credential_spec: registry: my-credential-spec

GMSA 配置示例: 在为服务配置 gMSA 凭据规范时，只需要使用 config 指定凭据规范，如下所示：

version: "3.9"
services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json|

depends_on

表达服务之前的依赖性。服务依赖项导致以下行为：

docker-compose up 以依赖关系顺序启动服务。在以下示例中，db 和 redis 在 web 之前启动；
docker-compose up SERVICE 自动包含 SERVICE 的依赖项。在以下示例中，docker-compose up web 还创建并启动 db 和 redis。
docker-compose stop 以依赖关系顺序停止服务。在以下示例中，web 在 db 和 redis 之前停止。

version: "3.9"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

使用 depends_on 时需要注意以下几点：

depends_on 在启动 web 之前不会等待 db 和 redis 处于就绪状态，仅在它们启动之前。如果需要等待服务准备就绪，请参阅控制启动顺序以获取有关此问题的更多信息以解决该问题的策略。
版本 3 不再支持 depends_on 的条件形式；
以 swarm 模式部署 stack 集群时，将忽略 depends_on。