阅读 17

Compose 文件指南

1.Compose 文件结构和示例

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

2.services部分

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

服务定义包含应用于该服务启动的每个容器的配置,就像将命令行参数传递给docker container create一样。

同样,网络和卷定义类似于docker network createdocker volume create

docker container create一样, Dockerfile指定的选项,比如CMD, EXPOSE, VOLUME, ENV, 无需在docker-compose.yml文件中再次指定他们。

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

bind

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

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

version: "3.7"
services:
  webapp:
    build: ./dir
复制代码

或者,作为一个在上下文中和可选的Dockerfile和args指定了路径的对象:

version: "3.7"
services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1
复制代码

如果你指定了imagebuild,Compose会命名构建的镜像为webapp并打上可选的tag.

build: ./dir
image: webapp:tag
复制代码

这将产生一个从./dir构建的名为webapp和带标签tag的镜像。

CONTEXT

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

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

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

DOCKERFILE

替代Dockerfile。

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

build:
  context: .
  dockerfile: Dockerfile-alternate
复制代码

ARGS

添加构建参数,这些环境变量只能在构建过程中访问。

首先,在Dockerfile中指定参数:

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
复制代码

您可以在指定构建参数时省略该值,在这种情况下,其在构建时的值就是运行Compose的环境中的值。

args:
  - buildno
  - gitcommithash
复制代码

注意:YAML布尔值(true,false,yes,no,on,off)必须用引号引起来,以便解析器将它们解释为字符串。

CACHE_FROM

Note: This option is new in v3.2

引擎用于缓存解析的镜像列表。

build:
  context: .
  cache_from:
    - alpine:latest
    - corp/web_app:3.14
复制代码

LABELS

Note: This option is new in v3.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"
复制代码

SHM_SIZE

Added in version 3.5 file format

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

build:
  context: .
  shm_size: '2gb'
复制代码
build:
  context: .
  shm_size: 10000000
复制代码

TARGET

Added in version 3.4 file format

根据Dockerfile中的定义构建指定的阶段。 有关详细信息,请参见多阶段构建文档。

build:
  context: .
  target: prod
复制代码

cap_add, cap_drop

添加或删除容器功能。

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN
复制代码

cgroup_parent

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

cgroup_parent: m-executor-abcd
复制代码

command

重写默认的命令。

command: bundle exec thin -p 3000
复制代码

该命令也可以是列表,类似于dockerfile:

command: ["bundle", "exec", "thin", "-p", "3000"]
复制代码

configs

使用按服务configs配置,按服务授予对配置的访问权限。 支持两种不同的语法变体。

注意:该配置必须已经存在或已在此堆栈文件的顶级配置配置中定义,否则堆栈部署失败。

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

下面的例子使用的是短语法,授权redis服务访问my_configmy_other_config配置,my_config的值设置为./my_config.txt文件的内容,my_other_config设置为外部的资源,这意味着它已经在Docker中定义过了,使用docker config create命令或者其他栈部署。如果外部配置不存在,该栈部署失败并有一个配置未发现的错误。

注意:config定义仅在version:3.3和更高的版本中支持

version: "3.7"
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: Docker中存在的配置名称。
  • target: 要在服务的任务容器中装载的文件的路径和名称。如果未指定,则默认为/<source >
  • uid and gid:服务的任务容器中拥有已挂载的配置文件的数字UID或GID。 如果未指定,则两者在Linux上均默认为0。 Windows不支持。
  • mode:服务的任务容器中装入的文件的权限,以八进制表示。 例如,0444表示世界可读。 缺省值为0444。配置文件不可写,因为它们已挂载在临时文件系统中,因此,如果设置了可写位,则会将其忽略。 可执行位可以设置。

下面的例子在容器中设置my_config的名称为redis_config.设置模式为0440设置用户和组为103.redis服务没有权限访问my_other_config配置。

version: "3.7"
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容器名称必须是惟一的,因此如果指定了自定义名称,则不能将服务扩展到一个容器之外。尝试这样做会导致错误。

depends_on

表示服务之间的依赖关系,服务依赖关系导致以下行为:

  • docker-compose up以依赖关系的顺序启动服务,在下面的例子中,dbredisweb之前启动。
  • docker-compose up SERVICE自动包含服务的依赖项,在下面的例子中, docker-compose up web同样创建并启动 dbredis.
  • docker-compose stop以依赖关系的顺序停止服务,在下面的例子中,webdb and redis之前停止服务.
version: "3.7"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres
复制代码

使用depends_on时的注意事项: 1.depends_on在启动web服务之前不会等到db和redis服务状态进入到ready. 2.版本3不再支持条件形式。 3.当使用版本3撰写文件以群集模式部署堆栈时,将忽略依赖选项。

deploy

Version 3 only.

指定与服务的部署和运行有关的配置。 这仅在通过docker stack deploy部署到集群时才生效,并且被docker-compose updocker-compose run忽略。

version: "3.7"
services:
  redis:
    image: redis:alpine
    deploy:
      replicas: 6
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure
复制代码

logging

服务的日志配置。

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"
复制代码

driver指定了服务容器的日志记录驱动程序,就像docker run--log-driver选项。

默认值为json-file。

driver: "json-file"
driver: "syslog"
driver: "none"
复制代码

注意: 只有使用json-file 和 journald 驱动的可以使日志可用通过docker-compose up 和 docker-compose logs. 使用其他驱动不会打印任何日志。

使用options选项指定日志驱动的日志选项,就像docker run--log-opt选项。

日志记录选项是键值对。 syslog选项的示例:

driver: "syslog"
options:
  syslog-address: "tcp://192.168.0.42:123"
复制代码

默认驱动程序json-file具有限制存储日志量的选项。 为此,请使用键值对以获取最大存储大小和最大文件数:

options:
  max-size: "200k"
  max-file: "10"
复制代码

上面显示的示例将存储日志文件,直到它们达到最大大小200kB,然后旋转它们。 单个日志文件的存储量由max-file值指定。 随着日志超出最大限制,将删除较旧的日志文件以允许存储新日志。

version: "3.7"
services:
  some-service:
    image: some-service
    logging:
      driver: "json-file"
      options:
        max-size: "200k"
        max-file: "10"
复制代码

network_mode

网络模式。 使用与docker client --network参数相同的值,以及特殊形式的service:[service name]

network_mode: "bridge"
network_mode: "host"
network_mode: "none"
network_mode: "service:[service name]"
network_mode: "container:[container name/id]"
复制代码

networks

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

services:
  some-service:
    networks:
     - some-network
     - other-network
复制代码

在下面的示例中,提供了三个服务(webworkerdb)以及两个网络(newlegacy)。 db服务可以访问在new网络的主机名为db或者database的主机,可以访问legacy网络的主机名为db或者mysql的主机。

version: "3.7"

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_ADDRESS, IPV6_ADDRESS

加入网络后,为此服务的容器指定一个静态IP地址。

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

如果需要IPv6寻址,则必须设置enable_ipv6选项,并且您必须使用2.x版本的Compose文件。 IPv6选项当前在群集模式下不起作用。

version: "3.7"

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"
复制代码

volumes

挂载主机路径或命名卷,指定为服务的子选项。

您可以将主机路径作为单个服务定义的一部分挂载,并且不需要在顶级卷键中定义它。

但是,如果要在多个服务之间重用卷,请在顶级卷键中定义一个命名卷。 将命名卷与服务,群集和堆栈文件一起使用。

这个例子展示了一个命名卷mydataweb服务中的使用,还有在单个服务中的一个绑定挂载(db服务下的volumes下的第一个路径)。db服务还使用了一个命名卷dbdata(db服务下的volumes下的第二个路径),但是挂载一个命名卷使用的是老的字符串形式定义的。命令卷需要在顶级volumes键下罗列出,就像下面那样:

version: "3.7"
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:
复制代码