撰写文件版本 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.819.03.0+
3.718.06.0+
3.618.02.0+
3.517.12.0+
3.417.09.0+
3.317.06.0+
3.217.04.0+
3.11.13.1+
3.01.13.0+
2.417.12.0+
2.317.06.0+
2.21.13.0+
2.11.12.0+
2.01.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 文件本身的结构。定义配置文件中的部分(例如builddeploydepends_onnetworks等)的顶级键与支持它们的选项一起作为子主题列出。这映射到<key>: <option>: <value>Compose 文件的缩进结构。

服务配置参考

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

提示:您可以为此文件使用.yml或扩展名。.yaml他们都工作。

服务定义包含应用于为该服务启动的每个容器的配置,就像将命令行参数传递给 docker run.同样,网络和卷定义类似于 docker network createdocker volume create

与 一样docker run,默认情况下会考虑 Dockerfile 中指定的选项,例如CMDEXPOSEVOLUME、 、ENV,您无需在 中再次指定它们docker-compose.yml

您可以使用类似 Bash 的语法在配置值中使用环境变量 ${VARIABLE}- 有关完整详细信息,请参阅 变量替换

本节包含版本 3 中服务定义支持的所有配置选项的列表。

建造

在构建时应用的配置选项。

build可以指定为包含构建上下文路径的字符串:

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

或者,作为一个对象,其路径在 context下指定,并且可选 Dockerfileargs

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

如果您指定image以及,则 Compose 会使用中指定的和 选项build来命名构建的映像:webapptagimage

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之前指定FROMARG则在 下的构建指令中不可用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_configmy_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>如果未指定则默认为。
  • uidgid:拥有服务任务容器中已安装配置文件的数字 UID 或 GID。0如果未指定,两者都默认在 Linux 上。 Windows 上不支持。
  • mode:在服务的任务容器中安装的文件的权限(以八进制表示法)。例如,0444 代表世界可读。默认为0444.配置无法写入,因为它们安装在临时文件系统中,因此如果设置可写位,它将被忽略。可以设置可执行位。如果您不熟悉 UNIX 文件权限模式,您可能会发现此 权限计算器 很有用。

以下示例将容器内的名称设置为my_configto 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按依赖顺序启动服务。在以下示例中,dbredis均在 之前启动web
  • docker-compose up SERVICE自动包含SERVICE的依赖项。在下面的示例中,docker-compose up web还创建并启动dbredis
  • 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在开始之前不会等待dbredis“准备好” web- 仅直到它们已经开始。如果您需要等待服务准备就绪,请参阅 控制启动顺序 以了解有关此问题的更多信息以及解决该问题的策略。
  • 当使用版本 3 Compose 文件以 swarm 模式部署堆栈时,该depends_on选项将被忽略 。

部署

添加 版本 3文件格式。

指定与服务部署和运行相关的配置。以下子选项仅在使用 docker stack deploy部署到swarm
时生效,并且被和忽略,除了。docker-compose updocker-compose runresources

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.25CPU 时间(始终可用)。

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

以下主题描述了对集群中的服务或容器设置资源限制的可用选项。

正在寻找在非集群模式容器上设置资源的选项?

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

内存不足异常 (OOME)

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

重启策略

配置容器退出时是否以及如何重新启动。取代 restart.

  • conditionnone: 、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: 更新失败怎么办?continuerollback、 或之一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 deploydeploy

提示

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

设备

设备映射列表。使用与--devicedocker 客户端创建选项相同的格式。

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清除映像上的任何默认命令 - 这意味着如果CMDDockerfile 中有指令,它将被忽略。

环境文件

从文件添加环境变量。可以是单个值或列表。

如果您使用 指定了 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

$VARhello

环境

添加环境变量。您可以使用数组或字典。任何布尔值(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遵循与旧选项类似的语义。linksCONTAINER: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

intervaltimeoutstart_period指定为 持续时间

在3.4 版本中添加 文件格式。

start_period选项已添加到文件格式 3.4 中。

test必须是字符串或列表。如果它是一个列表,第一项必须是NONE,CMDCMD-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 上,可接受的值为defaultprocesshyperv。有关详细信息,请参阅 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-driverdocker run 的选项一样( 在此处记录)。

默认值为 json 文件。

driver: "json-file"
driver: "syslog"
driver: "none"

笔记

只有json-file和驱动程序才能直接从和journald获取日志。使用任何其他驱动程序不会打印任何日志。docker-compose updocker-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-size200kB,然后轮换它们。存储的各个日志文件的数量由该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]"

笔记

网络

要加入的网络,引用顶级networkskey下的条目 。

services:
  some-service:
    networks:
     - some-network
     - other-network

别名

该服务在网络上的别名(备用主机名)。同一网络上的其他容器可以使用服务名称或此别名来连接到服务的容器之一。

由于aliases是网络范围的,因此相同的服务在不同的网络上可以有不同的别名。

笔记

网络范围的别名可以由多个容器甚至多个服务共享。如果是,则无法保证该名称到底解析为哪个容器。

一般格式如下所示。

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

在下面的示例中,提供了三个服务(webworkerdb)以及两个网络(newlegacy)。该db服务可以通过主机名dbdatabase网络访问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: 端口协议 (tcpudp)
  • modehost用于在每个节点上发布主机端口,或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_secretmy_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密钥中定义它。

但是,如果您想在多个服务中重用一个卷,请在 顶级volumeskey中定义一个命名卷。将命名卷与 服务、群和堆栈文件一起使用。

版本 3文件格式已更改 。

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

mydata此示例显示服务正在使用的命名卷 ( )web以及为单个服务定义的绑定安装(dbservice 下的第一个路径volumes)。该服务还使用名为( service下的第二个路径)db的命名卷,但使用旧的字符串格式定义它以安装命名卷。命名卷必须列在顶级 键下,如图所示。dbdatadbvolumesvolumes

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,tmpfsnpipe
  • 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 上,并且仅限于在节点上运行。这是该文件的相关片段:dbpostgresmanager

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

指定持续时间

某些配置选项(例如 的intervaltimeout子选项) check接受持续时间作为字符串,格式如下:

2.5s
10s
1m30s
2h32m
5h34m56s

支持的单位为usmss和。mh

指定字节值

某些配置选项(例如shm_size的子选项 build)接受字节值作为字符串,格式如下:

2b
1024kb
2048k
300m
1gb

支持的单位是b, k,mg, 以及它们的替代符号kb, mbgb。目前不支持十进制值。

卷配置参考

虽然可以动态 声明卷作为服务声明的一部分,但本节允许您创建可在多个服务之间重用(不依赖于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 及以上版本不再存在此限制 。driverdriver_optslabels

在下面的示例中, [projectname]_dataCompose 不会尝试创建名为 的卷,而是查找简单名为 的现有卷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键允许您指定要创建的网络。

司机

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

默认驱动程序取决于您使用的 Docker 引擎的配置方式,但在大多数情况下,它位于bridge单个主机和overlaySwarm 上。

如果驱动程序不可用,Docker 引擎将返回错误。

driver: overlay

bridgeDocker 默认在单个主机上使用网络。有关如何使用桥接网络的示例,请参阅有关 桥接网络的 Docker 实验室教程。

覆盖

驱动程序在swarmoverlay中跨多个节点创建一个命名网络 。

主机或无

使用主机的网络堆栈,或者不使用网络。相当于 docker run --net=hostdocker run --net=none。仅当您使用命令时才使用 docker stack。如果您使用该docker-compose命令,请改用 network_mode

如果您想在公共构建上使用特定网络,请network按照第二个 yaml 文件示例中所述进行使用。

使用内置网络(例如host和 )的语法none略有不同。使用名称hostnone(Docker 已自动创建)和 Compose 可以使用的别名(hostnetnonet在以下示例中)定义外部网络,然后使用别名授予服务访问该网络的权限。

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 及以上版本不再存在此限制 。driverdriver_optsipaminternal

在下面的示例中,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声明定义或引用 可以授予此堆栈中的服务的配置。配置的来源是fileexternal

  • file:配置是使用指定路径下的文件内容创建的。
  • external:如果设置为 true,则指定此配置已创建。 Docker 不会尝试创建它,如果它不存在, config not found就会发生错误。
  • name:Docker 中配置对象的名称。该字段可用于引用包含特殊字符的配置。该名称按原样使用,不会堆栈名称限定范围。以 3.5 版本文件格式引入。
  • driverdriver_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声明定义或引用 可以授予该堆栈中的服务的秘密。秘密的来源是fileexternal

  • 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_VERSIONimagepostgres: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}退出并显示一条错误消息,其中包含errif VARIABLE未设置或环境中为空。
  • ${VARIABLE?err}退出并显示一条错误消息,其中包含errif VARIABLE未在环境中设置。

${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

撰写文档