Compose specification

Estimated reading time: 80 minutes

Compose 文件是一个YAML文件,它为 Docker 应用程序定义服务、网络和卷. Compose 文件格式的最新和推荐版本由Compose 规范定义. Compose 规范合并了旧的 2.x 和 3.x 版本,聚合了这些格式的属性,并由Compose 1.27.0+实现.

Status of this document

本文档指定了用于定义多容器应用程序的 Compose 文件格式. 本文档的分发不受限制.

本文档中的关键词"必须"、"不得"、"要求"、"应"、"不应"、"应该"、"不应"、"推荐"、"可以"和"可选"是按照RFC 2119中的描述进行解释.

Requirements and optional attributes

Compose 规范包括旨在针对本地OCI容器运行时的属性,公开 Linux 内核特定的配置选项,还包括一些 Windows 容器特定的属性,以及与集群上的资源放置、复制的应用程序分布和可扩展性相关的云平台功能.

我们承认,没有任何 Compose 实现有望支持所有属性,并且对某些属性的支持取决于平台并且只能在运行时确认. 由设计 Compose 文件格式的docker-compose工具建立的用于控制 Compose 文件中支持的属性的版本化模式的定义并不保证最终用户属性将实际实现.

该规范定义了预期的配置语法和行为,但是 - 除非另有说明 - 支持其中任何一个都是可选的.

使用不受支持的属性解析 Compose 文件的 Compose 实现应该警告用户. 我们建议实现者支持这些运行模式:

  • 默认值:警告用户不支持的属性,但忽略它们
  • 严格:警告用户不支持的属性并拒绝撰写文件
  • 松散:忽略不支持的属性和未知属性(在创建实现时未由规范定义)

The Compose application model

Compose 规范允许定义一个与平台无关的基于容器的应用程序. 这样的应用程序被设计为一组容器,它们必须与足够的共享资源和通信通道一起运行.

应用程序的计算组件被定义为服务. 服务是通过一次或多次运行相同的容器映像(和配置)在平台上实现的抽象概念.

服务通过网络相互通信. 在本规范中,网络是一种平台能力抽象,用于在连接在一起的服务内的容器之间建立 IP 路由. 低级、特定于平台的网络选项被分组到网络定义中,并且可以在某些平台上部分实现.

服务将持久数据存储并共享到Volumes中. 该规范将此类持久性数据描述为具有全局选项的高级文件系统挂载. 实际特定于平台的实现细节被分组到卷定义中,并且可能在某些平台上部分实现.

某些服务需要依赖于运行时或平台的配置数据. 为此,规范定义了一个专用概念: Configs . 从 Service 容器的角度来看,Configs 类似于 Volumes,因为它们是挂载到容器中的文件. 但实际的定义涉及到不同的平台资源和服务,这些资源和服务都是通过这种类型抽象出来的.

秘密是敏感数据的一种特定类型的配置数据,如果没有安全考虑,不应公开这些数据. 秘密作为安装在其容器中的文件提供给服务,但提供敏感数据的特定于平台的资源足够具体,值得在 Compose 规范中使用不同的概念和定义.

Volumes、Configs 和 Secret 之间的区别允许实现在服务级别提供可比较的抽象,但涵盖了充分平台资源的特定配置,以用于明确识别的数据使用.

项目是平台上应用程序规范的单独部署. 项目名称用于将资源组合在一起并将它们与其他应用程序或具有不同参数的相同 Compose 指定应用程序的其他安装隔离. 在平台上创建资源的 Compose 实现必须按项目为资源名称添加前缀,并设置标签com.docker.compose.project .

项目名称可以通过顶级name属性显式设置. Compose 实现必须为用户提供一种设置自定义项目名称并覆盖此名称的方法,这样同一个compose.yaml文件可以在同一个基础设施上部署两次,而无需更改,只需传递一个不同的名称.

Illustrative example

以下示例通过一个具体的示例应用程序说明了 Compose 规范概念. 该示例是非规范性的.

考虑将应用程序拆分为前端 Web 应用程序和后端服务.

The frontend is configured at runtime with an HTTP configuration file managed by infrastructure, providing an external domain name, and an HTTPS server certificate injected by the platform’s secured secret store.

后端将数据存储在持久卷中.

两个服务在隔离的后端网络上相互通信,而前端也连接到前端网络并公开端口 443 以供外部使用.

(External user) --> 443 [frontend network]
                            |
                  +--------------------+
                  |  frontend service  |...ro...<HTTP configuration>
                  |      "webapp"      |...ro...<server certificate> #secured
                  +--------------------+
                            |
                        [backend network]
                            |
                  +--------------------+
                  |  backend service   |  r+w   ___________________
                  |     "database"     |=======( persistent volume )
                  +--------------------+        \_________________/

示例应用程序由以下部分组成:

  • 2 个服务,由 Docker 镜像支持: webappdatabase
  • 1 个密钥(HTTPS 证书),注入前端
  • 1个配置(HTTP),注入前端
  • 1 个持久卷,附加到后端
  • 2 个网络
services:
  frontend:
    image: awesome/webapp
    ports:
      - "443:8043"
    networks:
      - front-tier
      - back-tier
    configs:
      - httpd-config
    secrets:
      - server-certificate

  backend:
    image: awesome/database
    volumes:
      - db-data:/etc/data
    networks:
      - back-tier

volumes:
  db-data:
    driver: flocker
    driver_opts:
      size: "10GiB"

configs:
  httpd-config:
    external: true

secrets:
  server-certificate:
    external: true

networks:
  # The presence of these objects is sufficient to define them
  front-tier: {}
  back-tier: {}

此示例说明了卷、配置和机密之间的区别. 虽然它们都作为挂载的文件或目录暴露给服务容器,但只有一个卷可以配置为读写访问. 秘密和配置是只读的. 卷配置允许您选择卷驱动程序并传递驱动程序选项以根据实际基础架构调整卷管理. Configs 和 Secrets 依赖于平台服务,并且被声明为external ,因为它们不作为应用程序生命周期的一部分进行管理:Compose 实现将使用特定于平台的查找机制来检索运行时值.

Compose file

Compose 文件是一个YAML文件,它定义了version (DEPRECATED)、 services (REQUIRED)、 networksvolumesconfigssecrets . Compose 文件的默认路径是工作目录中的compose.yaml (首选)或compose.yml . Compose 实现还应该支持docker-compose.yamldocker-compose.yml以实现向后兼容性. 如果两个文件都存在,则 Compose 实现必须更喜欢规范的compose.yaml之一.

多个 Compose 文件可以组合在一起来定义应用程序模型. YAML 文件的组合必须通过基于用户设置的 Compose 文件顺序附加/覆盖 YAML 元素来实现. 简单的属性和地图被最高阶的 Compose 文件覆盖,列表通过附加来合并. 每当要合并的免费文件托管在其他文件夹中时,必须根据第一个Compose 文件的父文件夹解析相对路径.

由于某些 Compose 文件元素既可以表示为单个字符串也可以表示为复杂对象,因此合并必须适用于扩展形式.

Profiles

配置文件允许针对各种用途和环境调整 Compose 应用程序模型. Compose 实现应该允许用户定义一组活动配置文件. 确切的机制是特定于实现的,可能包括命令行标志、环境变量等.

Services 顶级元素支持profiles属性来定义命名配置文件的列表. 必须始终启用没有profiles属性集的服务. 当列出的profiles都不匹配活动的配置文件时,Compose 实现必须忽略服务,除非该服务被命令明确定位. 在这种情况下,必须将其profiles添加到活动配置文件集中. 所有其他顶级元素不受profiles的影响并且始终处于活动状态.

对其他服务的引用(通过linksextends或共享资源语法service:xxx )不得自动启用否则会被活动配置文件忽略的组件. 相反,Compose 实现必须返回一个错误.

Illustrative example

services:
  foo:
    image: foo
  bar:
    image: bar
    profiles:
      - test
  baz:
    image: baz
    depends_on:
      - bar
    profiles:
      - test
  zot:
    image: zot
    depends_on:
      - bar
    profiles:
      - debug
  • 在未启用配置文件的情况下解析的 Compose 应用程序模型仅包含foo服务.
  • 如果启用了配置文件test ,则模型包含由test配置文件启用的服务barbaz以及始终启用的服务foo .
  • 如果启用配置文件debug ,模型包含foozot服务,但不包含barbaz ,因此模型对于zotdepends_on约束无效.
  • 如果启用配置文件debugtest ,模型包含所有服务: foobarbazzot .
  • If Compose implementation is executed with bar as explicit service to run, it and the test profile will be active even if test profile is not enabled 由用户.
  • 如果使用baz作为要运行的显式服务执行 Compose 实现,则服务baz和配置文件test将处于活动状态,并且bar将被depends_on约束拉入.
  • 如果使用zot作为要运行的显式服务来执行 Compose 实现,那么对于zotdepends_on约束,模型将再次无效,因为zotbar没有列出公共profiles .
  • 如果使用zot作为要运行的显式服务并启用配置文件test来执行 Compose 实现,则会自动启用配置文件debug ,并将服务bar作为启动服务zotbar的依赖项拉入.

Version top-level element

顶级version属性由规范定义以实现向后兼容性,但仅提供信息.

Compose 实现不应该使用这个版本来选择一个精确的模式来验证 Compose 文件,而是更喜欢它设计时的最新模式.

Compose 实现应该验证它们是否可以完全解析 Compose 文件. 如果某些字段是未知的,通常是因为 Compose 文件是用较新版本的规范定义的字段编写的,Compose 实现应该警告用户. Compose 实现可以提供忽略未知字段的选项(由"松散"模式定义).

Name top-level element

顶级name属性由规范定义为在用户未明确设置时使用的项目名称. Compose 实现必须为用户提供一种覆盖此名称的方法,并且应该定义一种机制来计算默认项目名称,以在未设置顶级name元素时使用.

每当项目名称由顶级name或某些自定义机制定义时,它必须作为COMPOSE_PROJECT_NAME公开用于插值和环境变量解析

services:
  foo:
    image: busybox
    environment:
      - COMPOSE_PROJECT_NAME
    command: echo "I'm running ${COMPOSE_PROJECT_NAME}"

Services top-level element

服务是应用程序中计算资源的抽象定义,可以独立于其他组件进行扩展/替换. 服务由一组容器支持,由平台根据复制要求和放置约束运行. 由容器支持,服务由 Docker 映像和一组运行时参数定义. 服务中的所有容器都是使用这些参数创建的.

Compose 文件必须将services根元素声明为映射,其键是服务名称的字符串表示,其值是服务定义. 服务定义包含应用于为该服务启动的每个容器的配置.

每个服务可能还包括一个构建部分,它定义了如何为服务创建 Docker 镜像. Compose 实现可能支持使用此服务定义构建 docker 镜像. 如果没有实现 Build 部分应该被忽略并且 Compose 文件仍然必须被认为是有效的.

构建支持是 Compose 规范的一个可选方面,在构建支持文档中有详细描述.

每个服务定义运行时约束和要求以运行其容器. deploy部分对这些约束进行分组,并允许平台调整部署策略以最佳匹配容器的需求和可用资源.

部署支持是 Compose 规范的一个可选方面,在部署支持文档中有详细描述. 没有实现 Deploy 部分应该被忽略并且 Compose 文件仍然必须被认为是有效的.

build

build指定用于从源创建容器映像的构建配置,如构建支持文档中所定义.

blkio_config

blkio_config定义了一组配置选项来设置此服务的块 IO 限制.

services:
  foo:
    image: busybox
    blkio_config:
       weight: 300
       weight_device:
         - path: /dev/sda
           weight: 400
       device_read_bps:
         - path: /dev/sdb
           rate: '12mb'
       device_read_iops:
         - path: /dev/sdb
           rate: 120
       device_write_bps:
         - path: /dev/sdb
           rate: '1024k'
       device_write_iops:
         - path: /dev/sdb
           rate: 30

device_read_bps, device_write_bps

为给定设备上的读/写操作设置每秒字节数限制. 列表中的每个项目必须有两个键:

  • path :定义受影响设备的符号路径.
  • rate :可以是表示字节数的整数值,也可以是表示字节值的字符串.

device_read_iops, device_write_iops

为给定设备上的读/写操作设置每秒操作数限制. 列表中的每个项目必须有两个键:

  • path :定义受影响设备的符号路径.
  • rate :作为一个整数值,表示每秒允许的操作数.

weight

修改分配给该服务的带宽相对于其他服务的比例. 采用 10 到 1000 之间的整数值,默认值为 500.

weight_device

按设备微调带宽分配. 列表中的每个项目必须有两个键:

  • path :定义受影响设备的符号路径.
  • weight : 10 到 1000 之间的整数值.

cpu_count

cpu_count定义服务容器的可用 CPU 数量.

cpu_percent

cpu_percent定义可用 CPU 的可用百分比.

cpu_shares

cpu_shares定义(作为整数值)服务容器相对于其他容器的 CPU 权重.

cpu_period

cpu_period允许 Compose 实现在平台基于 Linux 内核时配置 CPU CFS(完全公平调度器)周期.

cpu_quota

当平台基于 Linux 内核时, cpu_quota允许 Compose 实现配置 CPU CFS(完全公平调度器)配额.

cpu_rt_runtime

cpu_rt_runtime为支持实时调度程序的平台配置 CPU 分配参数. 可以是使用微秒作为单位的整数值,也可以是持续时间.

 cpu_rt_runtime: '400ms'
 cpu_rt_runtime: 95000`

cpu_rt_period

cpu_rt_period configures CPU allocation parameters for platform with support for realtime scheduler. Can be either an integer value using microseconds as unit or a duration.

 cpu_rt_period: '1400us'
 cpu_rt_period: 11000`

cpus

已弃用:使用deploy.reservations.cpus

cpus定义分配给服务容器的(可能是虚拟的)CPU 的数量. 这是一个小数. 0.000表示没有限制.

cpuset

cpuset定义了允许执行的显式 CPU. 可以是范围0-3或列表0,1

cap_add

cap_add其他容器功能指定为字符串.

cap_add:
  - ALL

cap_drop

cap_drop指定要作为字符串删除的容器功能.

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup_parent

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

cgroup_parent: m-executor-abcd

command

command会覆盖容器镜像(即 Dockerfile 的CMD )声明的默认命令.

command: bundle exec thin -p 3000

该命令也可以是一个列表,其方式类似于Dockerfile

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

configs

configs使用 per-service configs配置在每个服务的基础上授予对配置的访问权限. 支持两种不同的语法变体.

如果 config 在平台上不存在或未在此 Compose 文件的configs部分中定义,则 Compose 实现必须报告错误.

为配置定义了两种语法. 为了保持符合本规范,实现必须支持这两种语法. 实现必须允许在同一文档中同时使用短句法和长句法.

Short syntax

短语法变体仅指定配置名称. 这将授予容器对配置的访问权限并将其安装在容器内的/<config_name>处. 源名称和目标挂载点都设置为配置名称.

以下示例使用简短语法授予redis服务对my_configmy_other_config配置的访问权限. my_config的值被设置为文件./my_config.txt的内容,而my_other_config被定义为外部资源,这意味着它已经在平台中定义了. 如果外部配置不存在,部署必须失败.

services:
  redis:
    image: redis:latest
    configs:
      - my_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

Long syntax

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

  • source :平台中存在的配置名称.
  • target :要挂载到服务任务容器中的文件的路径和名称. 如果未指定,则默认为/<source> .
  • uidgid :在服务的任务容器中拥有挂载配置文件的数字 UID 或 GID. 未指定时的默认值为 USER 运行容器.
  • mode :挂载在服务的任务容器中的文件的权限,以八进制表示. 默认值是世界可读的( 0444 ). 必须忽略可写位. 可执行位可以设置.

以下示例在容器中将redis_config my_config将模式设置为0440 (组可读)并将用户和组设置为103 . redis服务无权访问my_other_config配置.

services:
  redis:
    image: redis:latest
    configs:
      - source: my_config
        target: /redis_config
        uid: "103"
        gid: "103"
        mode: 0440
configs:
  my_config:
    external: true
  my_other_config:
    external: true

您可以授予服务访问多个配置的权限,并且可以混合使用长语法和短语法.

container_name

container_name是一个字符串,它指定自定义容器名称,而不是生成的默认名称.

container_name: my-web-container

如果 Compose 文件指定了container_name ,则 Compose 实现不得将服务扩展到一个容器之外. 尝试这样做必须导致错误.

如果存在, container_name应该遵循[a-zA-Z0-9][a-zA-Z0-9_.-]+的正则表达式格式

credential_spec

credential_spec为托管服务帐户配置凭据规范.

使用 Windows 容器编写支持服务的实现必须支持 credential_spec 的file:registry:协议. Compose 实现还可以支持自定义用例的附加协议.

credential_spec必须采用file://<filename>registry://<value-name>格式.

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

Example gMSA configuration

为服务配置 gMSA 凭证规范时,您只需使用config指定凭证规范,如下例所示:

services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

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

depends_on

depends_on表示服务之间的启动和关闭依赖关系.

Short syntax

短语法变体仅指定依赖项的服务名称. 服务依赖会导致以下行为:

  • Compose 实现必须按依赖顺序创建服务. 在以下示例中, dbredisweb之前创建.

  • Compose 实现必须按依赖顺序删除服务. 在以下示例中, webdbredis之前被删除.

简单的例子:

services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

Compose 实现必须保证依赖服务在启动依赖服务之前已经启动. Compose 实现可以在启动依赖服务之前等待依赖服务"准备好".

Long syntax

长格式语法允许配置无法以短格式表示的附加字段.

  • condition : 依赖被认为满足的条件
    • service_started :等效于上述短语法
    • service_healthy :指定在启动依赖服务之前依赖项应该是"健康的"(由healthcheck指示).
    • service_completed_successfully :指定依赖项在启动依赖服务之前运行成功完成.

服务依赖会导致以下行为:

  • Compose 实现必须按依赖顺序创建服务. 在以下示例中, dbredisweb之前创建.

  • Compose 实现必须等待运行状况检查传递标有service_healthy的依赖项. 在以下示例中,预计db在创建web之前是"健康的".

  • Compose 实现必须按依赖顺序删除服务. 在以下示例中, webdbredis之前被删除.

简单的例子:

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres

Compose 实现必须保证依赖服务在启动依赖服务之前已经启动. Compose 实现必须保证标有service_healthy的依赖服务在启动依赖服务之前是"健康的".

deploy

deploy指定服务的部署和生命周期的配置,如此处所定义.

device_cgroup_rules

device_cgroup_rules定义了该容器的设备 cgroup 规则列表. 该格式与 Linux 内核在Control Groups Device Whitelist Controller中指定的格式相同.

device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'

devices

devicesHOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS]的形式定义了已创建容器的设备映射列表.

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"

dns

dns定义了要在容器网络接口配置上设置的自定义 DNS 服务器. 可以是单个值或列表.

dns: 8.8.8.8
dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

dns_opt列出要传递给容器的 DNS 解析器的自定义 DNS 选项(Linux 上的/etc/resolv.conf文件).

dns_opt:
  - use-vc
  - no-tld-query

dns定义自定义 DNS 搜索域以在容器网络接口配置上设置. 可以是单个值或列表.

dns_search: example.com
dns_search:
  - dc1.example.com
  - dc2.example.com

domainname

domainname声明用于服务容器的自定义域名. 必须是有效的 RFC 1123 主机名.

entrypoint

entrypoint点覆盖 Docker 映像的默认入口点(即ENTRYPOINT设置的入口点). 当entrypoint点由 Compose 文件配置时,Compose 实现必须清除 Docker 映像上的任何默认命令 - Dockerfile 中的ENTRYPOINTCMD指令. 如果还设置了command ,则将其用作entrypoint点的参数,以替代 Docker 映像的CMD

entrypoint: /code/entrypoint.sh

入口点也可以是一个列表,其方式类似于Dockerfile

entrypoint:
  - php
  - -d
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  - -d
  - memory_limit=-1
  - vendor/bin/phpunit

env_file

env_file根据文件内容将环境变量添加到容器中.

env_file: .env

env_file也可以是一个列表. 列表中的文件必须自上而下处理. 对于两个 env 文件中指定的相同变量,列表中最后一个文件的值必须保持不变.

env_file:
  - ./a.env
  - ./b.env

必须从 Compose 文件的父文件夹解析相对路径. 由于绝对路径会阻止 Compose 文件的可移植性,因此 Compose 实现应该在使用此类路径设置env_file时警告用户.

environment部分中声明的环境变量必须覆盖这些值——即使这些值为空或未定义也是如此.

Env_file format

env 文件中的每一行必须采用VAR[=[VAL]]格式. 必须忽略以#开头的行. 空行也必须被忽略.

VAL的值用作原始字符串,根本没有修改. 如果值被引号包围(这通常是 shell 变量的情况),引号必须包含在传递给由 Compose 实现创建的容器的值中.

VAL可以省略,在这种情况下,变量值是空字符串. =VAL可以省略,在这种情况下,变量是unset .

# Set Rails/Rack environment
RACK_ENV=development
VAR="quoted"

environment

environment定义在容器中设置的环境变量. environment可以使用数组或地图. 任何布尔值; true、false、yes、no,应该用引号括起来,以确保 YAML 解析器不会将它们转换为 True 或 False.

环境变量可以由单个键声明(等号没有值). 在这种情况下,Compose 实现应该依赖一些用户交互来解析值. 如果没有,则该变量未设置并将从服务容器环境中删除.

地图语法:

environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:

数组语法:

environment:
  - RACK_ENV=development
  - SHOW=true
  - USER_INPUT

当为服务设置env_fileenvironment时,由environment设置的值优先.

expose

expose定义 Compose 实现必须从容器公开的端口. 这些端口必须可供链接服务访问,并且不应发布到主机. 只能指定内部容器端口.

expose:
  - "3000"
  - "8000"

extends

在当前文件或另一个文件中扩展另一个服务,可选择覆盖配置. 您可以在任何服务上使用extends以及其他配置键. extends值必须是使用必需service和可选file键定义的映射.

extends:
  file: common.yml
  service: webapp

如果支持 Compose 实现,必须以下列方式extends

  • service将被引用的服务的名称定义为基础,例如webdatabase .
  • file是定义该服务的 Compose 配置文件的位置.

Restrictions

以下限制适用于被引用的服务:

  • 依赖于其他服务的服务不能作为基础. 因此,任何引入对另一个服务的依赖的键都与extends不兼容. 这些键的非详尽列表是: linksvolumes_fromcontainer模式(在ipcpidnetwork_modenet )、 service模式(在ipcpidnetwork_mode )、 depends_on .
  • 服务不能有带extends的循环引用

在所有这些情况下,Compose 实现必须返回错误.

Finding referenced service

file值可以是:

  • 不存在. 这表明正在引用同一 Compose 文件中的另一个服务.
  • 文件路径,可以是:
    • 相对路径. 此路径被认为是相对于主 Compose 文件的位置.
    • 绝对路径.

由 service 表示的service必须存在于标识的引用 Compose 文件中. 如果出现以下情况,Compose 实现必须返回错误:

  • 未找到服务表示的service
  • 未找到由file表示的撰写文件

Merging service definitions

Two service definitions (main one in the current Compose file and referenced one specified by extends) MUST be merged in the following way:

  • 映射:主要服务定义的映射中的键覆盖引用的服务定义的映射中的键. 未覆盖的键按原样包含在内.
  • 序列:项目组合在一起形成一个新的序列. 元素的顺序被保留,引用的项目在前,主要项目在后.
  • 标量:服务定义中的键优先于被引用的键.
Mappings

以下键应被视为映射: build.argsbuild.labelsbuild.extra_hostsdeploy.labelsdeploy.update_configdeploy.rollback_configdeploy.restart_policydeploy.resources.limitsenvironmenthealthchecklabelslogging.optionssysctlsstorage_optextra_hostsulimits .

适用于healthcheck的一个例外是映射不能指定disable: true ,除非引用的映射也指定disable: true . 在这种情况下,Compose 实现必须返回错误.

例如,下面的输入:

services:
  common:
    image: busybox
    environment:
      TZ: utc
      PORT: 80
  cli:
    extends:
      service: common
    environment:
      PORT: 8080

cli服务生成以下配置. 如果使用数组语法,则会产生相同的输出.

environment:
  PORT: 8080
  TZ: utc
image: busybox

blkio_config.device_read_bpsblkio_config.device_read_iopsblkio_config.device_write_bpsblkio_config.device_write_iopsdevicesvolumes下的项目也被视为映射,其中 key 是容器内的目标路径.

例如,下面的输入:

services:
  common:
    image: busybox
    volumes:
      - common-volume:/var/lib/backup/data:rw
  cli:
    extends:
      service: common
    volumes:
      - cli-volume:/var/lib/backup/data:ro

cli服务生成以下配置. 请注意,挂载路径现在指向新卷名并应用了ro标志.

image: busybox
volumes:
- cli-volume:/var/lib/backup/data:ro

如果引用的服务定义包含extends映射,则其下的项目将简单地复制到新的合并定义中. 然后再次启动合并过程,直到没有extends键剩余.

例如,下面的输入:

services:
  base:
    image: busybox
    user: root
  common:
    image: busybox
    extends:
      service: base
  cli:
    extends:
      service: common

cli服务生成以下配置. 在这里, cli服务从common服务中获取user密钥,而后者又从base服务中获取此密钥.

image: busybox
user: root
Sequences

以下键应被视为序列: cap_addcap_dropconfigsdeploy.placement.constraintsdeploy.placement.preferencesdeploy.reservations.generic_resourcesdevice_cgroup_rulesexposeexternal_linksportssecretssecurity_opt . 删除合并产生的任何重复项,以便序列仅包含唯一元素.

例如,下面的输入:

services:
  common:
    image: busybox
    security_opt:
      - label:role:ROLE
  cli:
    extends:
      service: common
    security_opt:
      - label:user:USER

cli服务生成以下配置.

image: busybox
security_opt:
- label:role:ROLE
- label:user:USER

如果使用列表语法,以下键也应被视为序列: dnsdns_searchenv_filetmpfs . 与上面提到的序列字段不同,合并产生的重复项不会被删除.

Scalars

服务定义中的任何其他允许的键都应被视为标量.

external_links将服务容器链接到在此 Compose 应用程序之外管理的服务. external_links定义要使用平台查找机制检索的现有服务的名称. 可以指定SERVICE:ALIAS形式的别名.

external_links:
  - redis
  - database:mysql
  - database:postgresql

extra_hosts

extra_hosts将主机名映射添加到容器网络接口配置(Linux 的/etc/hosts ). 值必须以HOSTNAME:IP的形式为其他主机设置主机名和 IP 地址.

extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"

Compose 实现必须在容器的网络配置中创建与 IP 地址和主机名匹配的条目,这意味着对于 Linux /etc/hosts将获得额外的行:

162.242.195.82  somehost
50.31.209.229   otherhost

group_add

group_add指定容器内的用户必须是其成员的其他组(按名称或编号).

这很有用的一个例子是当多个容器(作为不同的用户运行)需要在共享卷上读取或写入同一个文件时. 该文件可以由所有容器共享的组拥有,并在group_add中指定.

services:
  myservice:
    image: alpine
    group_add:
      - mail

在创建的容器中运行id必须显示用户属于mail组,如果未声明group_add则不会出现这种情况.

healthcheck

healthcheck声明了一个运行检查以确定该服务的容器是否"健康". 这将覆盖服务的 Docker 映像设置的HEALTHCHECK Dockerfile 指令.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s

interval, timeout and start_period are 指定为持续时间.

test定义 Compose 实现将运行以检查容器运行状况的命令. 它可以是字符串或列表. 如果是列表,则第一项必须是NONECMDCMD-SHELL . 如果是字符串,则相当于指定CMD-SHELL后跟该字符串.

# Hit the local web app
test: ["CMD", "curl", "-f", "http://localhost"]

使用CMD-SHELL将使用容器的默认 shell(Linux 的/bin/sh )运行配置为字符串的命令. 以下两种形式是等效的:

test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
test: curl -f https://localhost || exit 1

NONE禁用健康检查,主要用于禁用按图像设置的健康检查. 或者,可以通过设置disable: true来禁用图像设置的健康检查:

healthcheck:
  disable: true

hostname

hostname声明用于服务容器的自定义主机名. 必须是有效的 RFC 1123 主机名.

image

image指定启动容器的图像. 图像必须遵循开放容器规范可寻址图像格式,如[<registry>/][<project>/]<image>[:<tag>|@<digest>] .

    image: redis
    image: redis:5
    image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
    image: library/redis
    image: docker.io/library/redis
    image: my_private.registry:5000/redis

如果平台上不存在图像,Compose 实现必须尝试根据pull_policy拉取它. 具有构建支持的 Compose 实现可以为最终用户提供替代选项,以控制从源构建图像的拉取优先级,但是拉取图像必须是默认行为.

只要声明了build部分,就可以从 Compose 文件中省略image . 当 Compose 文件中缺少image时,没有构建支持的 Compose 实现必须失败.

init

init在容器内运行一个 init 进程 (PID 1),用于转发信号和获取进程. 将此选项设置为true可为服务启用此功能.

services:
  web:
    image: alpine:latest
    init: true

使用的 init 二进制文件是特定于平台的.

ipc

ipc配置服务容器设置的 IPC 隔离模式. 可用值是特定于平台的,但 Compose 规范定义了特定值,如果支持,则必须按照描述实现:

  • shareable的,它为容器提供了自己的私有 IPC 命名空间,并且可以与其他容器共享它.
  • service:{name}使容器加入另一个( shareable )容器的 IPC 命名空间.
    ipc: "shareable"
    ipc: "service:[service name]"

isolation

isolation指定容器的隔离技术. 支持的值是特定于平台的.

labels

labels将元数据添加到容器中. 您可以使用数组或地图.

建议您使用反向 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"

Compose 实现必须创建带有规范标签的容器:

  • com.docker.compose.project将所有由 Compose 实现创建的资源设置为用户项目名称
  • com.docker.compose.service在服务容器上设置,服务名称在 Compose 文件中定义

com.docker.compose标签前缀是保留的. 在 Compose 文件中使用此前缀指定标签必须导致运行时错误.

links定义到另一个服务中的容器的网络链接. 要么指定服务名称和链接别名 ( SERVICE:ALIAS ),要么只指定服务名称.

web:
  links:
    - db
    - db:database
    - redis

链接服务的容器必须可以通过与别名相同的主机名访问,或者如果没有指定别名,则可以使用服务名.

启用服务进行通信不需要链接 - 当没有设置特定的网络配置时,任何服务必须能够在default网络上以该服务的名称访问任何其他服务. 如果服务确实声明了它们所连接的网络,则links不应该覆盖网络配置,并且未连接到共享网络的服务不应该能够通信. Compose 实现可能不会警告用户此配置不匹配.

链接也以与depends_on相同的方式表达服务之间的隐式依赖关系,因此它们决定了服务启动的顺序.

logging

logging定义服务的日志记录配置.

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

driver名称指定服务容器的日志记录驱动程序. 默认值和可用值是特定于平台的. 驱动程序特定的选项可以设置为键值对的options .

network_mode

network_mode设置服务容器的网络模式. 可用值是特定于平台的,但 Compose 规范定义了特定值,如果支持,则必须按照描述实现:

  • none禁用所有容器网络
  • host ,它为容器提供对主机网络接口的原始访问权限
  • service:{name}只允许容器访问指定的服务
    network_mode: "host"
    network_mode: "none"
    network_mode: "service:[service name]"

networks

networks定义服务容器附加到的网络,引用顶级networks下的条目.

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

aliases

aliases在网络上声明此服务的备用主机名. 同一网络上的其他容器可以使用服务名称或此别名连接到服务的容器之一.

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

注意:网络范围的别名可以被多个容器共享,甚至可以被多个服务共享. 如果是,则无法保证名称解析为哪个容器.

一般格式如下所示:

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

在下面的示例中,服务frontend将能够访问back-tier网络上主机名backenddatabasebackend服务,服务monitoring将能够访问admin网络上dbmysql上的相同backend服务.

services:
  frontend:
    image: awesome/webapp
    networks:
      - front-tier
      - back-tier

  monitoring:
    image: awesome/monitoring
    networks:
      - admin

  backend:
    image: awesome/backend
    networks:
      back-tier:
        aliases:
          - database
      admin:
        aliases:
          - mysql

networks:
  front-tier:
  back-tier:
  admin:

ipv4_address, ipv6_address

加入网络时,为此服务的容器指定静态 IP 地址.

顶级网络部分中的相应网络配置必须有一个ipam块,其中子网配置覆盖每个静态地址.

services:
  frontend:
    image: awesome/webapp
    networks:
      front-tier:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  front-tier:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"

link_local_ips指定链接本地 IP 的列表. 链接本地 IP 是属于众所周知的子网的特殊 IP,完全由运营商管理,通常取决于部署它们的架构. 实现是平台特定的.

Example:

services:
  app:
    image: busybox
    command: top
    networks:
      app_net:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
networks:
  app_net:
    driver: bridge

priority

priority指示 Compose 实现应该以何种顺序将服务的容器连接到其网络. 如果未指定,则默认值为 0.

在以下示例中,应用服务首先连接到 app_net_1,因为它具有最高优先级. 然后它连接到 app_net_3,然后是 app_net_2,它使用默认优先级值 0.

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

mac_address

mac_address设置服务容器的 MAC 地址.

mem_limit

已弃用:使用deploy.limits.memory

mem_reservation

已弃用:使用deploy.reservations.memory

mem_swappiness

mem_swappiness定义为主机内核交换容器使用的匿名内存页面的百分比(0 到 100 之间的值).

  • a value of 0 turns off anonymous page swapping.
  • 值 100 将所有匿名页面设置为可交换.

默认值是平台特定的.

memswap_limit

memswap_limit定义了允许交换到磁盘的内存容器的数量. 这是一个修饰符属性,仅在还设置了memory时才有意义. 使用交换允许容器在容器耗尽所有可用内存时将多余的内存需求写入磁盘. 经常将内存交换到磁盘的应用程序会降低性能.

  • 如果memswap_limit设置为正整数,则必须同时设置memorymemswap_limit . memswap_limit表示可以使用的内存和交换的总量, memory控制非交换内存的使用量. 所以如果memory ="300m" and memswap_limit ="1g",容器可以使用 300m 的内存和 700m (1g - 300m) 的交换空间.
  • 如果memswap_limit设置为 0,则必须忽略该设置,并将该值视为未设置.
  • 如果memswap_limit设置为与memory相同的值,并且memory设置为正整数,则容器无权访问交换. 请参阅防止容器使用交换.
  • 如果未设置memswap_limit并设置了memory ,则容器可以使用与memory设置一样多的交换,如果主机容器配置了交换内存. 例如,如果memory ="300m" 并且没有设置memswap_limit ,则容器总共可以使用 600m 的内存和交换空间.
  • 如果memswap_limit显式设置为 -1,则允许容器使用无限交换,最多为主机系统上可用的数量.

oom_kill_disable

如果设置了oom_kill_disable ,则 Compose 实现必须配置平台,以便在内存不足的情况下不会杀死容器.

oom_score_adj

oom_score_adj调整容器在内存不足的情况下被平台杀死的偏好. 值必须在 [-1000,1000] 范围内.

pid

pid为 Compose 实现创建的容器设置 PID 模式. 支持的值是特定于平台的.

pids_limit

已弃用:使用deploy.reservations.pids

pids_limit调整容器的 PID 限制. 设置为 -1 表示无限 PID.

pids_limit: 10

platform

platform使用os[/arch[/variant]]语法定义了此服务将在其上运行的目标平台容器. Compose 实现在声明时必须使用此属性来确定将提取哪个版本的图像和/或将在哪个平台上执行服务的构建.

platform: osx
platform: windows/amd64
platform: linux/arm64/v8

ports

暴露集装箱港口. 端口映射不得与network_mode: host一起使用,这样做必须导致运行时错误.

Short syntax

简短语法是一个以冒号分隔的字符串,用于设置主机 IP、主机端口和容器端口,格式如下:

[HOST:]CONTAINER[/PROTOCOL] where:

  • HOST is [IP:](port | range)
  • CONTAINER is port | range
  • PROTOCOL将端口限制为指定的协议. tcpudp值由规范定义,Compose 实现可以提供对特定于平台的协议名称的支持.

主机 IP,如果未设置,必须绑定到所有网络接口. 端口可以​​是单个值或范围. 主机和容器必须使用等效范围.

要么指定两个端口( HOST:CONTAINER ),要么只指定容器端口. 在后一种情况下,Compose 实现应该自动分配任何未分配的主机端口.

HOST:CONTAINER应始终指定为(带引号的)字符串,以避免与yaml base-60 float冲突.

Samples:

ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "6060:6060/udp"

注意:平台可能不支持主机 IP 映射,在这种情况下,Compose 实现应该拒绝 Compose 文件并且必须通知用户他们将忽略指定的主机 IP.

Long syntax

长格式语法允许配置无法以短格式表示的附加字段.

  • target :容器端口
  • published :公开的端口. 可以使用语法start-end设置为范围,然后应该根据可用端口在此范围内分配实际端口.
  • host_ip :主机 IP 映射,未指定表示所有网络接口( 0.0.0.0
  • protocol :端口协议( tcpudp ),未指定表示任何协议
  • mode : host用于在每个节点上发布主机端口,或用于负载平衡的端口的ingress .
ports:
  - target: 80
    host_ip: 127.0.0.1
    published: 8080
    protocol: tcp
    mode: host

  - target: 80
    host_ip: 127.0.0.1
    published: 8000-9000
    protocol: tcp
    mode: host

privileged

privileged将服务容器配置为以提升的权限运行. 支持和实际影响因平台而异.

profiles

profiles为要启用的服务定义了一个命名配置文件列表. 未设置时,服务始终启用.

如果存在, profiles应该遵循[a-zA-Z0-9][a-zA-Z0-9_.-]+的正则表达式格式.

pull_policy

pull_policy定义 Compose 实现在开始拉取图像时将做出的决定. 可能的值为:

  • always : Compose 实现应该总是从注册表中拉取图像.
  • never : Compose 实现不应该从注册表中提取图像,而应该依赖于平台缓存的图像. 如果没有缓存图像,则必须报告失败.
  • missing :仅当平台缓存中不可用时,Compose 实现应该拉取图像. 这应该是没有构建支持的 Compose 实现的默认选项. if_not_present应该被认为是这个值的别名,以便向后兼容
  • build : Compose 实现应该构建图像. 如果已经存在,Compose 实现应该重建图像.

如果pull_policybuild都存在, Compose 实现应该默认构建镜像. Compose 实现可以覆盖工具链中的这种行为.

read_only

read_only将服务容器配置为使用只读文件系统创建.

restart

restart定义了平台将在容器终止时应用的策略.

  • no :默认重启策略. 在任何情况下都不会重新启动容器.
  • always :该策略始终重新启动容器,直到将其删除.
  • on-failure :如果退出代码指示错误,该策略将重新启动容器.
  • unless-stopped :该策略会重新启动容器,而不考虑退出代码,但会在服务停止或删除时停止重新启动.
    restart: "no"
    restart: always
    restart: on-failure
    restart: unless-stopped

runtime

runtime指定用于服务容器的运行时.

runtime的值特定于实现. 例如, runtime可以是OCI Runtime Spec 实现的名称,例如"runc".

web:
  image: busybox:latest
  command: true
  runtime: runc

scale

-已弃用:使用部署/副本_

scale指定要为此服务部署的默认容器数量.

secrets

secrets授予对基于每个服务的机密定义的敏感数据的访问权限. 支持两种不同的语法变体:短语法和长语法.

如果平台上不存在秘密或未在此 Compose 文件的secrets部分中定义,则 Compose 实现必须报告错误.

Short syntax

短语法变体仅指定秘密名称. 这将授予容器对机密的访问权限,并将其以只读方式挂载到容器内的/run/secrets/<secret_name>中. 源名称和目标挂载点都设置为机密名称.

以下示例使用简短语法授予frontend服务访问server-certificate密钥的权限. server-certificate的值设置为文件./server.cert的内容.

services:
  frontend:
    image: awesome/webapp
    secrets:
      - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

Long syntax

长语法为如何在服务的容器中创建秘密提供了更多的粒度.

  • source :存在于平台上的密钥的名称.
  • target :要挂载在服务任务容器中的/run/secrets/中的文件的名称. 如果未指定,则默认为source .
  • uidgid :拥有服务任务容器中/run/secrets/中文件的数字 UID 或 GID. 默认值为 USER 运行容器.
  • mode : 文件挂载到服务任务容器中的/run/secrets/权限,以八进制表示. 默认值为世界可读权限(模式0444 ). 如果设置了可写位,则必须忽略. 可执行位可以设置.

以下示例将server-certificate机密文件的名称设置为容器内的server.crt ,将模式设置为0440 (组可读)并将用户和组设置为103 . server-certificate密钥的值由平台通过查找提供,并且密钥生命周期不由 Compose 实现直接管理.

services:
  frontend:
    image: awesome/webapp
    secrets:
      - source: server-certificate
        target: server.cert
        uid: "103"
        gid: "103"
        mode: 0440
secrets:
  server-certificate:
    external: true

服务可以被授予访问多个秘密的权限. 可以在同一个 Compose 文件中使用密钥的长语法和短语法. 在顶级secrets中定义机密不得暗示授予任何服务对其的访问权限. 这种授权必须在服务规范中作为秘密服务元素明确.

security_opt

security_opt覆盖每个容器的默认标签方案.

security_opt:
  - label:user:USER
  - label:role:ROLE

shm_size

shm_size配置服务容器允许的共享内存(Linux 上的/dev/shm分区)的大小. 指定为字节值.

stdin_open

stdin_open将服务容器配置为使用分配的标准输入运行.

stop_grace_period

stop_grace_period指定 Compose 实现在尝试停止容器时必须等待多长时间,如果它不处理 SIGTERM(或使用stop_signal指定的任何停止信号),然后再发送 SIGKILL. 指定为持续时间.

    stop_grace_period: 1s
    stop_grace_period: 1m30s

默认值是容器在发送 SIGKILL 之前退出的 10 秒.

stop_signal

stop_signal定义 Compose 实现必须用来停止服务容器的信号. 如果未设置的容器被 Compose 实现通过发送SIGTERM停止.

stop_signal: SIGUSR1

storage_opt

storage_opt定义服务的存储驱动程序选项.

storage_opt:
  size: '1G'

sysctls

sysctls定义要在容器中设置的内核参数. sysctls可以使用数组或映射.

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0
sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

您只能使用在内核中命名空间的 sysctl. Docker 不支持更改容器内的 sysctls 也会修改主机系统. 有关支持的 sysctls 的概述,请参阅在运行时配置命名空间内核参数 (sysctls) .

tmpfs

tmpfs在容器内挂载一个临时文件系统. 可以是单个值或列表.

tmpfs: /run
tmpfs:
  - /run
  - /tmp

tty

tty配置服务容器以使用 TTY 运行.

ulimits

ulimits覆盖容器的默认 ulimits. 要么将单个限制指定为整数,要么将软/硬限制指定为映射.

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000

user

user覆盖用于运行容器进程的用户. 默认是由图像设置的(即 Dockerfile USER ),如果没有设置,则为root .

userns_mode

userns_mode设置服务的用户命名空间. 支持的值是特定于平台的,可能取决于平台配置

userns_mode: "host"

volumes

volumes defines mount host paths or named volumes that MUST be accessible by service containers.

如果挂载是主机路径并且仅由单个服务使用,则可以将其声明为服务定义的一部分,而不是顶级volumes键.

要跨多个服务重用一个卷,必须在顶级volumes中声明一个命名卷.

此示例显示backend服务使用的命名卷 ( db-data ),以及为单个服务定义的绑定挂载

services:
  backend:
    image: awesome/backend
    volumes:
      - type: volume
        source: db-data
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: /var/run/postgres/postgres.sock
        target: /var/run/postgres/postgres.sock

volumes:
  db-data:

Short syntax

简短语法使用带有冒号分隔值的单个字符串来指定卷安装 ( VOLUME:CONTAINER_PATH ) 或访问模式 ( VOLUME:CONTAINER_PATH:ACCESS_MODE ).

  • VOLUME :可以是托管容器的平台上的主机路径(绑定挂载)或卷名
  • CONTAINER_PATH :容器中安装卷的路径
  • ACCESS_MODE :是一个逗号分隔,选项列表,可以设置为:
    • rw :读写访问(默认)
    • ro : 只读访问
    • z :SELinux 选项表示绑定挂载主机内容在多个容器之间共享
    • Z :SELinux 选项表示绑定挂载主机内容是私有的,对其他容器不共享

注意:在没有 SELinux 的平台上,SELinux 重新标记绑定挂载选项会被忽略.

注意:相对主机路径必须仅由部署到本地容器运行时的 Compose 实现支持. 这是因为相对路径是从 Compose 文件的父目录解析的,该父目录仅适用于本地情况. 部署到非本地平台的 Compose 实现必须拒绝使用带有错误的相对主机路径的 Compose 文件. 为避免命名卷的歧义,相对路径应始终以...

Long syntax

长格式语法允许配置无法以短格式表示的附加字段.

  • type : 挂载类型volume , bind , tmpfsnpipe
  • source :挂载的源,主机上用于绑定挂载的路径,或者在顶级volumes中定义的卷的名称. 不适用于 tmpfs 挂载.
  • target :容器中安装卷的路径
  • read_only : 将卷设置为只读的标志
  • bind : 配置额外的绑定选项
    • propagation :用于绑定的传播模式
    • create_host_path :如果没有任何内容,则在主机上的源路径创建一个目录. 如果路径上有东西,什么也不做. 为了与 docker-compose legacy 向后兼容,简短语法自动暗示了这一点.
    • selinux :SELinux 重新标记选项z (共享)或Z (私有)
  • volume : 配置额外的音量选项
    • nocopy : 创建卷时禁止从容器复制数据的标志
  • tmpfs : 配置额外的 tmpfs 选项
    • size :tmpfs 挂载的大小,以字节为单位(数字或字节单位)
  • consistency :安装的一致性要求. 可用值是特定于平台的

volumes_from

volumes_from挂载来自另一个服务或容器的所有卷,可选择指定只读访问 (ro) 或读写 (rw). 如果没有指定访问级别,则必须使用读写.

String value defines another service in the Compose application model to mount volumes from. The container: prefix, if supported, allows to mount volumes from a container that is not managed by the Compose implementation.

volumes_from:
  - service_name
  - service_name:ro
  - container:container_name
  - container:container_name:rw

working_dir

working_dir覆盖了镜像指定的容器工作目录(即 Dockerfile WORKDIR ).

Networks top-level element

网络是允许服务相互通信的层. 向服务公开的网络模型仅限于与目标服务和外部资源的简单 IP 连接,而网络定义允许微调平台提供的实际实现.

可以通过在顶级networks部分下指定网络名称来创建网络. 服务可以通过在服务networks小节下指定网络名称来连接到网络

在下面的示例中,在运行时,将创建网络front-tierback-tier ,并将frontend服务连接到front-tier网络和back-tier网络.

services:
  frontend:
    image: awesome/webapp
    networks:
      - front-tier
      - back-tier

networks:
  front-tier:
  back-tier:

driver

driver指定该网络应该使用哪个驱动程序. 如果驱动程序在平台上不可用,则 Compose 实现必须返回错误.

driver: overlay

默认值和可用值是特定于平台的. Compose 规范必须支持以下特定驱动程序: nonehost

  • host使用主机的网络堆栈
  • none禁用网络

host or none

使用内置网络(如hostnone )的语法是不同的,因为这些网络隐式存在于 Compose 实现的范围之外. 要使用它们,必须定义一个名称为hostnone的外部网络以及 Compose 实现可以使用的别名(以下示例中的hostnetnonet ),然后使用其别名授予服务访问该网络的权限.

services:
  web:
    networks:
      hostnet: {}

networks:
  hostnet:
    external: true
    name: host
services:
  web:
    ...
    networks:
      nonet: {}

networks:
  nonet:
    external: true
    name: none

driver_opts

driver_opts指定选项列表作为键值对传递给该网络的驱动程序. 这些选项取决于驱动程序 - 请参阅驱动程序文档以获取更多信息. 选修的.

driver_opts:
  foo: "bar"
  baz: 1

attachable

如果attachable设置为true ,那么除了服务之外,独立容器应该能够附加到这个网络. 如果独立容器连接到网络,它可以与服务和其他也连接到网络的独立容器通信.

networks:
  mynet1:
    driver: overlay
    attachable: true

enable_ipv6

enable_ipv6在此网络上启用 IPv6 网络.

ipam

ipam指定自定义 IPAM 配置. 这是一个具有多个属性的对象,每个属性都是可选的:

  • driver :自定义 IPAM 驱动程序,而不是默认驱动程序.
  • config :具有零个或多个配置元素的列表,每个包含:
    • subnet : CIDR 格式的子网,代表一个网段
    • ip_range : 分配容器 IP 的 IP 范围
    • gateway :主子网的 IPv4 或 IPv6 网关
    • aux_addresses :网络驱动程序使用的辅助 IPv4 或 IPv6 地址,作为从主机名到 IP 的映射
  • options :作为键值映射的特定于驱动程序的选项.

一个完整的例子:

ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16
      ip_range: 172.28.5.0/24
      gateway: 172.28.5.254
      aux_addresses:
        host1: 172.28.1.5
        host2: 172.28.1.6
        host3: 172.28.1.7
  options:
    foo: bar
    baz: "0"

internal

默认情况下,Compose 实现必须提供到网络的外部连接. internal设置为true时允许创建外部隔离网络.

labels

使用标签将元数据添加到容器. 可以使用数组或字典.

用户应该使用反向 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"

Compose 实现必须设置com.docker.compose.projectcom.docker.compose.network标签.

external

如果设置为true ,则external指定此网络的生命周期在应用程序之外维护. Compose 实现不应该尝试创建这些网络,如果不存在则会引发错误.

在下面的示例中, proxy是通往外部世界的网关. Compose 实现不应该尝试创建网络,而是应该询问平台以获取简单地outside调用的现有网络,并将proxy服务的容器连接到它.


services:
  proxy:
    image: awesome/proxy
    networks:
      - outside
      - default
  app:
    image: awesome/app
    networks:
      - default

networks:
  outside:
    external: true

name

name设置此网络的自定义名称. 名称字段可用于引用包含特殊字符的网络. 该名称按原样使用,不会与项目名称一起使用.

networks:
  network1:
    name: my-app-net

它也可以与external属性结合使用来定义 Compose 实现应该检索的平台网络,通常使用一个参数,因此 Compose 文件不需要硬编码运行时特定的值:

networks:
  network1:
    external: true
    name: "${NETWORK_ID}"

Volumes top-level element

卷是平台实现的持久数据存储. Compose 规范为挂载卷的服务和在基础架构上分配它们的配置参数提供了中性抽象.

volumes部分允许配置可以跨多个服务重用的命名卷. 这是一个双服务设置的示例,其中数据库的数据目录与另一个服务共享为名为db-data的卷,以便可以定期备份:

services:
  backend:
    image: awesome/database
    volumes:
      - db-data:/etc/data

  backup:
    image: backup-service
    volumes:
      - db-data:/var/lib/backup/data

volumes:
  db-data:

顶级volumes键下的条目可以为空,在这种情况下,它使用平台的默认配置来创建卷. 或者,您可以使用以下键对其进行配置:

driver

指定应为此卷使用的卷驱动程序. 默认值和可用值是特定于平台的. 如果驱动程序不可用,Compose 实现必须返回错误并停止应用程序部署.

driver: foobar

driver_opts

driver_opts将选项列表指定为键值对,以传递给此卷的驱动程序. 这些选项取决于驱动程序.

volumes:
  example:
    driver_opts:
      type: "nfs"
      o: "addr=10.40.0.199,nolock,soft,rw"
      device: ":/docker/example"

external

If set to true, external specifies that this volume already exist on the platform and its lifecycle is managed outside of that of the application. Compose implementations MUST NOT attempt to create these volumes, and MUST return an error if they do not exist.

在下面的示例中,Compose 并没有尝试创建一个名为{project_name}_db-data的卷,而是寻找一个简单地称为db-data的现有卷并将其挂载到backend服务的容器中.

services:
  backend:
    image: awesome/database
    volumes:
      - db-data:/etc/data

volumes:
  db-data:
    external: true

labels

labels用于向卷添加元数据. 您可以使用数组或字典.

建议您使用反向 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"

Compose 实现必须设置com.docker.compose.projectcom.docker.compose.volume标签.

name

name set a custom name for this volume. The name field can be used to reference volumes that contain special characters. The name is used as is and will not be scoped with the stack name.

volumes:
  data:
    name: "my-app-data"

它也可以与external属性结合使用. 这样做,用于在平台上查找实际卷的卷的名称与 Compose 文件中用于引用它的名称分开设置:

volumes:
  db-data:
    external:
      name: actual-name-of-volume

这使得可以将此查找名称作为 Compose 文件的参数,以便卷的模型 ID 是硬编码的,但平台上的实际卷 ID 是在部署期间的运行时设置的:

volumes:
  db-data:
    external:
      name: ${DATABASE_VOLUME}

Configs top-level element

配置允许服务调整其行为,而无需重建 Docker 映像. 从服务的角度来看,配置与卷相当,因为它们被挂载到服务的容器文件系统中. 获取平台提供的配置的实际实现细节可以从配置定义中设置.

当授予对配置的访问权限时,配置内容将作为文件安装在容器中. 容器内挂载点的位置在 Linux 容器中默认为/<config-name> ,在 Windows 容器中默认为C:\<config-name> .

默认情况下,配置必须由运行容器命令的用户拥有,但可以被服务配置覆盖. 默认情况下,配置必须具有世界可读权限(模式 0444),除非服务被配置为覆盖它.

服务只能在configs子部分明确授予时访问配置.

顶级configs声明定义或引用可以授予此应用程序中的服务的配置数据. 配置的来源是fileexternal .

  • file :使用指定路径的文件内容创建配置.
  • external :如果设置为 true,则指定此配置已创建. Compose 实现不会尝试创建它,如果它不存在,则会发生错误.
  • name: The name of config object on Platform to lookup. This field can be used to reference configs that contain special characters. The name is used as is and will not be scoped with the project name.

在这个例子中, http_config在部署应用程序时被创建(作为<project_name>_http_config ),并且my_second_config必须已经存在于 Platform 上并且值将通过查找获得.

在此示例中,通过将httpd.conf的内容注册为配置数据,在部署应用程序时将server-http_config创建为<project_name>_http_config .

configs:
  http_config:
    file: ./httpd.conf

或者,可以将http_config声明为外部,这样 Compose 实现将查找http_config以将配置数据公开给相关服务.

configs:
  http_config:
    external: true

外部配置查找也可以通过指定name来使用不同的键. 以下示例修改前一个以使用参数HTTP_CONFIG_KEY查找配置. 这样做,实际的查找键将在部署时通过变量的插值设置,但作为硬编码 ID http_config暴露给容器.

configs:
  http_config:
    external: true
    name: "${HTTP_CONFIG_KEY}"

Compose 文件需要明确授予对应用程序中相关服务的配置的访问权限.

Secrets top-level element

Secrets are a flavour of Configs focussing on sensitive data, with specific constraint for this usage. As the platform implementation may significantly differ from Configs, dedicated Secrets section allows to configure the related resources.

顶级secrets声明定义或引用可以授予此应用程序中的服务的敏感数据. 秘密的来源是fileexternal .

  • file :秘密是使用指定路径的文件内容创建的.
  • external :如果设置为 true,则指定此密钥已创建. Compose 实现不会尝试创建它,如果它不存在,则会发生错误.
  • name :Docker 中秘密对象的名称. 此字段可用于引用包含特殊字符的机密. 该名称按原样使用,不会与项目名称一起使用.

在此示例中,通过将server.cert的内容注册为平台机密,在部署应用程序时将server-certificate创建为<project_name>_server-certificate .

secrets:
  server-certificate:
    file: ./server.cert

或者,可以将server-certificate声明为外部,这样 Compose 实现将查找server-certificate以向相关服务公开秘密.

secrets:
  server-certificate:
    external: true

外部秘密查找也可以通过指定name来使用不同的密钥. 以下示例修改了前一个示例以使用参数CERTIFICATE_KEY查找秘密. 这样做,实际的查找键将在部署时通过变量的插值设置,但作为硬编码的 ID server-certificate暴露给容器.

secrets:
  server-certificate:
    external: true
    name: "${CERTIFICATE_KEY}"

撰写文件需要明确授予对应用程序中相关服务的机密的访问权限.

Fragments

可以使用YAML 锚点重用配置片段.

volumes:
  db-data: &default-volume
    driver: default
  metrics: *default-volume

在前面的示例中,基于db-data卷规范将锚点创建为default-volume卷. 它稍后被别名*default-volume重用来定义metrics量. 相同的逻辑可以应用于 Compose 文件中的任何元素. 锚解析必须在变量插值之前进行,因此变量不能用于设置锚或别名.

It is also possible to partially override values set by anchor reference using the YAML 合并类型. In following example, metrics volume specification uses alias to avoid repetition but override name attribute:


services:
  backend:
    image: awesome/database
    volumes:
      - db-data
      - metrics
volumes:
  db-data: &default-volume
    driver: default
    name: "data"
  metrics:
    <<: *default-volume
    name: "metrics"

Extension

特殊扩展字段可以是任何格式,只要它们的名称以x-字符序列开头. 它们可以在 Compose 文件的任何结构中使用. 这是 Compose 实现静默忽略未识别字段的唯一例外.

x-custom:
  foo:
    - bar
    - zot

services:
  webapp:
    image: awesome/webapp
    x-foo: bar

Compose 规范未指定此类字段的内容,可用于启用自定义功能. 编写遇到未知扩展字段的实现不能失败,但可以警告未知字段.

对于平台扩展,强烈建议使用平台/供应商名称作为扩展前缀,就像浏览器添加对自定义 CSS 功能的支持一样.

service:
  backend:
    deploy:
      placement:
        x-aws-role: "arn:aws:iam::XXXXXXXXXXXX:role/foo"
        x-aws-region: "eu-west-3"
        x-azure-region: "france-central"

Informative Historical Notes

本节内容丰富. 在撰写本文时,已知存在以下前缀:

prefix vendor/organization
docker Docker
kubernetes Kubernetes

Using extensions as fragments

借助扩展字段的支持,Compose 文件可以编写如下,以提高重用片段的可读性:

x-logging: &default-logging
  options:
    max-size: "12m"
    max-file: "5"
  driver: json-file

services:
  frontend:
    image: awesome/webapp
    logging: *default-logging
  backend:
    image: awesome/database
    logging: *default-logging

specifying byte values

Value 以{amount}{byte unit}格式将字节值表示为字符串:支持的单位为b (字节)、 kkb (千字节)、 mmb (兆字节)和ggb (千兆字节) .

    2b
    1024kb
    2048k
    300m
    1gb

specifying durations

值以{value}{unit}的形式将持续时间表示为字符串. 支持的单位是us (微秒)、 ms (毫秒)、 s (秒)、 m (分钟)和h (小时). 值可以组合多个值并使用不带分隔符.

  10ms
  40s
  1m30s
  1h5m30s20ms

Interpolation

Compose 文件中的值可以由变量设置,并在运行时进行插值. 撰写文件使用类似 Bash 的语法${VARIABLE}

支持$VARIABLE${VARIABLE}语法. 可以使用典型的 shell 语法内联定义默认值:latest

  • 如果VARIABLE在环境中未设置或为空,则${VARIABLE:-default}评估为default .
  • 只有在环境中未设置VARIABLE${VARIABLE-default}才会评估为default .

同样,以下语法允许您指定强制变量:

  • 如果VARIABLE在环境中未设置或为空,则${VARIABLE:?err}退出并显示包含err的错误消息.
  • 如果在环境中未设置VARIABLE ,则${VARIABLE?err}退出并显示包含err的错误消息.

插值也可以嵌套:

  • ${VARIABLE:-${FOO}}
  • ${VARIABLE?$FOO}
  • ${VARIABLE:-${FOO:-default}}

Compose 规范不支持其他扩展的 shell 样式功能,例如${VARIABLE/foo/bar} .

当您的配置需要文字美元符号时,您可以使用$$ (双美元符号). 这也可以防止 Compose 插入值,因此$$允许您引用您不希望 Compose 处理的环境变量.

web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"

如果 Compose 实现无法解析替换变量并且没有定义默认值,它必须警告用户并用空字符串替换变量.

由于 Compose 文件中的任何值都可以使用变量替换进行插值,包括复杂元素的紧凑字符串表示法,因此必须在基于每个文件的合并之前应用插值.

Compose documentation

fig, composition, compose, docker

by  icopy.site