Docker：Compose file v2 reference

一、Compose文件版本

Compose文件是一个YAML文件，用于定义services、netword和volumes。 Compose 文件的默认路径为./docker-compose.yml(后缀为.yml和.yaml都可以)。

一个service配置将会应用到容器的启动中，很像将命令行参数传递给docker run。同样，network和volume定义类似于docker network create和docker volume create。与Docker运行一样，默认情况下尊重Dockerfile中指定的选项（例如CMD，EXPOSE，VOLUME，ENV） – 您不需要在docker-compose.yml中再次指定它们。

Compose文件发展到目前为止，已经有了V1、V2、V3三个版本的文件格式，特定于每个版本。

Reference file	What changed in this version
Version 3 (most current, and recommended)	Version 3 updates
Version 2	Version 2 updates
Version 1	Version 1 updates

Compose与Docker兼容性矩阵：

Compose file format	Docker Engine release
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.3	17.06.0+
2.2	1.13.0+
2.1	1.12.0+
2.0	1.10.0+
1.0	1.9.1.+

version

目前有三种版本的Compose文件格式：

版本1，传统格式。YAML文件不需要指定version关键字，默认就是版本1。

版本2.x.，这是在YAML文件中通过指定version: ‘2’或者version: ‘2.1’条目来生效。

版本3.x是最新和推荐的版本，旨在Compose和Docker Engine的swarm模式之间交叉兼容，这是在YAML文件中通过指定version: ‘3’或者version: ‘3.1’条目来生效。

version: '2'
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

version: '2'

services:

web:

build: .

depends_on:

- db

- redis

redis:

image: redis

db:

image: postgres

二、Service配置参考

每个docker-compose.yml必须定义image或者build中的一个，其它的是可选的。

build

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

build可以指定为包含构建上下文路径，也可以根据上下文选择 dockerfile 和 args 指定的路径对象。

build: ./dir

build:
  context: ./dir
  dockerfile: Dockerfile-alternate
  args:
    buildno: 1

build: ./dir

build:

context: ./dir

dockerfile: Dockerfile-alternate

args:

buildno: 1

如果指定image字段来build，则Compose使用image中指定的webapp和tag（可选）命名构建的image：

build: ./dir
image: webapp:tag

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

这里从./dir构建了一个镜像名为webapp，并打上标记为tag的镜像。

context

它的值可以是Dockerfile的路径，或者是指向git仓库的url。

当提供的值是相对路径时，它被解释Compose文件位置的相对路径。目录里的信息会被当做构建内容发送到Docker守护进程。

Compose将使用生成的名字build和tag它，然后使用该image。

build:
  context: ./dir

1 2	build: context: ./dir

args

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

首先，在Dockerfile中指定参数：

ARG buildno
ARG password

RUN echo "Build number: $buildno"
RUN script-requiring-password.sh "$password"

ARG buildno

ARG password

RUN echo "Build number: $buildno"

RUN script-requiring-password.sh "$password"

然后，指定build字段下的参数args。您可以mapping或list：

build:
  context: .
  args:
    buildno: 1
    password: secret

build:
  context: .
  args:
    - buildno=1
    - password=secret

build:

context: .

args:

buildno: 1

password: secret

build:

context: .

args:

- buildno=1

- password=secret

指定build参数时，可以忽略该值，在这种情况下，构建时其值为运行Compose的环境中的值。

args:
  - buildno
  - password

args:

- buildno

- password

command

覆盖默认命令

command: bundle exec thin -p 3000

1	command: bundle exec thin -p 3000

该命令也可以是一个list，在方式类似于dockerfile：

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

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

container_name

设置容器名称

container_name: name-01

1	container_name: name-01

由于Docker容器名称必须是唯一的，因此如果您指定了自定义名称，则无法将服务扩展到1个容器之外。尝试这样做会导致错误。

hostname

设置主机名称

hostname: name-01

1	hostname: name-01

depends_on

容器之间的依赖关系，有两个效果：

docker-compose up将按照依赖顺序启动服务，在下面的示例中，db和redis将在web之前启动。

docker-compose up SERVICE将自动包含SERVICE的依赖关系，在以下示例中，docker-compose up web也将创建并启动db和redis。

version: '2'
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

version: '2'

services:

web:

build: .

depends_on:

- db

- redis

redis:

image: redis

db:

image: postgres

注意：在启动web之前，depends_on不会等待db和redis“就绪”，直到它们被启动。如果您需要等待服务准备就绪，请参阅控制启动顺序了解有关此问题的更多信息以及解决问题的策略。

dns

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

dns: 8.8.8.8
dns:
  - 8.8.8.8
  - 9.9.9.9

dns: 8.8.8.8

dns:

- 8.8.8.8

- 9.9.9.9

tmpfs

在容器中安装临时文件系统，可以是单个值或列表。

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

tmpfs: /run

tmpfs:

- /run

- /tmp

entrypoint

覆盖默认的entrypoint。

entrypoint: /code/entrypoint.sh

1	entrypoint: /code/entrypoint.sh

entrypoint也可以是一个列表，存在方式类似于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

entrypoint:

- php

- -d

- zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so

- -d

- memory_limit=-1

- vendor/bin/phpunit

environment

添加环境变量。您可以使用数组或字典。任意布尔值:true，false，yes no，需要用引号括起来，以确保它们不会被YML解析器转换为True或False。

只有一个键的环境变量被解析为它在Compose正在运行的机器上的值，这对于secret或host-specific values是有帮助的。

environment:
  RACK_ENV: development
  SHOW: 'true'
  SESSION_SECRET:

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

environment:

RACK_ENV: development

SHOW: 'true'

SESSION_SECRET:

environment:

- RACK_ENV=development

- SHOW=true

- SESSION_SECRET

注意：如果您的服务指定了build选项，则在build期间将不会自动显示在环境中定义的变量。使用build的args子选项来定义构建时环境变量。

env_file

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

如果已使用docker-compose -f FILE指定了一个Compose文件，则env_file中的路径相对于该文件所在的目录。

在环境中指定的环境变量会覆盖这些值。

env_file: .env

env_file:
  - ./common.env
  - ./apps/web.env
  - /opt/secrets.env

env_file: .env

env_file:

- ./common.env

- ./apps/web.env

- /opt/secrets.env

Compose期望env文件中的每一行都处于VAR = VAL格式。以＃开头的行（即注释）将被忽略，空行也是如此。

# Set Rails/Rack environment
RACK_ENV=development

1 2	# Set Rails/Rack environment RACK_ENV=development

注意：如果您的service指定了build选项，则在build过程中将不会自动显示环境文件中定义的变量，使用build的args子选项来定义构建时环境变量。

expose

公开端口，而不将其发布到主机 – 它们只能访问链接服务。只能指定内部端口。

expose:
 - "3000"
 - "8000"

expose:

- "3000"

- "8000"

external_links

链接到在docker-compose.yml外部启动的容器，甚至在Compose之外，特别是对于提供共享或公共服务的容器。 external_links在指定容器名称和链接别名（CONTAINER：ALIAS）时遵循类似于links的语义。

external_links:
 - redis_1
 - project_db_1:mysql
 - project_db_1:postgresql

external_links:

- redis_1

- project_db_1:mysql

- project_db_1:postgresql

extra_hosts

添加主机名映射。使用与docker client –add-host参数相同的值。

  extra_hosts:
    - "www.ywnds.com:10.106.136.7"

1 2	extra_hosts: - "www.ywnds.com:10.106.136.7"

此参数的意义就相当于添加一个hosts文件，在程序中直接调用域名，然后通过hosts文件解析。

image

指定要从中启动容器的映像，可以是存储库/标记或image ID。

image: redis
image: ubuntu:14.04
image: tutum/influxdb
image: example-registry.com:4000/postgresql
image: a4bc65fd

image: redis

image: ubuntu:14.04

image: tutum/influxdb

image: example-registry.com:4000/postgresql

image: a4bc65fd

如果image不存在，Compose会尝试拉取它，除非你也指定了build，在这种情况下，它使用指定的选项构建它，并用指定的标签标记它。

links

链接到另一个服务中的容器。请指定服务名称和链接别名（SERVICE：ALIAS），或仅指定服务名称。

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

web:

links:

- db

- db:database

- redis

如果未指定别名，则可以在与别名相同的主机名或服务名称处访问链接服务的容器。

链接也以与depends_on相同的方式表示服务之间的依赖关系，因此它们确定服务启动的顺序。

network_mode

网络模式。使用与docker client –net参数相同的值，以及特殊表单 service：[service name]。

network_mode: "bridge"
network_mode: "host"
network_mode: "none"
network_mode: "service:[service name]"
network_mode: "container:[container name/id]"

network_mode: "bridge"

network_mode: "host"

network_mode: "none"

network_mode: "service:[service name]"

network_mode: "container:[container name/id]"

ports

公开端口。指定两个端口（HOST：CONTAINER），或只指定容器端口（将选择随机主机端口）。

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"

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"

ulimits

覆盖容器的默认ulimits，您可以将单个限制指定为整数或soft/hard限制作为映射。

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

ulimits:

nproc: 65535

nofile:

soft: 20000

hard: 40000

volumes，volume_driver

装载路径或命名卷（可选）指定主机上的路径（HOST:CONTAINER）或访问模式（HOST:CONTAINER:ro）。对于版本2文件，命名卷需要使用top-level volumes key`指定。当使用版本1时，Docker Engine将自动创建命名卷（如果不存在）。

您可以在主机上安装相对路径，相对于正在使用的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

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

如果不使用主机路径，则可以指定volume_driver。

volume_driver: mydriver

1	volume_driver: mydriver

volumes_from

从另一个服务或容器装入所有卷，可选择指定只读访问（ro）或读写（rw）。如果未指定访问级别，则将使用读写。

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

volumes_from:

- service_name

- service_name:ro

- container:container_name

- container:container_name:rw

cpu_shares, cpu_quota, cpuset, domainname, hostname, ipc, mac_address, mem_limit, memswap_limit, oom_score_adj, privileged, read_only, restart, shm_size, stdin_open, tty, user, working_dir

每个都是一个单一的值，类似于它的docker运行对应。

cpu_shares: 73
cpu_quota: 50000
cpuset: 0,1

user: postgresql
working_dir: /code

domainname: foo.com
hostname: foo
ipc: host
mac_address: 02:42:ac:11:65:43

mem_limit: 1000000000
memswap_limit: 2000000000
privileged: true

oom_score_adj: 500

restart: always

read_only: true
shm_size: 64M
stdin_open: true
tty: true

cpu_shares: 73

cpu_quota: 50000

cpuset: 0,1

user: postgresql

working_dir: /code

domainname: foo.com

hostname: foo

ipc: host

mac_address: 02:42:ac:11:65:43

mem_limit: 1000000000

memswap_limit: 2000000000

privileged: true

oom_score_adj: 500

restart: always

read_only: true

shm_size: 64M

stdin_open: true

tty: true

driver

指定应为此卷使用哪个卷驱动程序，默认为local。如果驱动程序不可用，Docker Engine将返回错误。

driver: foobar

1	driver: foobar

三、Variable substitution

你可以在配置中使用具有类似Bash的${VARIABLE}语法使用环境变量。您的配置选项可以包含环境变量。 Compose使用运行docker-compose的shell环境中的变量值。例如，假设shell包含EXTERNAL_PORT = 8000，并且您提供此配置：

web:
  build: .
  ports:
    - "${EXTERNAL_PORT}:5000"

web:

build: .

ports:

- "${EXTERNAL_PORT}:5000"

当使用此配置运行docker-compose up时，Compose会在shell中查找EXTERNAL_PORT环境变量并将其值代入。在本示例中，Compose在创建Web容器之前将端口映射解析为“8000:5000”。

如果未设置环境变量，则Compose将替换为空字符串。在上面的示例中，如果未设置EXTERNAL_PORT，则端口映射的值为:5000（这当然是无效的端口映射，并且将在尝试创建容器时导致错误）。

支持$VARIABLE和${VARIABLE}语法。此外，当使用2.1文件格式时，可以使用典型的shell语法提供内联默认值： * 如果VARIABLE在环境中未设置或为空，${VARIABLE:-default}将评估为默认值。 * 只有在环境中未设置VARIABLE的情况下，${VARIABLE-default}才会评估为默认值。

当您的配置需要一个字母美元符号时，您可以使用$$（双美元符号）。这也防止了Compose内插值，所以$$允许你引用你不想由Compose处理的环境变量。

如果您忘记并使用单个美元符号（$），Compose将该值解释为环境变量并将警告您：

未设置VAR_NOT_INTERPOLATED_BY_COMPOSE。替换空字符串。

<摘抄>

https://deepzz.com/post/docker-compose-file.html#toc_61

https://docs.docker.com/compose/compose-file/compose-file-v2

如果您觉得本站对你有帮助，那么可以支付宝扫码捐助以帮助本站更好地发展，在此谢过。