撰写文件版本3参考

预计阅读时间：78分钟

参考和准则

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

撰写和Docker兼容性矩阵

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

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

撰写档案格式 Docker Engine版本
撰写规格 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 releases中所示，但是文件格式版本不一定随每个发行版增加。例如，Compose文件格式3.0最初是在Compose版本1.10.0中引入的，并在随后的版本中逐渐版本化。

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

撰写档案结构和范例

这是Docker for Beginners实验 主题中使用的投票应用程序示例的Compose文件示例，该 主题涉及将应用程序部署到Swarm：


version: "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
        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文件，用于定义 服务， 网络和 卷。撰写文件的默认路径为./docker-compose.yml。

提示：您可以为此文件使用a.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.9"
services:
  webapp:
    build: ./dir

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

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

如果您指定image和build，那么Compose将使用中指定的webapp和可选名称命名构建的图像：tagimage

build: ./dir
image: webapp:tag

这将产生一个名为webapp并标记为的图像，该图像tag是从构建的./dir。

使用docker stack deploy时的注意事项

在以群集模式部署堆栈build时，将忽略该选项。 该docker stack命令不会在部署之前生成映像。

语境

包含Dockerfile的目录的路径，或git存储库的URL。

当提供的值是相对路径时，它将被解释为相对于Compose文件的位置。该目录还是发送到Docker守护程序的构建上下文。

Compose用生成的名称构建并标记它，然后使用该图像。

build:
  context: ./dir

码头工人文件

备用Dockerfile。

Compose使用一个替代文件进行构建。还必须指定一个构建路径。

build:
  context: .
  dockerfile: Dockerfile-alternate

args

添加构建参数，它们是只能在构建过程中访问的环境变量。

首先，在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"）必须用引号括起来，这样分析器会将它们解释为字符串。

cache_from

以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_size

以版本3.5的文件格式添加

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

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

目标

以3.4版文件格式添加

建立内定义的指定阶段Dockerfile。有关详细信息，请参见 多阶段构建文档。

build:
  context: .
  target: prod

cap_add，cap_drop

添加或删除容器功能。请参阅man 7 capabilities以获取完整列表。

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

使用docker stack deploy时的注意事项

在群模式下部署堆栈时，cap_add和cap_drop选项将被忽略

cgroup_parent

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

cgroup_parent: m-executor-abcd

使用docker stack deploy时的注意事项

在集群模式下部署堆栈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设置为file的内容./my_config.txt，并 my_other_config定义为外部资源，这意味着它已经在Docker中定义，可以通过运行docker config create 命令或通过其他堆栈部署进行定义。如果外部配置不存在，则堆栈部署失败并显示config not found错误。

以版本3.3文件格式添加。

config 仅在撰写文件格式的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

长语法

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

  • source：在此配置中定义的配置的标识符。
  • target：要在服务的任务容器中挂载的文件的路径和名称。/<source>如果未指定，则默认为。
  • uid和gid：拥有服务任务容器中已安装的配置文件的数字UID或GID。0如果未指定，则两者默认都在Linux上使用。Windows不支持。
  • mode：服务的任务容器中装入的文件的权限，以八进制表示法。例如，0444 表示世界可读。默认值为0444。由于配置文件已挂载在临时文件系统中，因此它们不可写，因此如果您设置可写位，则会将其忽略。可执行位可以设置。如果您不熟悉UNIX文件权限模式，则可能会发现此 权限计算器 很有用。

下面的示例设置的名称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

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

container_name: my-web-container

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

使用docker stack deploy时的注意事项

在集群模式下部署堆栈container_name时，将忽略该选项

credential_spec

以版本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.9"
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.9"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

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

  • depends_on在启动之前不会等待db并且redis要“准备就绪” web-仅在启动之前。如果您需要等待服务准备就绪，请参阅控制启动顺序以 获取有关此问题的更多信息以及解决该问题的策略。
  • 在以群体模式 3版本的Compose文件部署堆栈depends_on时，将忽略该选项 。

部署

以版本3文件格式添加。

指定与服务的部署和运行有关的配置。这只能部署到时生效群与 泊坞窗堆栈部署，并且被忽略docker-compose up和docker-compose run。

version: "3.9"
services:
  redis:
    image: redis:alpine
    deploy:
      replicas: 6
      placement:
        max_replicas_per_node: 1
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

有几个子选项可用：

端点模式

以版本3.2文件格式添加。

为连接到群集的外部客户端指定服务发现方法。

  • endpoint_mode: vip-Docker为服务分配了虚拟IP（VIP），该虚拟IP充当客户端访问网络上服务的前端。Docker在客户端和服务的可用工作程序节点之间路由请求，而无需客户端知道有多少节点正在参与服务或其IP地址或端口。（这是默认设置。）

  • endpoint_mode: dnsrr-DNS轮询（DNSRR）服务发现不使用单个虚拟IP。Docker设置服务的DNS条目，以便对服务名称的DNS查询返回IP地址列表，并且客户端直接连接到其中之一。在想要使用自己的负载平衡器或混合Windows和Linux应用程序的情况下，DNS轮询很有用。

version: "3.9"

services:
  wordpress:
    image: wordpress
    ports:
      - "8080:80"
    networks:
      - overlay
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: vip

  mysql:
    image: mysql
    volumes:
       - db-data:/var/lib/mysql/data
    networks:
       - overlay
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: dnsrr

volumes:
  db-data:

networks:
  overlay:

的选项endpoint_mode还可以在群集模式CLI命令docker service create上用作标志 。有关所有与群相关的docker命令的快速列表，请参阅 群模式CLI命令。

要了解有关在群集模式下进行服务发现和联网的更多信息，请参阅在群集模式下 配置服务发现 主题。

标签

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

version: "3.9"
services:
  web:
    image: web
    deploy:
      labels:
        com.example.description: "This label will appear on the web service"

要在容器上设置标签，请使用labels之外的键deploy：

version: "3.9"
services:
  web:
    image: web
    labels:
      com.example.description: "This label will appear on all containers for the web service"

模式

任一global（正好一个每群节点容器）或replicated（容器的指定数量）。默认值为replicated。（要了解更多信息，请参阅swarm主题 中的复制服务和全局服务。）

version: "3.9"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    deploy:
      mode: global

放置

指定约束和首选项的位置。有关语法以及约束， 首选项的可用类型以及指定每个节点的最大副本数的完整说明，请参阅docker服务create文档。 

version: "3.9"
services:
  db:
    image: postgres
    deploy:
      placement:
        constraints:
          - "node.role==manager"
          - "engine.labels.operatingsystem==ubuntu 18.04"
        preferences:
          - spread: node.labels.zone

max_replicas_per_node

以3.8版文件格式添加。

如果服务是replicated（默认）服务，请限制 可以在节点上随时运行的副本数。

当请求的任务多于运行节点时，将no suitable node (max replicas per node limit exceed)引发错误 。

version: "3.9"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6
      placement:
        max_replicas_per_node: 1

复制品

如果服务是replicated（默认）服务，请指定在任何给定时间应运行的容器数。

version: "3.9"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6

资源

配置资源约束。

更改了撰写文件版本3

该resources部分取代了旧的资源约束选项 在撰写第3版之前的文件（cpu_shares，cpu_quota，cpuset， mem_limit，memswap_limit，mem_swappiness）。请参阅将版本2.x升级到3.x， 以了解撰写文件格式的版本2和版本3之间的差异。

其中每个都是一个值，类似于其 docker服务create对应项。

在此一般示例中，redis服务被限制为使用不超过50M的内存和0.50可用处理时间（CPU）（单个内核的50％），并且具有保留20M的内存和0.25CPU时间（始终可用）。

version: "3.9"
services:
  redis:
    image: redis:alpine
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
        reservations:
          cpus: '0.25'
          memory: 20M

以下主题描述了可用于设置群中服务或容器的资源约束的可用选项。

寻找用于在非群模式容器上设置资源的选项吗？

此处描述的选项特定于 deploy键和群模式。如果要在非群集部署中设置资源限制，请使用 Compose文件格式版本2 CPU，内存和其他资源选项。如果您还有其他问题，请参阅有关GitHub问题docker / compose / 4513的讨论。

内存不足异常（OOME）

如果您的服务或容器尝试使用的内存超过系统可用的内存，则可能会遇到内存不足异常（OOME），并且内核OOM杀手可能会杀死容器或Docker守护程序。为防止这种情况的发生，请确保您的应用程序在具有足够内存的主机上运行，​​请参阅了解内存不足的风险。

restart_policy

配置是否以及如何在退出容器时重新启动容器。替换 restart。

  • condition：其一none，on-failure或者any（默认值：any）。
  • delay：两次重启尝试之间等待的时间，指定为 持续时间（默认值：5s）。
  • max_attempts：放弃之前尝试重新启动容器的次数（默认值：永不放弃）。如果重新启动未在configure内成功完成 window，则此尝试不会计入配置max_attempts值。例如，如果max_attempts设置为“ 2”，并且第一次尝试重启失败，则可能会尝试两次以上重启。
  • window：决定重新启动是否成功之前要等待的时间，指定为持续时间（默认值：立即决定）。
version: "3.9"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

rollback_config

以3.7版文件格式添加。

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

  • parallelism：一次要回滚的容器数。如果设置为0，则所有容器将同时回滚。
  • delay：每个容器组回滚之间等待的时间（默认为0s）。
  • failure_action：如果回滚失败，该怎么办。其中一个continue或者pause（默认pause）
  • monitor：更新每个任务以监视失败后的持续时间(ns|us|ms|s|m|h)（默认5s）注意：设置为0将使用默认5s。
  • max_failure_ratio：在回滚期间可以容忍的故障率（默认为0）。
  • order：回滚期间的操作顺序。其中一个stop-first（旧任务，开始新的一个前停止），或者start-first（新的任务首先启动，并且正在运行的任务简单地重叠）（默认stop-first）。

update_config

配置应如何更新服务。对于配置滚动更新很有用。

  • parallelism：一次更新的容器数。
  • delay：在更新一组容器之间等待的时间。
  • failure_action：如果更新失败，该怎么办。其中一个continue，rollback或者pause （默认：pause）。
  • monitor：更新每个任务以监视失败后的持续时间(ns|us|ms|s|m|h)（默认5s）注意：设置为0将使用默认5s。
  • max_failure_ratio：更新期间可以容忍的故障率。
  • order：更新期间的操作顺序。其中一个stop-first（旧任务，开始新的一个前停止），或者start-first（新的任务首先启动，并且正在运行的任务简单重叠）（默认stop-first）注：仅支持V3.4及更高版本。

以3.4版文件格式添加。

orderv3.4及更高版本的撰写文件格式仅支持该选项。

version: "3.9"
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

下面的子选项（支持docker-compose up和docker-compose run）是不支持的docker stack deploy或deploy关键的。

小费

请参阅有关如何为服务，群集和docker-stack.yml文件配置卷的部分。卷是受支持的，但是要与群集和服务一起使用，必须将它们配置为命名卷或与约束到有权访问必需卷的节点的服务关联。

设备

设备映射列表。使用与--devicedocker client create选项相同的格式。

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

使用docker stack deploy时的注意事项

在集群模式下部署堆栈devices时，将忽略该选项

域名系统

自定义DNS服务器。可以是单个值或列表。

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

自定义DNS搜索域。可以是单个值或列表。

dns_search