docker-compose编排语法

文章目录

一、前言

docker compose 在 Docker 容器运用中具有很大的学习意义，docker compose 是一个整合发布应用的利器。而使用 docker compose 时，懂得如何编排 docker compose 配置文件是很重要的。

关于 docker compose 技术可以查看官方文档 Docker Compose

以下的内容是确立在已经下载好 Docker 以及 Docker Compose，可参看 Docker Compose 的官方安装教程 Install Docker Compose

二. Docker Compose 配置文件的构建参数说明

首先，官方提供了一个 docker-compose.yml 配置文件的标准例子

version: "3"
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 文件是一个定义服务、网络和卷的 YAML 文件。Compose 文件的默认路径是 ./docker-compose.yml

可以是用 .yml 或 .yaml 作为文件扩展名

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

正如 docker container create 在 Dockerfile 指定选项，如 CMD、 EXPOSE、VOLUME、ENV，在默认情况下，你不需要再次指定它们docker-compose.yml。

可以使用 Bash 类 ${VARIABLE} 语法在配置值中使用环境变量。

配置选项

[Docker-Compose配置详解官方文档]

2.1 version

指定本yml一从的compose 哪个版本制定的。

2.2 image

services: #定义服务
  web: # web服务
    image: hello-world # 启动服务使用的镜像

指定容器运行的镜像，格式：

image: redis # 镜像名称
image: ubuntu:14.04 #镜像：版本号
image: tutum/influxdb # 个人用户级别的镜像
image: example-registry.com:4000/postgresql # 非官方仓库的镜像
image: a4bc65fd # 镜像ID

2.3 build

服务除了可以基于指定的镜像，还可以基于一份 “Dockerfile” ，在使用 up 启动之时执行构建任务，这个构建标签就是 build，它可以指定 Dockerfile 所在文件夹的路径。Compose 将会利用它自动构建这个镜像，然后使用这个镜像启动服务容器

build: /path/to/build/dir/

也可以是相对路径，只要上下文确定就可以读取到 Dockerfile

build: ./dir
build:
  context: /home/transport或./transport#context:指定Dockerfile文件所在的路径
  dockerfile: Dockerfile#dockerfile:指定context指定的目录下面的Dockerfile的名称(默认为Dockerfile)
args:#args:Dockerf
   args: # 指定输入环境变量
    buildno: 1 # 环境变量
    password: secret # 环境变量
image: webapp:tag # 命名的镜像名称，根据此名称启动

2.4 command 覆盖容器启动的默认命令。

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

2.5 container_name：<项目名称><服务名称><序号>

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

2.6 depends_on设置依赖关系，建立关联，优先级启动

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

docker-compose up ：以依赖性顺序启动服务。在以下示例中，先启动 db 和 redis ，才会启动 web。

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

docker-compose stop ：按依赖关系顺序停止服务。在以下示例中，web 在 db 和 redis 之前停止。

2.7 dns

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

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

2.8 dns_search

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

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

2.9 tmpfs
在容器内安装一个临时文件系统。可以是单个值或列表的多个值。

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

2.10 entrypoint

entrypoint: /code/entrypoint.sh #覆盖容器默认的 entrypoint

2.11 env_file

env_file: .env
从文件添加环境变量。可以是单个值或列表的多个值。

env_file: # 列表格式

env_file: # 列表格式
  - ./common.env
  - ./apps/web.env
  - /opt/secrets.env

2.12 environment：镜像变量

添加环境变量。您可以使用数组或字典、任何布尔值，布尔值需要用引号引起来，以确保 YML 解析器不会将其转换为 True 或 False。

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

2.13 expose

暴露端口的定义，但不映射到宿主机，只被连接的服务访问。
仅可以指定内部端口为参数：

expose:
 - "3000"
 - "8000"

2.14 external_links：链接外部容器

external_links: # 将容器的地址注入到host文件里

external_links: # 将容器的地址注入到host文件里
 - redis_1
 - project_db_1:mysql # 添加别名
 - project_db_1:postgresql

2.15 extra_hosts

添加主机名映射

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

2.16 links：与 Docker client 的 –link 一样效果，会连接到其它服务中的容器

links:
 - db
 - db:database
 - redis

2.17 logging

服务的日志记录配置。

logging:
  driver: syslog # 指定服务容器的日志记录驱动程序，默认值为json-file，有以下三个选项 driver: “json-file”    driver: “syslog”     driver: “none”
  options:
    syslog-address: "tcp://192.168.0.42:123"

2.18 labels

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"

2.19 pid

指定pid名称

pid: "host"

2.20 port

指定端口的暴露

ports:
 - "3000"
 - "8000:8000"
 - "49100:22"
 - "127.0.0.1:8001:8001"

2. 21 security_opt

为每个容器覆盖默认的标签。简单说来就是管理全部服务的标签。比如设置全部服务的user标签值为USER。

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

label:user:USER # 设置容器的用户标签
label:role:ROLE # 设置容器的角色标签
label:type:TYPE # 设置容器的安全策略标签
label:level:LEVEL # 设置容器的安全等级标签

2.22 stop_signal

设置停止容器的替代信号。
stop_signal: SIGUSR1

2.23 volumes

volumes:
  // 只是指定一个路径，Docker 会自动在创建一个数据卷（这个路径是容器内部的）。
  - /var/lib/mysql
 
  // 使用绝对路径挂载数据卷
  - /opt/data:/var/lib/mysql
 
  // 以 Compose 配置文件为中心的相对路径作为数据卷挂载到容器。
  - ./cache:/tmp/cache
 
  // 使用用户的相对路径（~/ 表示的目录是 /home/<用户目录>/ 或者 /root/）。
  - ~/configs:/etc/configs/:ro
 
  // 已经存在的命名的数据卷。
  - datavolume:/var/lib/mysql

2.24 volumes_from

从其它容器或者服务挂载数据卷，可选的参数是 :ro或者 :rw，前者表示容器只读，后者表示容器对数据卷是可读可写的。默认情况下是可读可写的

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

2.25 cap_add, cap_drop

添加或删除容器拥有的宿主机的功能

cap_add:
  - ALL
 
cap_drop:
  - NET_ADMIN # 网络管理员权限
  - SYS_ADMIN

2.26 network_mode

设置网络模式

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

2.27 ulimits

覆盖容器默认的ulimits

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

2.28 extends

连接其他文件

extends:
  file: common.yml
  service: webapp

2.29 networks

配置容器连接的网络，引用顶级 networks 下的条目

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

2.30 stop_grace_period

指定在容器无法处理 SIGTERM (或者任何 stop_signal 的信号)，等待多久后发送 SIGKILL 信号关闭容器
stop_grace_period: 1s # 等待 1 秒
stop_grace_period: 1m30s # 等待 1 分 30 秒
默认的等待时间是 10 秒。

2.31 secrets

存储敏感数据

version: “3.1”
services:

	mysql:
	    image: mysql
	    environment:
 	        MYSQL_ROOT_PASSWORD_FILE: /run/secrets/my_secret
	    secrets:
		    - my_secret
	    secrets:
		   my_secret:
		   file: ./my_secret.txt

2.32 aliases

同一网络上的其他容器可以使用服务名称或此别名来连接到对应容器的服务

2.33 restart

no：是默认的重启策略，在任何情况下都不会重启容器。
always：容器总是重新启动。
on-failure：在容器非正常退出时（退出状态非0），才会重启容器。
unless-stopped：在容器退出时总是重启容器，但是不考虑在Docker守护进程启动时就已经停止了的容器
restart: “no”
restart: always
restart: on-failure
restart: unless-stopped
注：swarm 集群模式，请改用 restart_policy。

2.34 devices

指定设备映射列表。

devices:
“/dev/ttyUSB0:/dev/ttyUSB0”

2.35 healthcheck

用于检测 docker 服务是否健康运行。

healthcheck:
test: [“CMD”, “curl”, “-f”, “http://localhost”] # 设置检测程序
interval: 1m30s # 设置检测间隔
timeout: 10s # 设置检测超时时间
retries: 3 # 设置重试次数
start_period: 40s # 启动后，多少秒开始启动检测程序

2.36 cgroup_parent

为容器指定父 cgroup 组，意味着将继承该组的资源限制。

cgroup_parent: m-executor-abcd

2.37 deploy

指定与docker swarm集群服务的部署和运行有关的配置。

理解:
docker run 单机运行单个容器
docker-compose 单机运行多个容器
docker swarm 集群服务
docker service create  创建集群中的单个服务;
docker stack 管理集群中的多个服务;

version:"3.7"

services:

   redis:

     image:redis:alpine

     deploy:

       replicas:6

       update_config:

         parallelism:2

         delay:10s

       restart_policy:

         condition:on-failure

有几个子选项可供选择：

endpoint_mode(第一个)

endpoint_mode：指定连接到群组外部客户端服务发现方法
endpoint_mode:vip ：Docker 为该服务分配了一个虚拟 IP(VIP),作为客户端的 “前端“ 部位用于访问网络上的服务。
endpoint_mode: dnsrr : DNS轮询（DNSRR）服务发现不使用单个虚拟 IP。Docker为服务设置 DNS 条目，使得服务名称的 DNS 查询返回一个 IP 地址列表，并且客户端直接连接到其中的一个。如果想使用自己的负载平衡器，或者混合 Windows 和 Linux 应用程序，则 DNS 轮询调度（round-robin）功能就非常实用。

version:"3.7"

 

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:

labels(第二种)

指定服务的标签，这些标签仅在服务上设置

version:"3.7"

services:

   web:

     image:web

     deploy:

       labels:

         com.example.description:"Thislabelwillappearonthewebservice"

通过将 deploy 外面的 labels 标签来设置容器上的 labels

version:"3.7"

services:

   web:

     image:web

     labels:

       com.example.description:"Thislabelwillappearonallcontainersforthewebservice"

mode(第三种)

global:每个集节点只有一个容器

replicated:指定容器数量（默认）

version:"3.7"

services:

   worker:

     image:dockersamples/examplevotingapp_worker

     deploy:

       mode:global

placement(第四种)

指定 constraints 和 preferences

version:"3.7"

services:

   db:

     image:postgres

     deploy:

       placement:

         constraints:

           - node.role == manager

           - engine.labels.operatingsystem == ubuntu 14.04

         preferences:

          - spread:node.labels.zone

replicas(第五种)

如果服务是 replicated（默认)，需要指定运行的容器数量

version:"3.7"

services:

   worker:

     image:dockersamples/examplevotingapp_worker

     networks:

       - frontend

       - backend

     deploy:

        mode:replicated

       replicas:6

resources(第六种)

配置资源限制

version:"3.7"

services:

   redis:

     image:redis:alpine

     deploy:

       resources:

         limits:

           cpus:'0.50'

           memory:50M

         reservations:

           cpus:'0.25'

            memory:20M

例子中，redis 服务限制使用不超过 50M 的内存和 0.50（50％）可用处理时间（CPU），并且保留 20M 了内存和 0.25 CPU时间。

2.38 endpoint_mode：访问集群服务的方式。

endpoint_mode: vip
Docker 集群服务一个对外的虚拟 ip。所有的请求都会通过这个虚拟 ip 到达集群服务内部的机器。
endpoint_mode: dnsrr
#DNS 轮询（DNSRR）。所有的请求会自动轮询获取到集群 ip 列表中的一个 ip 地址。

2.39 labels

使用 Docker 标签将元数据添加到容器，可以使用数组或字典。与 Dockerfile 中的 LABELS 类似：

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"

2.40 configs

使用服务 configs 配置为每个服务赋予相应的访问权限，支持两种不同的语法。

Note: 配置必须存在或在 configs 此堆栈文件的顶层中定义，否则堆栈部署失效

SHORT 语法

SHORT 语法只能指定配置名称，这允许容器访问配置并将其安装在 /<config_name> 容器内，源名称和目标装入点都设为配置名称。

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

以上实例使用 SHORT 语法将 redis 服务访问授予 my_config 和 my_other_config ,并被 my_other_config 定义为外部资源，这意味着它已经在 Docker 中定义。可以通过 docker config create 命令或通过另一个堆栈部署。如果外部部署配置都不存在，则堆栈部署会失败并出现 config not found 错误。

Note: config 定义仅在 3.3 版本或在更高版本的撰写文件格式中受支持，YAML 的布尔值（true, false, yes, no, on, off）必须要使用引号引起来（单引号、双引号均可），否则会当成字符串解析。

LONG 语法

LONG 语法提供了创建服务配置的更加详细的信息

source：Docker 中存在的配置的名称
target：要在服务的任务中装载的文件的路径或名称。如果未指定则默认为 /
uid 和 gid：在服务的任务容器中拥有安装的配置文件的数字 UID 或 GID。如果未指定，则默认为在Linux上。Windows不支持。
mode：在服务的任务容器中安装的文件的权限，以八进制表示法。例如，0444 代表文件可读的。默认是 0444。如果配置文件无法写入，是因为它们安装在临时文件系统中，所以如果设置了可写位，它将被忽略。可执行位可以设置。如果您不熟悉 UNIX 文件权限模式，[Unix Permissions Calculator](http://permissions-calculator.org/)

下面示例在容器中将 my_config 名称设置为 redis_config，将模式设置为 0440（group-readable）并将用户和组设置为 103。该 redis 服务无法访问 my_other_config 配置。

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

可以同时授予多个配置的服务相应的访问权限，也可以混合使用 LONG 和 SHORT 语法。定义配置并不意味着授予服务访问权限。

2.42 restart_policy

配置如何在退出容器时重新启动容器。

condition：可选 none，on-failure 或者 any（默认值：any）。
delay：设置多久之后重启（默认值：0）。
max_attempts：尝试重新启动容器的次数，超出次数，则不再尝试（默认值：一直重试）。
window：设置容器重启超时时间（默认值：0）。

2.43 rollback_config

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

parallelism：一次要回滚的容器数。如果设置为0，则所有容器将同时回滚。
delay：每个容器组回滚之间等待的时间（默认为0s）。
failure_action：如果回滚失败，该怎么办。其中一个 continue 或者 pause（默认pause）。
monitor：每个容器更新后，持续观察是否失败了的时间 (ns|us|ms|s|m|h)（默认为0s）。
max_failure_ratio：在回滚期间可以容忍的故障率（默认为0）。
order：回滚期间的操作顺序。其中一个 stop-first（串行回滚），或者 start-first（并行回滚）（默认 stop-first ）。

2.44 update_config

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

parallelism：一次更新的容器数。
delay：在更新一组容器之间等待的时间。
failure_action：如果更新失败，该怎么办。其中一个 continue，rollback 或者pause （默认：pause）。
monitor：每个容器更新后，持续观察是否失败了的时间 (ns|us|ms|s|m|h)（默认为0s）。
max_failure_ratio：在更新过程中可以容忍的故障率。
order：回滚期间的操作顺序。其中一个 stop-first（串行回滚），或者 start-first（并行回滚）（默认stop-first）。
注：仅支持 V3.4 及更高版本。