├── LICENSE ├── README-v3.7.md ├── README.md └── README_en.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 hz 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README-v3.7.md: -------------------------------------------------------------------------------- 1 | # docker-compose 编排指南 (v3.7) 2 | 3 | 4 | 5 | ## 缘起 6 | 7 | 关于 docker-compose 的安装，关于 docker 的基本介绍，不在本文的指导范围内。 8 | 9 | 这篇文章基本上是 docker-compose YAML 文件格式的严格的英译中。这么做，缘起于昨天想起扫描一下 docker-compose 编排中怎么使用 `${PWD}` 的问题，结果中文没有一点帮助，还是官网最终解决了我的模糊之处。因此我觉得还是应该做一篇比较严谨的译文以及说明，来阐释 docker-compose 编排的各项细节。 10 | 11 | 以下，我们主要是介绍 [docker-compose 编排文件格式版本3](https://docs.docker.com/compose/compose-file/) 的各项细节。 12 | 13 | 阅读本文，你应该有 docker-compose 的基本认识，至少有基本的早期（版本2）编排格式的了解。 14 | 15 | ### 关于授权 16 | 17 | 译文从属于原文 https://docs.docker.com/compose/compose-file/ 。 18 | 19 | [译文 https://github.com/hedzr/docker-compose-file-format](https://github.com/hedzr/docker-compose-file-format) 本身以 MIT 方式分发。 20 | 21 | 22 | 23 | ## Table of Contents 24 | 25 | * [docker\-compose 编排指南 (v3\.7)](#docker-compose-%E7%BC%96%E6%8E%92%E6%8C%87%E5%8D%97-v37) 26 | * [缘起](#%E7%BC%98%E8%B5%B7) 27 | * [关于授权](#%E5%85%B3%E4%BA%8E%E6%8E%88%E6%9D%83) 28 | * [Table of Contents](#table-of-contents) 29 | * [编排格式版本3](#%E7%BC%96%E6%8E%92%E6%A0%BC%E5%BC%8F%E7%89%88%E6%9C%AC3) 30 | * [历史](#%E5%8E%86%E5%8F%B2) 31 | * [特别添加](#%E7%89%B9%E5%88%AB%E6%B7%BB%E5%8A%A0) 32 | * [编排文件结构与示例](#%E7%BC%96%E6%8E%92%E6%96%87%E4%BB%B6%E7%BB%93%E6%9E%84%E4%B8%8E%E7%A4%BA%E4%BE%8B) 33 | * [[Dockerfile] 关于 ENTRYPOINT 和 CMD](#dockerfile-%E5%85%B3%E4%BA%8E-entrypoint-%E5%92%8C-cmd) 34 | * [Docker RUN vs CMD vs ENTRYPOINT \- Go in Big Data](#docker-run-vs-cmd-vs-entrypoint---go-in-big-data) 35 | * [In a nutshell](#in-a-nutshell) 36 | * [典型用法](#%E5%85%B8%E5%9E%8B%E7%94%A8%E6%B3%95) 37 | * [用于你的容器](#%E7%94%A8%E4%BA%8E%E4%BD%A0%E7%9A%84%E5%AE%B9%E5%99%A8) 38 | * [[Dockerfile] 多遍构建](#dockerfile-%E5%A4%9A%E9%81%8D%E6%9E%84%E5%BB%BA) 39 | * [编排格式手册 \- service](#%E7%BC%96%E6%8E%92%E6%A0%BC%E5%BC%8F%E6%89%8B%E5%86%8C---service) 40 | * [build](#build) 41 | * [context](#context) 42 | * [dockerfile](#dockerfile) 43 | * [args](#args) 44 | * [cache\_from](#cache_from) 45 | * [labels](#labels) 46 | * [shm\_size](#shm_size) 47 | * [target](#target) 48 | * [cap\_add, cap\_drop](#cap_add-cap_drop) 49 | * [cgroup\_parent](#cgroup_parent) 50 | * [command](#command) 51 | * [configs](#configs) 52 | * [短格式](#%E7%9F%AD%E6%A0%BC%E5%BC%8F) 53 | * [长格式](#%E9%95%BF%E6%A0%BC%E5%BC%8F) 54 | * [container\_name](#container_name) 55 | * [credential\_spec](#credential_spec) 56 | * [gMSA 配置例子](#gmsa-%E9%85%8D%E7%BD%AE%E4%BE%8B%E5%AD%90) 57 | * [depends\_on](#depends_on) 58 | * [deploy](#deploy) 59 | * [endpoint\_mode](#endpoint_mode) 60 | * [labels](#labels-1) 61 | * [mode](#mode) 62 | * [placement](#placement) 63 | * [replicas](#replicas) 64 | * [resources](#resources) 65 | * [Out Of Memory Exceptions (OOME)](#out-of-memory-exceptions-oome) 66 | * [restart\_policy](#restart_policy) 67 | * [rollback\_config](#rollback_config) 68 | * [update\_config](#update_config) 69 | * [NOT SUPPORTED FOR DOCKER STACK DEPLOY](#not-supported-for-docker-stack-deploy) 70 | * [devices](#devices) 71 | * [dns](#dns) 72 | * [dns\_search](#dns_search) 73 | * [entrypoint](#entrypoint) 74 | * [env\_file](#env_file) 75 | * [environment](#environment) 76 | * [expose](#expose) 77 | * [external\_links](#external_links) 78 | * [extra\_hosts](#extra_hosts) 79 | * [healthcheck](#healthcheck) 80 | * [image](#image) 81 | * [init](#init) 82 | * [isolation](#isolation) 83 | * [labels](#labels-2) 84 | * [links](#links) 85 | * [logging](#logging) 86 | * [network\_mode](#network_mode) 87 | * [networks](#networks) 88 | * [ALIASES](#aliases) 89 | * [IPV4\_ADDRESS, IPV6\_ADDRESS](#ipv4_address-ipv6_address) 90 | * [pid](#pid) 91 | * [ports](#ports) 92 | * [短格式](#%E7%9F%AD%E6%A0%BC%E5%BC%8F-1) 93 | * [长格式](#%E9%95%BF%E6%A0%BC%E5%BC%8F-1) 94 | * [restart](#restart) 95 | * [secrets](#secrets) 96 | * [短格式](#%E7%9F%AD%E6%A0%BC%E5%BC%8F-2) 97 | * [长格式](#%E9%95%BF%E6%A0%BC%E5%BC%8F-2) 98 | * [security\_opt](#security_opt) 99 | * [stop\_grace\_period](#stop_grace_period) 100 | * [stop\_signal](#stop_signal) 101 | * [sysctls](#sysctls) 102 | * [tmpfs](#tmpfs) 103 | * [ulimits](#ulimits) 104 | * [userns\_mode](#userns_mode) 105 | * [volumes](#volumes) 106 | * [短格式](#%E7%9F%AD%E6%A0%BC%E5%BC%8F-3) 107 | * [长格式](#%E9%95%BF%E6%A0%BC%E5%BC%8F-3) 108 | * [VOLUMES FOR SERVICES, SWARMS, AND STACK FILES](#volumes-for-services-swarms-and-stack-files) 109 | * [CACHING OPTIONS FOR VOLUME MOUNTS (DOCKER DESKTOP FOR MAC)](#caching-options-for-volume-mounts-docker-desktop-for-mac) 110 | * [domainname, hostname, ipc, mac\_address, privileged, read\_only, shm\_size, stdin\_open, tty, user, working\_dir](#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir) 111 | * [指定时间段 duration](#%E6%8C%87%E5%AE%9A%E6%97%B6%E9%97%B4%E6%AE%B5-duration) 112 | * [指定字节值](#%E6%8C%87%E5%AE%9A%E5%AD%97%E8%8A%82%E5%80%BC) 113 | * [卷编排格式手册 \- volumes](#%E5%8D%B7%E7%BC%96%E6%8E%92%E6%A0%BC%E5%BC%8F%E6%89%8B%E5%86%8C---volumes) 114 | * [driver](#driver) 115 | * [driver\_opts](#driver_opts) 116 | * [external](#external) 117 | * [labels](#labels-3) 118 | * [name](#name) 119 | * [网络编排格式手册 \- networks](#%E7%BD%91%E7%BB%9C%E7%BC%96%E6%8E%92%E6%A0%BC%E5%BC%8F%E6%89%8B%E5%86%8C---networks) 120 | * [driver](#driver-1) 121 | * [bridge](#bridge) 122 | * [overlay](#overlay) 123 | * [host or none](#host-or-none) 124 | * [driver\_opts](#driver_opts-1) 125 | * [attachable](#attachable) 126 | * [enable\_ipv6](#enable_ipv6) 127 | * [ipam](#ipam) 128 | * [internal](#internal) 129 | * [labels](#labels-4) 130 | * [external](#external-1) 131 | * [name](#name-1) 132 | * [配置项编排格式手册 \- configs](#%E9%85%8D%E7%BD%AE%E9%A1%B9%E7%BC%96%E6%8E%92%E6%A0%BC%E5%BC%8F%E6%89%8B%E5%86%8C---configs) 133 | * [敏感信息项编排格式手册 \- secrets](#%E6%95%8F%E6%84%9F%E4%BF%A1%E6%81%AF%E9%A1%B9%E7%BC%96%E6%8E%92%E6%A0%BC%E5%BC%8F%E6%89%8B%E5%86%8C---secrets) 134 | * [Compose File v3\.5 及更高版本](#compose-file-v35-%E5%8F%8A%E6%9B%B4%E9%AB%98%E7%89%88%E6%9C%AC) 135 | * [Compose File v3\.4 和更低版本](#compose-file-v34-%E5%92%8C%E6%9B%B4%E4%BD%8E%E7%89%88%E6%9C%AC) 136 | * [变量替换](#%E5%8F%98%E9%87%8F%E6%9B%BF%E6%8D%A2) 137 | * [扩展字段](#%E6%89%A9%E5%B1%95%E5%AD%97%E6%AE%B5) 138 | * [Compose 文档参考](#compose-%E6%96%87%E6%A1%A3%E5%8F%82%E8%80%83) 139 | * [结束](#%E7%BB%93%E6%9D%9F) 140 | 141 | 142 | 143 |  144 | 145 | 146 | 147 | ## 编排格式版本3 148 | 149 | ### 历史 150 | 151 | 版本3是自 docker-engine 1.13 推出以来 docker-compose 所支持的格式。这之前 docker 在 1.12 中推出了 swarm mode 来构建一个虚拟网络中的虚拟计算资源，同时也大幅度改进了 docker 的网络以及存储的支持。 152 | 153 | 对于 docker-compose 编排格式与 docker-engine 之间的关系，下面这张表（摘自官网）有清晰的对照。 154 | 155 | | **Compose file format** | **Docker Engine release** | 156 | | :---------------------- | :------------------------ | 157 | | 3.7 | 18.06.0+ | 158 | | 3.6 | 18.02.0+ | 159 | | 3.5 | 17.12.0+ | 160 | | 3.4 | 17.09.0+ | 161 | | 3.3 | 17.06.0+ | 162 | | 3.2 | 17.04.0+ | 163 | | 3.1 | 1.13.1+ | 164 | | 3.0 | 1.13.0+ | 165 | | 2.4 | 17.12.0+ | 166 | | 2.3 | 17.06.0+ | 167 | | 2.2 | 1.13.0+ | 168 | | 2.1 | 1.12.0+ | 169 | | 2.0 | 1.10.0+ | 170 | | 1.0 | 1.9.1.+ | 171 | 172 | 173 | 174 | ## 特别添加 175 | 176 | ### 编排文件结构与示例 177 | 178 | 这是一个版本3+的典型文件结构样本： 179 | 180 | ```yaml 181 | version: "3.7" 182 | services: 183 | 184 | redis: 185 | image: redis:alpine 186 | ports: 187 | - "6379" 188 | networks: 189 | - frontend 190 | deploy: 191 | replicas: 2 192 | update_config: 193 | parallelism: 2 194 | delay: 10s 195 | restart_policy: 196 | condition: on-failure 197 | 198 | db: 199 | image: postgres:9.4 200 | volumes: 201 | - db-data:/var/lib/postgresql/data 202 | networks: 203 | - backend 204 | deploy: 205 | placement: 206 | constraints: [node.role == manager] 207 | 208 | vote: 209 | image: dockersamples/examplevotingapp_vote:before 210 | ports: 211 | - "5000:80" 212 | networks: 213 | - frontend 214 | depends_on: 215 | - redis 216 | deploy: 217 | replicas: 2 218 | update_config: 219 | parallelism: 2 220 | restart_policy: 221 | condition: on-failure 222 | 223 | result: 224 | image: dockersamples/examplevotingapp_result:before 225 | ports: 226 | - "5001:80" 227 | networks: 228 | - backend 229 | depends_on: 230 | - db 231 | deploy: 232 | replicas: 1 233 | update_config: 234 | parallelism: 2 235 | delay: 10s 236 | restart_policy: 237 | condition: on-failure 238 | 239 | worker: 240 | image: dockersamples/examplevotingapp_worker 241 | networks: 242 | - frontend 243 | - backend 244 | deploy: 245 | mode: replicated 246 | replicas: 1 247 | labels: [APP=VOTING] 248 | restart_policy: 249 | condition: on-failure 250 | delay: 10s 251 | max_attempts: 3 252 | window: 120s 253 | placement: 254 | constraints: [node.role == manager] 255 | 256 | visualizer: 257 | image: dockersamples/visualizer:stable 258 | ports: 259 | - "8080:8080" 260 | stop_grace_period: 1m30s 261 | volumes: 262 | - "/var/run/docker.sock:/var/run/docker.sock" 263 | deploy: 264 | placement: 265 | constraints: [node.role == manager] 266 | 267 | networks: 268 | frontend: 269 | backend: 270 | 271 | volumes: 272 | db-data: 273 | ``` 274 | 275 | 276 | 277 | 在这个样本中，顶级结构由 `version`，`services`，`networks`，`volumes` 等等标签构成。这与版本2并没有什么翻天覆地的区别。 278 | 279 | 280 | 281 | 在 `services` 章节中，你可以定义若干个服务，每个服务通常运转着一个容器，这些服务构成了一个整体的设施栈，又或是服务群。 282 | 283 | 一般来说我们会把一堆拉拉杂杂的东西，例如一堆微服务什么的，编排成一个服务栈，让他们整体对外服务，从而避免细节外露，也可以加强架构设计弹性和对整个服务栈进行伸缩（而不是面对大批微服务去逐个处理）。 284 | 285 | 286 | 287 | ### [Dockerfile] 关于 `ENTRYPOINT` 和 `CMD` 288 | 289 |  290 | 291 | #### [**Docker RUN vs CMD vs ENTRYPOINT - Go in Big Data**](https://goinbigdata.com/docker-run-vs-cmd-vs-entrypoint/) 292 | 293 | ##### In a nutshell 294 | 295 | - RUN executes command(s) in a new layer and creates a new image. E.g., it is often used for installing software packages. 296 | - CMD sets default command and/or parameters, which can be overwritten from command line when docker container runs. 297 | - ENTRYPOINT configures a container that will run as an executable. 298 | 299 | 在 Dockerfile 中讨论这三条命令： 300 | 301 | 首先，`RUN` 不考虑，其用途可以被视作执行一条Shell指令。 302 | 303 | `CMD` 和 `ENTRYPOING` 相似但实际上区别较大：`CMD` 指定默认命令及其命令行参数、或者命令行参数的结尾的部分，并且能够在启动容器时被覆盖（通过外部命令行指定的方式），`ENTRYPOINT` 指定该容器被运行时的启动命令，可以附带命令行参数，这条命令在被实际执行时还会附加 `CMD` 所指定的内容作为其命令行的结尾部分。 304 | 305 | 306 | 307 | #### 典型用法 308 | 309 | 所以一个惯用法是： 310 | 311 | ```dockerfile 312 | ENTRYPOINT ["/bin/echo", "Hello"] 313 | CMD ["world"] 314 | ``` 315 | 316 | 然后执行该容器的效果类似于： 317 | 318 | ```bash 319 | $ docker run -it test-container 320 | Hello world 321 | $ docker run -it test-container David 322 | Hello David 323 | ``` 324 | 325 | 326 | 327 | #### 用于你的容器 328 | 329 | 所以对于自定义容器来说，你的主要应用程序的路径可以被用作 `ENTRYPOINT` 而在 `CMD` 中提供默认参数： 330 | 331 | ```dockerfile 332 | ENTRYPOINT ["/usr/local/app/my-app"] 333 | CMD ["--help"] 334 | ``` 335 | 336 | 这将会包装你的 my-app 像一个外露的工具，默认时显示其帮助屏，你可以指定参数去运行 my-app： 337 | 338 | ```bash 339 | $ docker run -it my-app-container 340 | [... help screen here ...] 341 | $ docker run -it my-app-container server run --foreground 342 | [ 等同于执行 my-app server run --foreground ] 343 | ``` 344 | 345 | END 346 | 347 |  348 | 349 | 350 | 351 | ### [Dockerfile] 多遍构建 352 | 353 |  354 | 355 | 多遍构建被典型地用于CI/CD。 356 | 357 | 例如步骤0可以被命名为 `builder`，负责从源码编译到目标文件，而步骤1则从步骤0中抽出目标文件用于部署打包，并生成最终的容器镜像，随后步骤0的中间层则被抛弃（仅指不被打包在结果容器中，实际上这些中间层在 Docker 的构建缓存中仍然是存在且可以被重用的），这些中间层不会出现在最终容器镜像中，从而有效地缩减了最终容器镜像的尺寸，而这个结果也是从语义上、从逻辑上被自洽的。 358 | 359 | ```yaml 360 | FROM golang:1.7.3 AS builder 361 | WORKDIR /go/src/github.com/alexellis/href-counter/ 362 | RUN go get -d -v golang.org/x/net/html 363 | COPY app.go . 364 | RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app . 365 | 366 | FROM alpine:latest 367 | RUN apk --no-cache add ca-certificates 368 | WORKDIR /root/ 369 | COPY --from=builder /go/src/github.com/alexellis/href-counter/app . 370 | CMD ["./app"] 371 | ``` 372 | 373 |  374 | 375 | 376 | 377 | 378 | 379 | ## 编排格式手册 - `service` 380 | 381 | 接下来会是一个参考手册应有的章节结构，我们按照字母顺序列列举出了服务编排的指令，例如 `ports`，`volumes`，`cmd`，`entry` 等等。 382 | 383 | 384 | 385 | ### `build` 386 | 387 | 该选项被用于构建。 388 | 389 | `build` 可以是一个指向构建上下文的路径字符串，例如： 390 | 391 | ```yaml 392 | version: "3.7" 393 | services: 394 | webapp: 395 | build: ./dir 396 | ``` 397 | 398 | 也可以是一个更详细的定义。这包括了 `context` 项所指定的路径，以及可选的 `dockerfile` 文件和构建参数 `args`： 399 | 400 | ```yaml 401 | version: "3.7" 402 | services: 403 | webapp: 404 | build: 405 | context: ./dir 406 | dockerfile: Dockerfile-alternate 407 | args: 408 | buildno: 1 409 | ``` 410 | 411 | 如果你在指定了 `build` 的同时还指定了 `image`，那么构建的结果会被标记为相应的名字，这就好像 `docker build -t container-name:tag dir` 做的那样： 412 | 413 | ```yaml 414 | build: "./dir" 415 | image: "company/webapp:v1.1.9" 416 | ``` 417 | 418 | > 对于 YAML 而言，避免歧义的安全做法是对字符串加上引号包围。 419 | 420 | 上面这个例子，会找到 `./dir` 文件夹中的构建上下文（默认是寻找到 `Dockerfile`）并完成构建，最后将其标记为 `company/webapp` 的名字，以及 `v1.1.9` 的 Tag。 421 | 422 | > **NOTE** 当用在docker stack部署场景时： 423 | > 424 | > `build` 选项会被忽略。 425 | 426 | 427 | 428 | #### `context` 429 | 430 | 可以是一个包含 `Dockerfile` 的文件夹，也可以是一个指向 git repository 的 URL。 431 | 432 | 如果指定了一个相对路径，那么这个路径是相对于 `docker-compose.yml` 文件的。这个路径也会被传送给 Docker daemon 用于进行构建。 433 | 434 | docker-compose 发动构建动作和标记构建结果（按照`image`名字），在那之后按照对应的名字使用它。 435 | 436 | ```yaml 437 | build: 438 | context: ./dir 439 | ``` 440 | 441 | 442 | 443 | #### `dockerfile` 444 | 445 | 可以指定不同于默认名称 `Dockerfile` 的其它文件名用于构建。注意同时必须指定路径到 `context`： 446 | 447 | ```yaml 448 | build: 449 | context: . 450 | dockerfile: Dockerfile-alternate 451 | ``` 452 | 453 | 454 | 455 | #### `args` 456 | 457 | 指定构建参数。通常是指用于构建时的参数（参见 Dockerfile 中的 `ARG`）。 458 | 459 | 以下是一个简要的概述： 460 | 461 | 首先，在 Dockerfile 指定参数： 462 | 463 | ```dockerfile 464 | ARG buildno 465 | ARG gitcommithash 466 | 467 | RUN echo "Build number: $buildno" 468 | RUN echo "Based on commit: $gitcommithash" 469 | ``` 470 | 471 | 然后指定构建参数的实际值（传入Map或者数组都是可以的）： 472 | 473 | ```yaml 474 | build: 475 | context: . 476 | args: 477 | buildno: 1 478 | gitcommithash: cdc3b19 479 | ``` 480 | 481 | 或： 482 | 483 | ```yaml 484 | build: 485 | context: . 486 | args: 487 | - buildno=1 488 | - gitcommithash=cdc3b19 489 | ``` 490 | 491 | > **NOTE**: 在 Dockerfile中，如果在 `FROM` 之前指定 `ARG`，那么这个 `ARG` 对于其后的 `FROM` 闭包是无效的。 492 | > 493 | > 多个 `FROM` 分别切割出了多个构建的闭包。 494 | > 495 | > 想要 `ARG` 在每个 `FROM` 闭包中都有效，你需要在每个闭包中都指定它。 496 | > 497 | > 在 [Understand how ARGS and FROM interact](https://docs.docker.com/engine/reference/builder/#understand-how-arg-and-from-interact) 中有更详细的相关讨论。 498 | 499 | 你可以略过显式指定构建参数。此时，该参数的实际值取决于构建时运行环境。 500 | 501 | ```yaml 502 | args: 503 | - buildno 504 | - gitcommithash 505 | ``` 506 | 507 | > **NOTE**: YAML的布尔量（`true`, `false`, `yes`, `no`, `on`, `off`）必须用引号包围，以便 docker-compose正确处理。 508 | 509 | 510 | 511 | #### `cache_from` 512 | 513 | > since v3.2 514 | 515 | 指定一个映像列表，用于缓存的解决。 516 | 517 | ```yaml 518 | build: 519 | context: . 520 | cache_from: 521 | - alpine:latest 522 | - corp/web_app:3.14 523 | ``` 524 | 525 | 526 | 527 | #### `labels` 528 | 529 | > since v3.3 530 | 531 | 向构建的映像中添加元数据标签，可以是一个数组或一个字典。 532 | 533 | 我们推荐使用反向DNS标注性前缀以防止你的标签和使用者的标签相冲突： 534 | 535 | ```yaml 536 | build: 537 | context: . 538 | labels: 539 | com.example.description: "Accounting webapp" 540 | com.example.department: "Finance" 541 | com.example.label-with-empty-value: "" 542 | 543 | # anothor example 544 | build: 545 | context: . 546 | labels: 547 | - "com.example.description=Accounting webapp" 548 | - "com.example.department=Finance" 549 | - "com.example.label-with-empty-value" 550 | ``` 551 | 552 | 553 | 554 | #### `shm_size` 555 | 556 | > since v3.5 557 | 558 | 设置构建容器时的 `/dev/shm` 分区大小。整数格式按字节表示，但也可以使用字符串格式（[byte value](https://docs.docker.com/compose/compose-file/#specifying-byte-values)）： 559 | 560 | ```yaml 561 | build: 562 | context: . 563 | shm_size: '2gb' 564 | 565 | build: 566 | context: . 567 | shm_size: 10000000 568 | ``` 569 | 570 | 571 | 572 | #### `target` 573 | 574 | > since v3.4 575 | 576 | 构建定义与 Dockerfile 中的特定的步骤（Stage），参阅 [multi-stage build docs](https://docs.docker.com/engine/userguide/eng-image/multistage-build/)： 577 | 578 | ```yaml 579 | build: 580 | context: . 581 | target: prod 582 | ``` 583 | 584 | 585 | 586 | ### `cap_add`, `cap_drop` 587 | 588 | 添加或者移除容器的 Linux 能力。完整的清单可以参阅 `man 7 capabilities`。 589 | 590 | ```yaml 591 | cap_add: 592 | - ALL 593 | 594 | cap_drop: 595 | - NET_ADMIN 596 | - SYS_ADMIN 597 | ``` 598 | 599 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 600 | > 601 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 602 | 603 | Linux 能力机制很大程度上是一种安全机制。具体含义、用途和引申属于 Linux 操作系统范畴，不再赘述。 604 | 605 | 606 | 607 | ### `cgroup_parent` 608 | 609 | 可选地为容器指定一个上级 `cgroup`。`cgroup` 也是 Linux 容器化实现的最重要的基本概念之一。 610 | 611 | ```yaml 612 | cgroup_parent: m-executor-abcd 613 | ``` 614 | 615 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 616 | > 617 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 618 | 619 | 620 | 621 | ### `command` 622 | 623 | 覆盖容器内默认的 `command`. 624 | 625 | ```yaml 626 | command: bundle exec thin -p 3000 627 | ``` 628 | 629 | `command` 也可以被指定为一个列表。实际上这也是更被推荐的方式，无歧义而且安全，而且和 dockerfile 中的格式具有一致性： 630 | 631 | ```yaml 632 | command: ["bundle", "exec", "thin", "-p", "3000"] 633 | ``` 634 | 635 | 636 | 637 | ### configs 638 | 639 | 为每个服务提供具体化的访问 `config` 的权限。 640 | 641 | 一个 `config` 包含一系列的配置信息，这些信息可能被通过多种途径所创建。容器的部署引用这些配置时，可以更好地区格诸如生产环境参数这样的问题。另一方面，敏感信息也因此可以被单独隔离到一个安全的区域中，在一定程度上减少了泄露的可能性。 642 | 643 | > **NOTE**: 指定的配置必须已经存在，或者已经被定义在顶级 `configs` 中了（[defined in the top-level `configs` configuration](https://docs.docker.com/compose/compose-file/#configs-configuration-reference)）。否则整个容器栈的部署将会失败。 644 | 645 | 支持两个不同的语法变体格式。更详尽的信息应参考 [configs](https://docs.docker.com/engine/swarm/configs/)。 646 | 647 | #### 短格式 648 | 649 | 只指定配置名。容器因此可以访问配置 `/ **Note**: `config` 定义仅在 v3.3 及更高版本的 docker-compose 格式中被支持。 673 | 674 | 675 | 676 | #### 长格式 677 | 678 | 长格式提供更多的信息来表述一个 `config` 在哪儿，如何被找到，怎么被使用： 679 | 680 | - `source`: 配置名 681 | 682 | - `target`: 该配置将被挂载到容器中的路径。默认为 `/` 683 | 684 | - `uid` & `gid`: 数字值的 Linux/Unix `UID` 和 `GID`，如果没有指定则为0。Windows中不支持。 685 | 686 | - `mode`: 8进制的文件权限。默认值为 `0444`。 687 | 688 | 配置是不可写的，因为它们被挂载于临时的文件系统中。因此如果你设置了写许可，这将被忽略。 689 | 690 | 可执行位是可以被设置的。 691 | 692 | 下面的例子类似于短格式的例子： 693 | 694 | ```yaml 695 | version: "3.7" 696 | services: 697 | redis: 698 | image: redis:latest 699 | deploy: 700 | replicas: 1 701 | configs: 702 | - source: my_config 703 | target: /redis_config 704 | uid: '103' 705 | gid: '103' 706 | mode: 0440 707 | configs: 708 | my_config: 709 | file: ./my_config.txt 710 | my_other_config: 711 | external: true 712 | ``` 713 | 714 | 在这里，`redis` 容器的服务并未访问 `my_other_config`。 715 | 716 | 你可以授权一个服务访问多个配置，你也可以混用长短格式。 717 | 718 | （在顶级）定义一个配置（`config`）并未隐含着某个服务就能访问到它。 719 | 720 | 721 | 722 | ### `container_name` 723 | 724 | 指定一个自定义的容器名，而不是由 docker-compose 自己生成一个默认的。 725 | 726 | ```yaml 727 | container_name: my-web-container 728 | ``` 729 | 730 | 由于 Docker 容器名必须是唯一的，所以你无法伸缩一个自定义了容器名的服务。 731 | 732 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 733 | > 734 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 735 | 736 | 737 | 738 | ### `credential_spec` 739 | 740 | > since v3.3 741 | > 742 | > 从 v3.8 开始支持被用于组管理服务账户 gMSA（group Managed Service Account）方式。 743 | 744 | 为受控服务账户配置凭据。这个选项只被用于 Windows 容器服务。`credential_spce` 只能使用格式 `file://` or `registry://`。 745 | 746 | 当使用 `file:` 时，被参考的文件必须被置于 Docker 数据文件夹（通常是 `C:\ProgramData\Docker\`）的 `CredentialSpec` 子目录之下。下面的例子将会从 `C:\ProgramData\Docker\CredentialSpecs\my-credential-sp` 载入凭据信息： 747 | 748 | ```yaml 749 | credential_spec: 750 | file: my-credential-spec.json 751 | ``` 752 | 753 | 当使用 `registry:` 时，凭据信息将会被从 Docker daemon 主机的 Windows Registry 中读入。一个注册表表项必须位于： 754 | 755 | ``` 756 | HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs 757 | ``` 758 | 759 | 之中。 760 | 761 | 下面的例子读入 `my-credential-spec` 注册表项值： 762 | 763 | ```yaml 764 | credential_spec: 765 | registry: my-credential-spec 766 | ``` 767 | 768 | 769 | 770 | #### gMSA 配置例子 771 | 772 | 当为一个服务配置 gMSA 凭据时，参考如下的例子： 773 | 774 | ```yaml 775 | version: "3.8" 776 | services: 777 | myservice: 778 | image: myimage:latest 779 | credential_spec: 780 | config: my_credential_spec 781 | 782 | configs: 783 | my_credentials_spec: 784 | file: ./my-credential-spec.json| 785 | ``` 786 | 787 | 788 | 789 | ### `depends_on` 790 | 791 | 表示服务之间的依赖关系。服务依赖引发如下的行为： 792 | 793 | - `docker-compose up` 按照依赖顺序依次启动服务。在下面的例子中，`db` 和 `redis` 先于 `web` 被启动。 794 | - `docker-compose up SERVICE` 自动包括了 `SERVICE` 的依赖项。在下面的例子中，`docker-compose up web` 将会自动启动 `db` 和 `redis`。 795 | - `docker-compose stop` 按照依赖顺序依次停止服务。在下面的例子中，`web` 将会被先于 `db` 和 `redis` 被停止。 796 | 797 | 简单的示例如下： 798 | 799 | ```yaml 800 | version: "3.7" 801 | services: 802 | web: 803 | build: . 804 | depends_on: 805 | - db 806 | - redis 807 | redis: 808 | image: redis 809 | db: 810 | image: postgres 811 | ``` 812 | 813 | > 使用 `depends_on` 时应该注意的几件事： 814 | > 815 | > - `depends_on` 并不意味着等待 `db` 和 `redis` 就绪后才启动 `web`，而是在它们被启动后就会接着启动 `web`。如果要想等到服务就绪可用，应该参阅 [Controlling startup order](https://docs.docker.com/compose/startup-order/)。 816 | > 817 | > - 版本 3 不再支持 `condition` 表述。 818 | > 819 | > - `depends_on` 选项在部署到 swarm mode 时被忽略。 820 | > 821 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 822 | 823 | 824 | 825 | ### `deploy` 826 | 827 | > **[Version 3](https://docs.docker.com/compose/compose-file/compose-versioning/#version-3) only.** 828 | 829 | 指定和部署以及运行相关的配置。 830 | 831 | 只会对部署到一个使用 [docker stack deploy](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 的 [swarm](https://docs.docker.com/engine/swarm/) 有影响。 832 | 833 | 在 `docker-compose up` 和 `docker-compose run` 时被忽略。 834 | 835 | ```yaml 836 | version: "3.7" 837 | services: 838 | redis: 839 | image: redis:alpine 840 | deploy: 841 | replicas: 6 842 | update_config: 843 | parallelism: 2 844 | delay: 10s 845 | restart_policy: 846 | condition: on-failure 847 | ``` 848 | 849 | 几个子选项是可用的： 850 | 851 | #### `endpoint_mode` 852 | 853 | swarm. 854 | 855 | > **[Version 3.3](https://docs.docker.com/compose/compose-file/compose-versioning/#version-3) only.** 856 | 857 | - `endpoint_mode: vip` - Docker 为服务请求一个虚拟IP（`VIP`）用于访问。 858 | 859 | Docker在客户端和服务的有效的工作节点之间对请求进行自动负载均衡路由。客户端无需知道服务有多少可用节点，也不必知道服务节点的IP地址和端口号。 860 | 861 | 这是默认方式。 862 | 863 | - `endpoint_mode: dnsrr` - 使用 DNS round-robin (DNSRR) 算法进行服务发现。Docker会为服务设置一个DNS条目，因而在进行对应的 DNS 解析时通过服务名称会返回一个IP地址清单。客户端因此直接选择一个具体的端点进行访问。 864 | 865 | ```yaml 866 | version: "3.7" 867 | 868 | services: 869 | wordpress: 870 | image: wordpress 871 | ports: 872 | - "8080:80" 873 | networks: 874 | - overlay 875 | deploy: 876 | mode: replicated 877 | replicas: 2 878 | endpoint_mode: vip 879 | 880 | mysql: 881 | image: mysql 882 | volumes: 883 | - db-data:/var/lib/mysql/data 884 | networks: 885 | - overlay 886 | deploy: 887 | mode: replicated 888 | replicas: 2 889 | endpoint_mode: dnsrr 890 | 891 | volumes: 892 | db-data: 893 | 894 | networks: 895 | overlay: 896 | ``` 897 | 898 | `endpoint_mode` 的选项也被同样地用作 swarm mode 命令行选项（参阅 [`docker service create`](https://docs.docker.com/engine/reference/commandline/service_create/)）。至于 docker swarm命令的一个快捷清单，可以查阅 [Swarm mode CLI commands](https://docs.docker.com/engine/swarm/#swarm-mode-key-concepts-and-tutorial)。 899 | 900 | 要学习更多关于 swarm mode 的网络模型已经服务发现机制 的知识，请查看 [Configure service discovery](https://docs.docker.com/engine/swarm/networking/#configure-service-discovery)。 901 | 902 | 903 | 904 | #### `labels` 905 | 906 | 为服务指定标签。这些标签只被作用于对应的服务，而不是被应用到服务的容器或者容器实例上。 907 | 908 | ```yaml 909 | version: "3.7" 910 | services: 911 | web: 912 | image: web 913 | deploy: 914 | labels: 915 | com.example.description: "This label will appear on the web service" 916 | ``` 917 | 918 | 要为容器设置标签的话，在 `deploy` 之外为服务指定 `labels`： 919 | 920 | ```yaml 921 | version: "3.7" 922 | services: 923 | web: 924 | image: web 925 | labels: 926 | com.example.description: "This label will appear on all containers for the web service" 927 | ``` 928 | 929 | 930 | 931 | #### `mode` 932 | 933 | 可以是 `global` 或 `replicated`。`global` 表示严格地一个 swarm node 跑一个服务，`replicated` 表示可以跑多个容器实例。默认是 `replicated`。 934 | 935 | 参阅 [swarm](https://docs.docker.com/engine/swarm/) 主题下的 [Replicated and global services](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/#replicated-and-global-services)。 936 | 937 | ```yaml 938 | version: "3.7" 939 | services: 940 | worker: 941 | image: dockersamples/examplevotingapp_worker 942 | deploy: 943 | mode: global 944 | ``` 945 | 946 | 947 | 948 | #### `placement` 949 | 950 | 指定 constaints 和 preferences。 951 | 952 | 参阅docker服务建立的相关文档以了解更多的关于 [constraints](https://docs.docker.com/engine/reference/commandline/service_create/#specify-service-constraints-constraint) 和 [preferences 的相关信息，包括相应的语法，可用的类型等等的完整描述。 953 | 954 | ```yaml 955 | version: "3.7" 956 | services: 957 | db: 958 | image: postgres 959 | deploy: 960 | placement: 961 | constraints: 962 | - node.role == manager 963 | - engine.labels.operatingsystem == ubuntu 14.04 964 | preferences: 965 | - spread: node.labels.zone 966 | ``` 967 | 968 | 969 | 970 | #### `replicas` 971 | 972 | 如果服务是 `replicated` 的，`replicas` 则为其指定一个数值，此数值指示了一个 swarm 节点上最多可以跑多少个容器实例。 973 | 974 | ```yaml 975 | version: "3.7" 976 | services: 977 | worker: 978 | image: dockersamples/examplevotingapp_worker 979 | networks: 980 | - frontend 981 | - backend 982 | deploy: 983 | mode: replicated 984 | replicas: 6 985 | ``` 986 | 987 | 988 | 989 | #### `resources` 990 | 991 | 配置资源约束。 992 | 993 | >**NOTE**: 对于非 swarm mode 而言，这个表项替换 [older resource constraint options](https://docs.docker.com/compose/compose-file/compose-file-v2/#cpu-and-other-resources)（诸如 `cpu_shares`, `cpu_quota`, `cpuset`, `mem_limit`, `memswap_limit`, `mem_swappiness` 等在版本3之前版本中的表项）。 994 | > 995 | >在 [Upgrading version 2.x to 3.x](https://docs.docker.com/compose/compose-file/compose-versioning/#upgrading) 中有相应的描述。 996 | 997 | 这些资源约束表项都具有一个单一值，相当于 `docker service create` 中的等价物。 998 | 999 | 在如下的例子中，`redis` 服务被约束为不可使用超出50M的内存，单核50%的CPU使用率，同时也保留 20M 内存以及 25%的CPU使用率作为基准值。 1000 | 1001 | ```yaml 1002 | version: "3.7" 1003 | services: 1004 | redis: 1005 | image: redis:alpine 1006 | deploy: 1007 | resources: 1008 | limits: 1009 | cpus: '0.50' 1010 | memory: 50M 1011 | reservations: 1012 | cpus: '0.25' 1013 | memory: 20M 1014 | ``` 1015 | 1016 | 以下的主题描述 swarm 场景下的服务或容器资源约束的可用选项。 1017 | 1018 | ##### Out Of Memory Exceptions (OOME) 1019 | 1020 | 企图在你的服务和容器实例中使用超过系统拥有的内存，那么将得到 Out Of Memory Exception (OOME) 。此时，容器实例，或者 Docker daemon，可能会被内核的 OOM 管理器所清除。 1021 | 1022 | 要防止这样的情况发生，请确定你的应用程序合法有效地使用内存。对于这样的风险，查阅 [Understand the risks of running out of memory](https://docs.docker.com/engine/admin/resource_constraints/#understand-the-risks-of-running-out-of-memory) 以获知进一步的评估须知。 1023 | 1024 | #### `restart_policy` 1025 | 1026 | 指示当容器实例退出时，如何重启。替换 `restart`： 1027 | 1028 | - `condition`: 可以为 `none`, `on-failure` 或 `any` (默认为 `any`) 1029 | - `delay`: 在尝试重启之前的等候时长（默认为0）。应该为其指定一个 [duration](https://docs.docker.com/compose/compose-file/#specifying-durations)。 1030 | - `max_attempts`: 试图尝试重启多少次后放弃重启的尝试。默认为不放弃。 1031 | - `window`: 要确定一次重启是否成功，需要等候的时长。默认为无等待立即认定为已成功。应该为其指定一个 [duration](https://docs.docker.com/compose/compose-file/#specifying-durations)。 1032 | 1033 | ```yaml 1034 | version: "3.7" 1035 | services: 1036 | redis: 1037 | image: redis:alpine 1038 | deploy: 1039 | restart_policy: 1040 | condition: on-failure 1041 | delay: 5s 1042 | max_attempts: 3 1043 | window: 120s 1044 | ``` 1045 | 1046 | 1047 | 1048 | #### `rollback_config` 1049 | 1050 | > [Version 3.7 file format](https://docs.docker.com/compose/compose-file/compose-versioning/#version-37) and up 1051 | 1052 | 在滚动更新失败的场景下服务应该如何回滚： 1053 | 1054 | - `parallelism`：同时回滚的容器的数量值。如果设置为0，所有容器将被同时回滚。 1055 | - `delay`: 每个容器组被回滚前的等待时长（默认为0） 1056 | - `failure_action`: 一个回滚失败时应当执行的动作。可以是 `continue` 或 `pause`（默认为`pause`） 1057 | - `monitor`: 失败的回滚状态被更新到监视器的周期（`ns|us|ms|s|m|h`）默认为 `0s`。 1058 | - `max_failure_ratio`: 回滚时失败的可容忍的比例（默认为0） 1059 | - `order`: 回滚的操作顺序。可以为 `stop-first` 或 `start-first`（默认为 `stop-first`） 1060 | 1061 | 1062 | 1063 | #### `update_config` 1064 | 1065 | 指示服务应该如何被更新。这对于配置为滚动更新时有用： 1066 | 1067 | - `parallelism`：同时更新的容器的数量值。如果设置为0，所有容器将被同时回滚。 1068 | - `delay`: 每个容器组被更新前的等待时长（默认为0） 1069 | - `failure_action`: 一个更新失败时应当执行的动作。可以是 `continue`, `rollback` 或 `pause`（默认为`pause`） 1070 | - `monitor`: 失败的更新状态被更新到监视器的周期（`ns|us|ms|s|m|h`）默认为 `0s`。 1071 | - `max_failure_ratio`: 更新时失败的可容忍的比例（默认为0） 1072 | - `order`: 更新的操作顺序。可以为 `stop-first` 或 `start-first`（默认为 `stop-first`） 1073 | 1074 | > **NOTE**：`order` 只在 v3.4 及之后有效。 1075 | 1076 | ```yaml 1077 | version: "3.7" 1078 | services: 1079 | vote: 1080 | image: dockersamples/examplevotingapp_vote:before 1081 | depends_on: 1082 | - redis 1083 | deploy: 1084 | replicas: 2 1085 | update_config: 1086 | parallelism: 2 1087 | delay: 10s 1088 | order: stop-first 1089 | ``` 1090 | 1091 | 1092 | 1093 | #### NOT SUPPORTED FOR `DOCKER STACK DEPLOY` 1094 | 1095 | 下列的子选项（为 `docker-compose up` 和 `docker-compose run` 所支持）是在 `docker stack deploy` 中不被支持的： 1096 | 1097 | - [build](https://docs.docker.com/compose/compose-file/#build) 1098 | - [cgroup_parent](https://docs.docker.com/compose/compose-file/#cgroup_parent) 1099 | - [container_name](https://docs.docker.com/compose/compose-file/#container_name) 1100 | - [devices](https://docs.docker.com/compose/compose-file/#devices) 1101 | - [tmpfs](https://docs.docker.com/compose/compose-file/#tmpfs) 1102 | - [external_links](https://docs.docker.com/compose/compose-file/#external_links) 1103 | - [links](https://docs.docker.com/compose/compose-file/#links) 1104 | - [network_mode](https://docs.docker.com/compose/compose-file/#network_mode) 1105 | - [restart](https://docs.docker.com/compose/compose-file/#restart) 1106 | - [security_opt](https://docs.docker.com/compose/compose-file/#security_opt) 1107 | - [sysctls](https://docs.docker.com/compose/compose-file/#sysctls) 1108 | - [userns_mode](https://docs.docker.com/compose/compose-file/#userns_mode) 1109 | 1110 | > **Tip:** See the section on [how to configure volumes for services, swarms, and docker-stack.yml files](https://docs.docker.com/compose/compose-file/#volumes-for-services-swarms-and-stack-files). Volumes *are* supported but to work with swarms and services, they must be configured as named volumes or associated with services that are constrained to nodes with access to the requisite volumes. 1111 | 1112 | ### `devices` 1113 | 1114 | 要被映射的设备清单。其用法和 docker 命令的 `--device` 相同。 1115 | 1116 | ``` 1117 | devices: 1118 | - "/dev/ttyUSB0:/dev/ttyUSB0" 1119 | ``` 1120 | 1121 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1122 | > 1123 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1124 | 1125 | 1126 | 1127 | ### `dns` 1128 | 1129 | 自定义 DNS 服务器列表。可以指定单一值或一个清单。 1130 | 1131 | ``` 1132 | dns: 8.8.8.8 1133 | dns: 1134 | - 8.8.8.8 1135 | - 9.9.9.9 1136 | ``` 1137 | 1138 | 1139 | 1140 | ### `dns_search` 1141 | 1142 | 自定义DNS搜索域名。可以指定单一值或一个清单。 1143 | 1144 | ``` 1145 | dns_search: example.com 1146 | dns_search: 1147 | - dc1.example.com 1148 | - dc2.example.com 1149 | ``` 1150 | 1151 | 1152 | 1153 | ### `entrypoint` 1154 | 1155 | 覆盖 dockerfile 中定义的默认的 entrypoint 值。 1156 | 1157 | ```yaml 1158 | entrypoint: /code/entrypoint.sh 1159 | ``` 1160 | 1161 | 入口点也可以是一个清单： 1162 | 1163 | ```yaml 1164 | entrypoint: 1165 | - php 1166 | - -d 1167 | - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so 1168 | - -d 1169 | - memory_limit=-1 1170 | - vendor/bin/phpunit 1171 | ``` 1172 | 1173 | > **NOTE**: 设置一个 `entrypoint` 不但覆盖 Dockerfile 中的任何 `ENTRYPOINT` 默认值，还会清理 Dockerfile 中的任何 `CMD` 默认值。所以 Dockerfile 中的 `CMD` 将会被忽略。 1174 | 1175 | 1176 | 1177 | ### `env_file` 1178 | 1179 | 从给定的文件中引入环境变量值。可以是单一值或一个清单。 1180 | 1181 | ```yaml 1182 | env_file: .env 1183 | env_file: 1184 | - ./common.env 1185 | - ./apps/web.env 1186 | - /opt/secrets.env 1187 | ``` 1188 | 1189 | 对于 `docker-compose -f FILE` 来说，`env_file` 的路径是相对于 `FILE` 所在文件夹的。 1190 | 1191 | 在 `environment` 中声明的环境变量将会覆盖掉这里所引入的值。 1192 | 1193 | 对应的文件中，每一行应该使用 `VAR=VAL` 格式定义一个环境变量。行首为 `#` 表示为注释行，和空白行一样被忽略。 1194 | 1195 | ```bash 1196 | # Set Rails/Rack environment 1197 | RACK_ENV=development 1198 | ``` 1199 | 1200 | > **NOTE**: 如果服务定义了 `build` 项，在构建过程中，由 `env_file` 所定义的环境变量并不可见。只能使用 `build` 的子选项 `args` 去定义构建时环境变量值。 1201 | 1202 | `VAL` 的值被原样照用，且不能被修改。例如如果值由引号所包围，那么值的表示量中也包含引号。 1203 | 1204 | 环境变量文件的顺序也需要被注意。位置靠后的环境变量文件中所定义的变量值会覆盖掉早前定义的旧值。 1205 | 1206 | 1207 | 1208 | ### `environment` 1209 | 1210 | 添加环境变量。可以使用一个数组或者一个字典。任何布尔量：true, false, yes, no 等等都必须用引号包围为字符串字面量。 1211 | 1212 | 只有key值的环境变量的value值依赖于 docker-compose 运行时的主机环境，这对于防止敏感信息泄露是有用的。 1213 | 1214 | ```yaml 1215 | environment: 1216 | RACK_ENV: development 1217 | SHOW: 'true' 1218 | SESSION_SECRET: 1219 | environment: 1220 | - RACK_ENV=development 1221 | - SHOW=true 1222 | - SESSION_SECRET 1223 | ``` 1224 | 1225 | > **NOTE**: 如果服务定义了 `build` 项，在构建过程中，由 `env_file` 所定义的环境变量并不可见。只能使用 `build` 的子选项 `args` 去定义构建时环境变量值。 1226 | 1227 | 1228 | 1229 | ### `expose` 1230 | 1231 | 暴露端口到链接的服务。这些端口并不会被发布到宿主机。只能指定内部端口被用于暴露。 1232 | 1233 | ``` 1234 | expose: 1235 | - "3000" 1236 | - "8000" 1237 | ``` 1238 | 1239 | 1240 | 1241 | ### `external_links` 1242 | 1243 | 将在 `docker-compose.yml` 之外启动的容器链接到给定服务上。 1244 | 1245 | 和遗留选项 `links` 有相似的语义。 1246 | 1247 | ```yaml 1248 | external_links: 1249 | - redis_1 1250 | - project_db_1:mysql 1251 | - project_db_1:postgresql 1252 | ``` 1253 | 1254 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1255 | > 1256 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1257 | 1258 | 更推荐的做法是通过 `networks` 构造一个子网以进行容器之间的链接。 1259 | 1260 | 1261 | 1262 | ### `extra_hosts` 1263 | 1264 | 添加主机名映射。这些映射关系会被添加到 `/etc/hosts` 中。此功能等价于命令行参数 `--add-host`。 1265 | 1266 | ```yaml 1267 | extra_hosts: 1268 | - "somehost:162.242.195.82" 1269 | - "otherhost:50.31.209.229" 1270 | ``` 1271 | 1272 | 1273 | 1274 | ### `healthcheck` 1275 | 1276 | > since v2.1 1277 | 1278 | 用于确认一个服务是否是“健康”的。参阅 [HEALTHCHECK Dockerfile instruction](https://docs.docker.com/engine/reference/builder/#healthcheck)。 1279 | 1280 | ```yaml 1281 | healthcheck: 1282 | test: ["CMD", "curl", "-f", "http://localhost"] 1283 | interval: 1m30s 1284 | timeout: 10s 1285 | retries: 3 1286 | start_period: 40s 1287 | ``` 1288 | 1289 | `interval`, `timeout` 和 `start_period` 应该被指定为 [durations](https://docs.docker.com/compose/compose-file/#specifying-durations). 1290 | 1291 | > **Note**: `start_period` 只在 v3.4 及以后可用。 1292 | 1293 | `test` 必须是一个单一字符串值或一个列表。如果是一个列表，那么第一项必须是 `NONE`, `CMD`, `CMD-SHELL` 之一。如果是一个字符串，隐含地表示一个 `CMD-SHELL` 前缀。 1294 | 1295 | ```yaml 1296 | # Hit the local web app 1297 | test: ["CMD", "curl", "-f", "http://localhost"] 1298 | ``` 1299 | 1300 | 如上述示例，但隐含调用 `/bin/sh`，和以下的形式是等效的。 1301 | 1302 | ```yaml 1303 | test: ["CMD-SHELL", "curl -f http://localhost || exit 1"] 1304 | test: curl -f https://localhost || exit 1 1305 | ``` 1306 | 1307 | 要禁用任何在映像内指定的缺省的健康检查向，可以使用 `disable: true`。这和指定 `test: ["NONE"]` 是等效的。 1308 | 1309 | ```yaml 1310 | healthcheck: 1311 | disable: true 1312 | ``` 1313 | 1314 | 1315 | 1316 | ### `image` 1317 | 1318 | 指定映像的名称。 1319 | 1320 | ```yaml 1321 | image: redis 1322 | image: ubuntu:14.04 1323 | image: tutum/influxdb 1324 | image: example-registry.com:4000/postgresql 1325 | image: a4bc65fd 1326 | ``` 1327 | 1328 | 如果映像在宿主机不存在，Compose 会尝试下拉它，除非你也指定了 `build` 项。 1329 | 1330 | 1331 | 1332 | ### `init` 1333 | 1334 | > since v3.7 1335 | 1336 | 在容器中运行一个 init 进程并转发信号。设置为 `true` 为服务使能这个特性。 1337 | 1338 | ```yaml 1339 | version: "3.7" 1340 | services: 1341 | web: 1342 | image: alpine:latest 1343 | init: true 1344 | ``` 1345 | 1346 | > 缺省的 init 进程使用二进制执行文件 [Tini](https://github.com/krallin/tini)，在需要时它将被安装于 daemon主机的位置 `/usr/libexec/docker-init` 。你也可以配置 daemon 使用一个不同的二进制文件，通过 `init-path`，参阅 [configuration option](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file)。 1347 | 1348 | 1349 | 1350 | ### `isolation` 1351 | 1352 | 指定一个容器的隔离层级/技术。在 Linux 中，仅支持 `default` 值。在 Windows 中，可以接受的值有：`default`, `process` 和 `hyperv`。 1353 | 1354 | 1355 | 1356 | ### `labels` 1357 | 1358 | 为容器添加元数据标签，参考 [Docker labels](https://docs.docker.com/engine/userguide/labels-custom-metadata/)。可以为其指定一个数组或一个字典。 1359 | 1360 | 我们建议你采用反向DNS标注方式来定义你的标签，这可以有效地避免标签名称的冲突。 1361 | 1362 | ```yaml 1363 | labels: 1364 | com.example.description: "Accounting webapp" 1365 | com.example.department: "Finance" 1366 | com.example.label-with-empty-value: "" 1367 | labels: 1368 | - "com.example.description=Accounting webapp" 1369 | - "com.example.department=Finance" 1370 | - "com.example.label-with-empty-value" 1371 | ``` 1372 | 1373 | 1374 | 1375 | ### `links` 1376 | 1377 | > 已经是一个遗留特征了。在不久的未来将被移除。 1378 | 1379 | 链接另一个服务到本容器。可以同时制定服务名称和链接别名（`SERVICE:ALIAS`），也可以略过链接别名。 1380 | 1381 | ```yaml 1382 | web: 1383 | links: 1384 | - db 1385 | - db:database 1386 | - redis 1387 | ``` 1388 | 1389 | 已经被链入的服务将会是主机名（即链接别名 `ALIAS`）可访问的。 1390 | 1391 | 对于服务间通讯来说，链接并不是必须的。默认情况下，任何服务都可以通过服务名访问到其他服务。参阅 [Links topic in Networking in Compose](https://docs.docker.com/compose/networking/#links)。 1392 | 1393 | 链接也表示一个依赖关系，但这已经是 `depends_on` 的任务了，所以链接也并不必要了。 1394 | 1395 | 1396 | 1397 | ### `logging` 1398 | 1399 | 为服务指定日志转发配置。 1400 | 1401 | ```yaml 1402 | logging: 1403 | driver: syslog 1404 | options: 1405 | syslog-address: "tcp://192.168.0.42:123" 1406 | ``` 1407 | 1408 | `driver` 指定了驱动名称，这和 `--log-driver` 是等效的。缺省值为 `json-file`。 1409 | 1410 | ```yaml 1411 | driver: "json-file" 1412 | driver: "syslog" 1413 | driver: "none" 1414 | ``` 1415 | 1416 | 可用的转发驱动器可以参考 https://docs.docker.com/config/containers/logging/configure/。 1417 | 1418 | 使用 `option` 指定驱动器的选项，如同 `--log-opt` 那样。例如为 `syslog` 这样指定： 1419 | 1420 | ```yaml 1421 | driver: "syslog" 1422 | options: 1423 | syslog-address: "tcp://192.168.0.42:123" 1424 | ``` 1425 | 1426 | 缺省的日志转发驱动为 `json-file`。对此可以指定日志切割尺寸以及最多保持的日志历史文件个数： 1427 | 1428 | ```yaml 1429 | version: "3.7" 1430 | services: 1431 | some-service: 1432 | image: some-service 1433 | logging: 1434 | driver: "json-file" 1435 | options: 1436 | max-size: "200k" 1437 | max-file: "10" 1438 | ``` 1439 | 1440 | 1441 | 1442 | ### `network_mode` 1443 | 1444 | 网络模型。 1445 | 1446 | 和 `--network` 的取值相同。但额外支持 `service:[service name]` 模式。 1447 | 1448 | ```yaml 1449 | network_mode: "bridge" 1450 | network_mode: "host" 1451 | network_mode: "none" 1452 | network_mode: "service:[service name]" 1453 | network_mode: "container:[container name/id]" 1454 | ``` 1455 | 1456 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1457 | > 1458 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1459 | 1460 | > **NOTE**: `network_mode: "host"` 不能和 [links](https://docs.docker.com/compose/compose-file/#links) 混用。 1461 | 1462 | 1463 | 1464 | ### `networks` 1465 | 1466 | 要加入的网络。目标网络是在 `docker-compose.yml` 顶级的 `networks` 项中定义的。 1467 | 1468 | ```yaml 1469 | services: 1470 | some-service: 1471 | networks: 1472 | - some-network 1473 | - other-network 1474 | ``` 1475 | 1476 | #### ALIASES 1477 | 1478 | 指定网络中该服务的别名（也即主机名）。相同网络中别的容器可以使用服务名或者服务别名来连接到该服务的容器实例。 1479 | 1480 | 既然 `aliases` 是网络范围内的，同一个服务在不同网络中可以有不同的别名。 1481 | 1482 | ```yaml 1483 | services: 1484 | some-service: 1485 | networks: 1486 | some-network: 1487 | aliases: 1488 | - alias1 1489 | - alias3 1490 | other-network: 1491 | aliases: 1492 | - alias2 1493 | ``` 1494 | 1495 | 一个更复杂而完整的例子： 1496 | 1497 | ```yaml 1498 | version: "3.7" 1499 | 1500 | services: 1501 | web: 1502 | image: "nginx:alpine" 1503 | networks: 1504 | - new 1505 | 1506 | worker: 1507 | image: "my-worker-image:latest" 1508 | networks: 1509 | - legacy 1510 | 1511 | db: 1512 | image: mysql 1513 | networks: 1514 | new: 1515 | aliases: 1516 | - database 1517 | legacy: 1518 | aliases: 1519 | - mysql 1520 | 1521 | networks: 1522 | new: 1523 | legacy: 1524 | ``` 1525 | 1526 | #### IPV4_ADDRESS, IPV6_ADDRESS 1527 | 1528 | 指定一个静态IP地址。 1529 | 1530 | 注意相应的顶级网络配置中，必须有 `ipam` 块对子网进行了配置且静态IP地址符合该子网定义。 1531 | 1532 | > If IPv6 addressing is desired, the [`enable_ipv6`](https://docs.docker.com/compose/compose-file/compose-file-v2/##enable_ipv6) option must be set, and you must use a [version 2.x Compose file](https://docs.docker.com/compose/compose-file/compose-file-v2/#ipv4_address-ipv6_address). *IPv6 options do not currently work in swarm mode*. 1533 | 1534 | 一个例子是： 1535 | 1536 | ```yaml 1537 | version: "3.7" 1538 | 1539 | services: 1540 | app: 1541 | image: nginx:alpine 1542 | networks: 1543 | app_net: 1544 | ipv4_address: 172.16.238.10 1545 | ipv6_address: 2001:3984:3989::10 1546 | 1547 | networks: 1548 | app_net: 1549 | ipam: 1550 | driver: default 1551 | config: 1552 | - subnet: "172.16.238.0/24" 1553 | - subnet: "2001:3984:3989::/64" 1554 | ``` 1555 | 1556 | 1557 | 1558 | ### `pid` 1559 | 1560 | ```yaml 1561 | pid: "host" 1562 | ``` 1563 | 1564 | 设置服务使用主机的 PID 模式。这使得容器内的服务进程和宿主机操作系统级能够共享 PID 地址空间。这是一个典型的 Linux/Unix 操作系统概念，因此这里不再展开叙述了。这样的共享的作用，可以使能安全的、借助PID地址空间的 IPC 通讯。 1565 | 1566 | 1567 | 1568 | ### `ports` 1569 | 1570 | 暴露端口到宿主机。 1571 | 1572 | > **Note**: 端口暴露功能和 `network_mode: host` 不能兼容。 1573 | 1574 | ### 短格式 1575 | 1576 | 可以同时指定宿主机和容器端口 (`HOST:CONTAINER`) 以完成映射，也可以仅指定容器端口以自动映射为~~相同的主机端口~~一个临时端口（从32768开始）。 1577 | 1578 | ```yaml 1579 | ports: 1580 | - "3000" 1581 | - "3000-3005" 1582 | - "8000:8000" 1583 | - "9090-9091:8080-8081" 1584 | - "49100:22" 1585 | - "127.0.0.1:8001:8001" 1586 | - "127.0.0.1:5000-5010:5000-5010" 1587 | - "6060:6060/udp" 1588 | ``` 1589 | 1590 | #### 长格式 1591 | 1592 | 允许进行冗长的定义： 1593 | 1594 | ```yaml 1595 | ports: 1596 | - target: 80 1597 | published: 8080 1598 | protocol: tcp 1599 | mode: host 1600 | ``` 1601 | 1602 | > 意义明显，所以略过解说。 1603 | 1604 | > **NOTE**：长格式仅在 v3.2 及之后有效。 1605 | 1606 | 1607 | 1608 | ### `restart` 1609 | 1610 | `no` 是默认的重启策略。此时无论容器怎么退出、怎么失败也不会被自动重启。 1611 | 1612 | 指定 `always` 时任何情况下容器都会被重启。 1613 | 1614 | `on-failure` 策略可在容器失败退出时才重启。 1615 | 1616 | ```yaml 1617 | restart: "no" 1618 | restart: always 1619 | restart: on-failure 1620 | restart: unless-stopped 1621 | ``` 1622 | 1623 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。（此时可以使用 `restart_policy` 达到目的） 1624 | > 1625 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1626 | 1627 | 1628 | 1629 | ### `secrets` 1630 | 1631 | 从每个服务配置中，授权访问顶级 `secrets` 定义的表项。支持长短两个格式。 1632 | 1633 | #### 短格式 1634 | 1635 | 短格式仅指定敏感内容的名字。这使得容器能够挂载对应内容到 `/run/secrets/` 位置并访问它。 1636 | 1637 | 下面的例子使用短格式，让 `redis` 能够访问 `my_secret` 和 `my_other_secret`。`my_secret` 的具体内容被定义在 `./my_secret.txt`，`my_other_secret` 被定义为外部资源，例如通过 `docker secret create` 方式预先定义。如果找不到对应的外部资源，stack部署将会失败并抛出一个 `secret not found` 错误。 1638 | 1639 | ```yaml 1640 | version: "3.7" 1641 | services: 1642 | redis: 1643 | image: redis:latest 1644 | deploy: 1645 | replicas: 1 1646 | secrets: 1647 | - my_secret 1648 | - my_other_secret 1649 | secrets: 1650 | my_secret: 1651 | file: ./my_secret.txt 1652 | my_other_secret: 1653 | external: true 1654 | ``` 1655 | 1656 | #### 长格式 1657 | 1658 | 长格式可以更精细地定义敏感内容如何被用于 stack 内容器。 1659 | 1660 | - `source`： 敏感内容在 Docker 中所被定义的名字。 1661 | - `target`: 被挂载到容器内 `/run/secrets/` 中的文件名。如果没指定则使用 `source` 名。 1662 | - `uid` & `gid`: 容器内挂载的文件的 UID 和 GID。如未指定则为0。在 Windows 中无效。 1663 | - `mode`: 容器内挂载的文件的八进制许可权限。在 Docker 1.13.1 中默认值为 `0000`，但在更新的版本中为 `0444`。挂载的文件是不可写的。执行位可以被设置，但一般情况下没有意义。 1664 | 1665 | 下面是一个例子： 1666 | 1667 | ```yaml 1668 | version: "3.7" 1669 | services: 1670 | redis: 1671 | image: redis:latest 1672 | deploy: 1673 | replicas: 1 1674 | secrets: 1675 | - source: my_secret 1676 | target: redis_secret 1677 | uid: '103' 1678 | gid: '103' 1679 | mode: 0440 1680 | secrets: 1681 | my_secret: 1682 | file: ./my_secret.txt 1683 | my_other_secret: 1684 | external: true 1685 | ``` 1686 | 1687 | 长短格式时可以被混用的，如果你在定义多个敏感内容。 1688 | 1689 | 1690 | 1691 | ### `security_opt` 1692 | 1693 | 为每个容器覆盖掉默认的标签语义。 1694 | 1695 | ```yaml 1696 | security_opt: 1697 | - label:user:USER 1698 | - label:role:ROLE 1699 | ``` 1700 | 1701 | 通常这和 seccomp 有关，这会是与安全配置有关的一个冗长的话题，故而此处不做展开。 1702 | 1703 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。（此时可以使用 `restart_policy` 达到目的） 1704 | > 1705 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1706 | 1707 | 1708 | 1709 | ### stop_grace_period 1710 | 1711 | 指定一个等待时长，如果容器未能拦住 `SIGTERM` 信号（或者通过 `stop_signal` 定义的别的信号）正常地关闭自己，则在此时长之后强制清除容器实例的相应进程（通过 `SIGKILL` 信号）。 1712 | 1713 | ```yaml 1714 | stop_grace_period: 1s 1715 | stop_grace_period: 1m30s 1716 | ``` 1717 | 1718 | 默认时，将会等候 10s 。 1719 | 1720 | 1721 | 1722 | ### `stop_signal` 1723 | 1724 | 设置一个替代信号以正常关闭容器实例。默认时使用 `SIGTERM` 信号. 1725 | 1726 | ```yaml 1727 | stop_signal: SIGUSR1 1728 | ``` 1729 | 1730 | 1731 | 1732 | ### `sysctls` 1733 | 1734 | 为容器设定内核参数。可以使用一个数组或字典。 1735 | 1736 | ```yaml 1737 | sysctls: 1738 | net.core.somaxconn: 1024 1739 | net.ipv4.tcp_syncookies: 0 1740 | sysctls: 1741 | - net.core.somaxconn=1024 1742 | - net.ipv4.tcp_syncookies=0 1743 | ``` 1744 | 1745 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。（此时可以使用 `restart_policy` 达到目的） 1746 | > 1747 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1748 | 1749 | 1750 | 1751 | ### `tmpfs` 1752 | 1753 | > since v2 1754 | 1755 | 挂载一个临时文件系统到容器中。可以是一个单一值或一个列表。 1756 | 1757 | ```yaml 1758 | tmpfs: /run 1759 | tmpfs: 1760 | - /run 1761 | - /tmp 1762 | ``` 1763 | 1764 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。（此时可以使用 `restart_policy` 达到目的） 1765 | > 1766 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1767 | 1768 | 1769 | 1770 | > since v3.6 1771 | 1772 | 挂载一个临时文件系统到容器中。Size参数可以指定文件系统尺寸的字节大小。默认值为无限。 1773 | 1774 | ```yaml 1775 | - type: tmpfs 1776 | target: /app 1777 | tmpfs: 1778 | size: 1000 1779 | ``` 1780 | 1781 | 1782 | 1783 | ### `ulimits` 1784 | 1785 | 覆盖容器内指定的默认的 ulimits 值。可以指定一个整数作为单一的 limit 限制，或者指定一个 mapping 以分别表示 soft/hard limit 限制。 1786 | 1787 | ```yaml 1788 | ulimits: 1789 | nproc: 65535 1790 | nofile: 1791 | soft: 20000 1792 | hard: 40000 1793 | ``` 1794 | 1795 | 1796 | 1797 | ### `userns_mode` 1798 | 1799 | ```yaml 1800 | userns_mode: "host" 1801 | ``` 1802 | 1803 | 禁用用户名字空间。如果 Docker daemon 被配置运行在一个 user namespace 之中的话。 1804 | 1805 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。（此时可以使用 `restart_policy` 达到目的） 1806 | > 1807 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1808 | 1809 | 1810 | 1811 | ### `volumes` 1812 | 1813 | 挂载宿主机路径或者命名卷。 1814 | 1815 | 可以挂载一个主机路径到一个服务中，此时无需在顶级 `volumes` 中对其进行定义。 1816 | 1817 | 如果想要重用一个卷到多个服务，那么应该在顶级 `volumes` 中定义它并命名它。 1818 | 1819 | 可以在 [services, swarms, and stack files](https://docs.docker.com/compose/compose-file/#volumes-for-services-swarms-and-stack-files) 中使用命名卷。 1820 | 1821 | > **NOTE**： 在顶级 `volumes` 中定义一个命名卷，并在一个服务的 `volumes` 列表中引用它。 1822 | > 1823 | > 早期的 `volumes_from` 不再使用了。 1824 | > 1825 | > 可以参阅 [Use volumes](https://docs.docker.com/engine/admin/volumes/volumes/) and [Volume Plugins](https://docs.docker.com/engine/extend/plugins_volume/)。 1826 | 1827 | 下面的例子示意了一个命名卷 `my_data` ，且被用于 `web` 服务。在 `web` 中也使用一个主机文件夹 `./static` 到容器内的挂载；在 `db` 中挂载了一个主机文件到容器内的对应文件，并使用了另一个命名卷 `dbdata`。 1828 | 1829 | ```yaml 1830 | version: "3.7" 1831 | services: 1832 | web: 1833 | image: nginx:alpine 1834 | volumes: 1835 | - type: volume 1836 | source: mydata 1837 | target: /data 1838 | volume: 1839 | nocopy: true 1840 | - type: bind 1841 | source: ./static 1842 | target: /opt/app/static 1843 | 1844 | db: 1845 | image: postgres:latest 1846 | volumes: 1847 | - "/var/run/postgres/postgres.sock:/var/run/postgres/postgres.sock" 1848 | - "dbdata:/var/lib/postgresql/data" 1849 | 1850 | volumes: 1851 | mydata: 1852 | dbdata: 1853 | ``` 1854 | 1855 | 1856 | 1857 | #### 短格式 1858 | 1859 | 可以使用 `HOST:CONTAINER` 格式，或者附带一个访问模式 `HOST:CONTAINER:ro`。 1860 | 1861 | 可以挂载一个主机中的相对路径。 1862 | 1863 | ```yaml 1864 | volumes: 1865 | # Just specify a path and let the Engine create a volume 1866 | - /var/lib/mysql 1867 | 1868 | # Specify an absolute path mapping 1869 | - /opt/data:/var/lib/mysql 1870 | 1871 | # Path on the host, relative to the Compose file 1872 | - ./cache:/tmp/cache 1873 | 1874 | # User-relative path 1875 | - ~/configs:/etc/configs/:ro 1876 | 1877 | # Named volume 1878 | - datavolume:/var/lib/mysql 1879 | ``` 1880 | 1881 | #### 长格式 1882 | 1883 | 长格式可以进行更精细的控制。 1884 | 1885 | - `type`: 挂载类型 为 `volume`, `bind`, `tmpfs` 和 `npipe` 1886 | - `source`：挂载的源位置。可以是一个主机路径，一个定义于顶级 volumes 中的卷名称，等等。如果是挂载 `tmpfs` 则此参数无意义。 1887 | - `target`: 容器内的挂载点路径。 1888 | - `read_only`: 布尔值以设定卷的可写性。 1889 | - `bind`: 配置附加的 bind 选项。 1890 | - `propagation`: 用于 bind 的传播模式。 1891 | - `volume`: 配置附加的 卷 选项 1892 | - `nocopy`：布尔量以禁用数据复制（默认时当卷被首次创建时，容器内的内容将被复制到卷内） 1893 | - `tmpfs`: 配置附加的 tmpfs 选项 1894 | - `size`: tmpfs的容量，按字节数。 1895 | - `consistency`：挂载的一致性要求：`consistent` 主机和容器有同样的视图，`cached` 读操作被缓冲，主机视图为主体，`delegated` 读写操作被缓冲，容器视图为主体。 1896 | 1897 | ```yaml 1898 | version: "3.7" 1899 | services: 1900 | web: 1901 | image: nginx:alpine 1902 | ports: 1903 | - "80:80" 1904 | volumes: 1905 | - type: volume 1906 | source: mydata 1907 | target: /data 1908 | volume: 1909 | nocopy: true 1910 | - type: bind 1911 | source: ./static 1912 | target: /opt/app/static 1913 | 1914 | networks: 1915 | webnet: 1916 | 1917 | volumes: 1918 | mydata: 1919 | ``` 1920 | 1921 | > 长格式在 v3.2 之后可用 1922 | 1923 | #### VOLUMES FOR SERVICES, SWARMS, AND STACK FILES 1924 | 1925 | 当工作在 services, swarms, 或 `docker-stack.yml` 场景下，要注意一个服务在 swarm 中可能被部署到任意节点，而每当服务被更新之后再次启动时，可能已经不再在原来的节点上了。 1926 | 1927 | 当指定名称的卷并不存在时，Docker会自动创建一个匿名卷用于引用的服务。匿名卷是不可持久化的，因此当关联的容器实例退出并被移除时，匿名卷也会被销毁。 1928 | 1929 | 如果想要持久化你的数据，采用命名卷以及选择恰当的卷驱动程序，这个驱动应该是跨主机的，这样数据才能在不同的主机之间漫游。否则的话，你应该设置服务的约束条件以便该服务只会被部署到特定的节点上，这些节点上有相应的卷服务在正确工作。 1930 | 1931 | 作为一个例子，[votingapp sample in Docker Labs](https://github.com/docker/labs/blob/master/beginner/chapters/votingapp.md) 的 `docker-stack.yml` 文件定义了 `db` 服务，运行着 postgresql。它使用了一个命名卷 `db-data` 来持久化数据库数据，这个卷被通过swarm约束在只能运行在 `manager` 这个节点上，因此一切疑难都不存在了。下面是源码： 1932 | 1933 | ```yaml 1934 | version: "3.7" 1935 | services: 1936 | db: 1937 | image: postgres:9.4 1938 | volumes: 1939 | - db-data:/var/lib/postgresql/data 1940 | networks: 1941 | - backend 1942 | deploy: 1943 | placement: 1944 | constraints: [node.role == manager] 1945 | ``` 1946 | 1947 | #### CACHING OPTIONS FOR VOLUME MOUNTS (DOCKER DESKTOP FOR MAC) 1948 | 1949 | 在 Docker 17.04 CE Edge 以及其后版本中（乃至于 17.06CE Edge 和 Stable 版本），你可以配置容器和主机之间卷如何被同步的一致性约束参数。这些标志包括： 1950 | 1951 | - `consistent` 完全一致。主机和容器有同样的视图，这是默认的策略。 1952 | 1953 | - `cached` 宿主机为准。对卷的读操作被缓冲，主机视图为主体， 1954 | 1955 | - `delegated` 容器为准。对卷的读写操作被缓冲，容器视图为主体。 1956 | 1957 | 这是专为 Docker Desktop for Mac 而适配的。由于已经知道的 `osxfx` 的关于文件共享特性原因，合理的设置一致性标志能够改善容器内外访问挂载卷时的性能问题。 1958 | 1959 | 下面是一个`cached`卷的例子： 1960 | 1961 | ```yaml 1962 | version: "3.7" 1963 | services: 1964 | php: 1965 | image: php:7.1-fpm 1966 | ports: 1967 | - "9000" 1968 | volumes: 1969 | - .:/var/www/project:cached 1970 | ``` 1971 | 1972 | 对于读写操作均被缓冲的情况，即使容器中发生了什么修改（对于向PHP Website这样的典型架构来说，./config.php 经常是可能被写入的），也不会立即体现到宿主机中来，容器中的写入将会被堆积。 1973 | 1974 | 卷在容器内外的一致性问题，应该参考 [Performance tuning for volume mounts (shared filesystems)](https://docs.docker.com/docker-for-mac/osxfs-caching/)。 1975 | 1976 | > 在这里我未能原样翻译，因为那样会带来较长的篇幅，我尚未能就此问题组织好语言。 1977 | 1978 | 1979 | 1980 | ### `domainname`, `hostname`, `ipc`, `mac_address`, `privileged`, `read_only`, `shm_size`, `stdin_open`, `tty`, `user`, `working_dir` 1981 | 1982 | 这些配置具有单一值。和 `docker run` 的相应命令行参数相对应。`mac_address` 已经是被遗弃的设定。 1983 | 1984 | ```yaml 1985 | user: postgresql 1986 | working_dir: /code 1987 | 1988 | domainname: foo.com 1989 | hostname: foo 1990 | ipc: host 1991 | mac_address: 02:42:ac:11:65:43 1992 | 1993 | privileged: true 1994 | 1995 | 1996 | read_only: true 1997 | shm_size: 64M 1998 | stdin_open: true 1999 | tty: true 2000 | ``` 2001 | 2002 | 2003 | 2004 | 2005 | 2006 | ## 指定时间段 duration 2007 | 2008 | 有的配置选项，例如 `interval` 或者 `timeout`（都是 `check `的子选项），接受一个字符串风格的时间周期或时间段的参数值。它们应该具有这样的格式： 2009 | 2010 | ```yaml 2011 | 2.5s 2012 | 10s 2013 | 1m30s 2014 | 2h32m 2015 | 5h34m56s 2016 | ``` 2017 | 2018 | 可以为数值附加的后缀单位有 `us`, `ms`, `s`, `m`, 以及 `h`。 2019 | 2020 | 含义自明。 2021 | 2022 | 2023 | 2024 | ## 指定字节值 2025 | 2026 | 有的配置选项，例如 `build` 的子选项 `shm_size`，接受一个字符串分隔的容量尺寸参数值。它们应该具有这样的格式： 2027 | 2028 | ```yaml 2029 | 2b 2030 | 1024kb 2031 | 2048k 2032 | 300m 2033 | 1gb 2034 | ``` 2035 | 2036 | 有效的后缀单位包括 `b`, `k`, `m` 和 `g`。此外，`kb`, `mb` 和 `gb` 也是合法的。纯粹的十进制数值并不合法。 2037 | 2038 | 2039 | 2040 | 2041 | 2042 | 2043 | 2044 | ## 卷编排格式手册 - `volumes` 2045 | 2046 | 顶级的 volumes 章节可以声明和创建命名卷（无需使用 `volume_from`），这些卷能够被用于在 service 章节下的 [volumes](#volumes) 小节中被引用。所以我们可以重用它们，甚至能够跨越多个 services。docker命令的 [docker volume](https://docs.docker.com/engine/reference/commandline/volume_create/) 子命令有更多的参考信息。 2047 | 2048 | 关于卷的使用，也可以参考 [Use volumes](https://docs.docker.com/engine/admin/volumes/volumes/) 和 [Volume Plugins](https://docs.docker.com/engine/extend/plugins_volume/)。 2049 | 2050 | 这里有一个示例，包含了两个服务，数据库的数据存储文件夹在两个服务之间被共享，因而数据库可以使用这个存储文件夹，而备份服务同样可以操作它以完成备份任务： 2051 | 2052 | ```yaml 2053 | version: "3.7" 2054 | 2055 | services: 2056 | db: 2057 | image: db 2058 | volumes: 2059 | - data-volume:/var/lib/db 2060 | backup: 2061 | image: backup-service 2062 | volumes: 2063 | - data-volume:/var/lib/backup/data 2064 | 2065 | volumes: 2066 | data-volume: 2067 | ``` 2068 | 2069 | 顶级 `volumes` 章节下的条目可以是空，无需指定细节，这样的话，默认的卷驱动程序将被应用（通常都会是 `local` 卷驱动）。 2070 | 2071 | 但你也可以通过下面的参数对其进行定制： 2072 | 2073 | ### `driver` 2074 | 2075 | 指定哪一个卷驱动程序会被采用。一般来说，默认值会是 `local`。如果卷驱动程序无效、或不能工作，在 `docker-compose up` 时 Docker Engine将会返回一个错误。 2076 | 2077 | ```yaml 2078 | driver: foobar 2079 | ``` 2080 | 2081 | ### `driver_opts` 2082 | 2083 | 可选地指定一组键值对参数集，这些参数将被传递给卷驱动程序。所以这些参数集是和卷驱动程序相关的，请参考卷驱动程序的有关文档。 2084 | 2085 | ```yaml 2086 | volumes: 2087 | example: 2088 | driver_opts: 2089 | type: "nfs" 2090 | o: "addr=10.40.0.199,nolock,soft,rw" 2091 | device: ":/docker/example" 2092 | ``` 2093 | 2094 | ### `external` 2095 | 2096 | 如果设置为 `true`，表示相应的卷是在 compose 编排文件之外被创建就绪的。此时 `docker-compse up` 将不会尝试创建这个卷，而如果该卷尚未存在则会返回一个错误。 2097 | 2098 | 对于 v3.3 以及更低的 compose 编排格式版本而言，`external` 不可以被用于与其他卷配置参数组合使用，例如 `driver`, `driver_opts`, `labels` 等等。但对于 v3.4 以及更高版本来说不再有此限制。 2099 | 2100 | 下面的示例中，Compose 查找一个名为 `data` 的外部卷并挂载它到 `db` 服务中，而不是尝试创建一个名为 `[projectname]_data` 的新卷。 2101 | 2102 | ```yaml 2103 | version: "3.7" 2104 | 2105 | services: 2106 | db: 2107 | image: postgres 2108 | volumes: 2109 | - data:/var/lib/postgresql/data 2110 | 2111 | volumes: 2112 | data: 2113 | external: true 2114 | ``` 2115 | 2116 | > `external.name` 在 v3.4+ 已被废弃，这之后直接使用 `name`。 2117 | 2118 | 你也可以单独指定卷名字（这时，`data` 被认为是该卷在当前编排文件中被引用时的 卷别名）： 2119 | 2120 | ``` 2121 | volumes: 2122 | data: 2123 | external: 2124 | name: actual-name-of-volume 2125 | ``` 2126 | 2127 | > **External volumes are always created with docker stack deploy** 2128 | > 2129 | > 在使用 [docker stack deploy](https://docs.docker.com/compose/compose-file/#deploy) 部署到 swarm 中时，外部卷如果不存在，则总是自动被创建。进一步的有关信息请参阅 [moby/moby#29976](https://github.com/moby/moby/issues/29976)、 2130 | 2131 | ### `labels` 2132 | 2133 | 使用 [Docker labels](https://docs.docker.com/engine/userguide/labels-custom-metadata/) 为容器添加元数据。可以是数组格式或者字典格式。 2134 | 2135 | 我们建议你使用反向DNS标注方式，为你的元数据表键添加反向域名前缀，从而避免潜在的和其它应用的相同名字的表键发生冲突： 2136 | 2137 | ```yaml 2138 | labels: 2139 | com.example.description: "Database volume" 2140 | com.example.department: "IT/Ops" 2141 | com.example.label-with-empty-value: "" 2142 | labels: 2143 | - "com.example.description=Database volume" 2144 | - "com.example.department=IT/Ops" 2145 | - "com.example.label-with-empty-value" 2146 | ``` 2147 | 2148 | 2149 | 2150 | ### `name` 2151 | 2152 | > since v3.4+ 2153 | 2154 | 为卷指定一个自定义的名字。名字的值可被用于解决具有特殊字符名字的卷。注意该值被原样使用，引号不会被忽略，也不会被添加上栈名字前缀。 2155 | 2156 | ```yaml 2157 | version: "3.7" 2158 | volumes: 2159 | data: 2160 | name: my-app-data 2161 | ``` 2162 | 2163 | `name` 可以被与 `external` 相组合： 2164 | 2165 | ``` 2166 | version: "3.7" 2167 | volumes: 2168 | data: 2169 | external: true 2170 | name: my-app-data 2171 | ``` 2172 | 2173 | 2174 | 2175 | ## 网络编排格式手册 - `networks` 2176 | 2177 | 顶级章节 `networks` 使得你可以配置想要创建和使用的网络（Compose内网）。 2178 | 2179 | - 完整的在 Compose 中使用 Docker 网络环境特性的有关说明，以及所有的网络驱动程序选项，请参考 [Networking guide](https://docs.docker.com/compose/networking/)。 2180 | - 对于 [Docker Labs](https://github.com/docker/labs/blob/master/README.md) 的和网络相关的辅导用例，请仔细阅读 [Designing Scalable, Portable Docker Container Networks](https://github.com/docker/labs/blob/master/networking/README.md)。 2181 | 2182 | ### `driver` 2183 | 2184 | 指定该网络的驱动程序。 2185 | 2186 | 缺省的驱动程序由 Docker Engine 的启动参数所指定。通常情况下，启动参数内置为在单节点宿主机上使用 `bridge` 驱动，而在 `swarm mode` 中使用 `overlay` 驱动。 2187 | 2188 | 如果驱动程序不可用，Docker Engine 将会返回一个错误。 2189 | 2190 | ```yaml 2191 | driver: overlay 2192 | ``` 2193 | 2194 | 2195 | 2196 | #### bridge 2197 | 2198 | 缺省时 Docker 在每个宿主机节点上使用 `bridge` 驱动。有关桥接网络是如何工作的，可以参考 [Docker Labs](https://github.com/docker/labs/blob/master/README.md) 的和网络相关的辅导用例：[Bridge networking](https://github.com/docker/labs/blob/master/networking/A2-bridge-networking.md)。 2199 | 2200 | 2201 | 2202 | #### overlay 2203 | 2204 | `overlay` 驱动在多个 `swarm mode` 节点之间建立一个命名子网，这是一个跨主机的虚拟网络。 2205 | 2206 | - 在 `swarm mode` 中如何建立 `overlay` 网络并籍此令服务跨主机正确工作，请参考 [Docker Labs](https://github.com/docker/labs/blob/master/README.md) 的和网络相关的辅导用例： [Overlay networking and service discovery](https://github.com/docker/labs/blob/master/networking/A3-overlay-networking.md)。 2207 | - 如果想要深究 `overlay` 是如何跨主机完成虚拟网络构建和报文如何流转的，可以参考 [Overlay Driver Network Architecture](https://github.com/docker/labs/blob/master/networking/concepts/06-overlay-networks.md)。 2208 | 2209 | 2210 | 2211 | #### host or none 2212 | 2213 | 使用主机网络栈，或者不使用网络。 2214 | 2215 | 和命令行参数 `--net=host` 以及 `--net=none` 是等价的。 2216 | 2217 | 这两种驱动及网络模型只能被用于 `docker stack` 之中。如果你正在使用 `docker compose` 相关指令，请使用 `network_mode` 来指定它们。 2218 | 2219 | If you want to use a particular network on a common build, use [network] as mentioned in the second yaml file example. 2220 | 2221 | 使用内建的网络模型，例如 `host` 和 `none`，语法上有一点点需要注意的地方：如果用 `host` 或 `none` 这样的名字定义一个外部网络（注意你并不需要真的创建他们，这两者都属于Docker内置的网络模型），那么在 Compose 编排文件中引用它们时你需要使用 `hostnet` 或 `nonet`，如同这样： 2222 | 2223 | ```yaml 2224 | version: "3.7" 2225 | services: 2226 | web: 2227 | networks: 2228 | hostnet: {} 2229 | 2230 | networks: 2231 | hostnet: 2232 | external: true 2233 | name: host 2234 | 2235 | --- 2236 | services: 2237 | web: 2238 | ... 2239 | build: 2240 | ... 2241 | network: host 2242 | context: . 2243 | ... 2244 | services: 2245 | web: 2246 | ... 2247 | networks: 2248 | nonet: {} 2249 | 2250 | networks: 2251 | nonet: 2252 | external: true 2253 | name: none 2254 | ``` 2255 | 2256 | 2257 | 2258 | ### `driver_opts` 2259 | 2260 | 指定一组键值对表示的选项集，以传递给网络驱动程序。它们是和驱动程序密切相关的，所以具体的可用参数应该参考对应的驱动程序文档。 2261 | 2262 | ```yaml 2263 | driver_opts: 2264 | foo: "bar" 2265 | baz: 1 2266 | ``` 2267 | 2268 | 2269 | 2270 | ### `attachable` 2271 | 2272 | > since v3.2+ 2273 | 2274 | 只能用于 `driver: overlay` 的场景。 2275 | 2276 | 如果被设置为 `true`，独立运行的容器也能被附着在该网络之中。如果独立运行的容器实例被附着到了一个 overlay 网络中，那么容器中的服务与单独的容器实例之间能够互相通讯。请注意你甚至可以附着其他 Docker daemon 中的容器实例到本 overlay 网络中。 2277 | 2278 | ```yaml 2279 | networks: 2280 | mynet1: 2281 | driver: overlay 2282 | attachable: true 2283 | ``` 2284 | 2285 | 2286 | 2287 | ### `enable_ipv6` 2288 | 2289 | 在该网络/子网中启用 IPv6。 2290 | 2291 | >在 v3+ 中不被支持。 2292 | > 2293 | >`enable_ipv6` 需要你使用 v2 的编排格式，而且也不能被用于 swarm mode 中。 2294 | 2295 | 2296 | 2297 | ### `ipam` 2298 | 2299 | 自定义 IPAM 配置。每一项子配置都是可选参数。 2300 | 2301 | - `driver`: 自定义 IPAM 驱动程序，而不使用默认值 2302 | - `config`: 一个列表，包含一到多个配置块。每个配置块具有下列子参数： 2303 | - `subnet`: CIDR格式的子网定义，以划定一个网段。 2304 | 2305 | 一个完整的例子： 2306 | 2307 | ```yaml 2308 | ipam: 2309 | driver: default 2310 | config: 2311 | - subnet: 172.28.0.0/16 2312 | ``` 2313 | 2314 | > **NOTE**：附加IPAM如 `gateway` 只在 v2 中可用。 2315 | 2316 | 2317 | 2318 | ### `internal` 2319 | 2320 | 默认时，Docker也会连接到一个桥接网络以提供外部可连接性。如果你想建立一个外部的隔离的 overlay 网络，请设置本选项为 `true`。 2321 | 2322 | 2323 | 2324 | ### `labels` 2325 | 2326 | 使用 [Docker labels](https://docs.docker.com/engine/userguide/labels-custom-metadata/) 为容器添加元数据。可以是数组格式或者字典格式。 2327 | 2328 | 我们建议你使用反向DNS标注方式，为你的元数据表键添加反向域名前缀，从而避免潜在的和其它应用的相同名字的表键发生冲突： 2329 | 2330 | ```yaml 2331 | labels: 2332 | com.example.description: "Financial transaction network" 2333 | com.example.department: "Finance" 2334 | com.example.label-with-empty-value: "" 2335 | labels: 2336 | - "com.example.description=Financial transaction network" 2337 | - "com.example.department=Finance" 2338 | - "com.example.label-with-empty-value" 2339 | ``` 2340 | 2341 | 2342 | 2343 | ### `external` 2344 | 2345 | 如果设置为 `true`，那么本网络是在 Compose 编排文件之外被创建和管理的。此时 `dockercompose up` 不会试图创建它，如果网络并不存在则返回一个错误。 2346 | 2347 | 对于 v3.3 以及更低版本的格式，`external` 不可与 `driver`, `driver_opts`, `ipam`, `internal` 等连用。此限制在 v3.4+ 之后被取消。 2348 | 2349 | 下面的例子里，`proxy` 是一个外部世界中的网关，Compose将会寻找通过 `docker network create outside` 所建立的 `outside` 外部网络，而不是试图去自动建立一个名为 `[projectname]_outside` 的新网络： 2350 | 2351 | ```yaml 2352 | version: "3.7" 2353 | 2354 | services: 2355 | proxy: 2356 | build: ./proxy 2357 | networks: 2358 | - outside 2359 | - default 2360 | app: 2361 | build: ./app 2362 | networks: 2363 | - default 2364 | 2365 | networks: 2366 | outside: 2367 | external: true 2368 | ``` 2369 | 2370 | > `external.name` 在 v3.5 及之后已经被废弃，请改用 `name`。 2371 | 2372 | 你也可以单独指定一个网络名用于在Compose编排文件内被引用。 2373 | 2374 | 2375 | 2376 | ### `name` 2377 | 2378 | > since v3.5 2379 | 2380 | 为网络设置一个自定义名字。名字的值可被用于解决具有特殊字符名字的卷。注意该值被原样使用，引号不会被忽略，也不会被添加上栈名字前缀。 2381 | 2382 | ```yaml 2383 | version: "3.7" 2384 | networks: 2385 | network1: 2386 | name: my-app-net 2387 | ``` 2388 | 2389 | `name` 可以与 `external` 一起连用： 2390 | 2391 | ```yaml 2392 | version: "3.7" 2393 | networks: 2394 | network1: 2395 | external: true 2396 | name: my-app-net 2397 | ``` 2398 | 2399 | 2400 | 2401 | 2402 | 2403 | 2404 | 2405 | ## 配置项编排格式手册 - `configs` 2406 | 2407 | 顶级的 `configs` 章节声明，定义了一个配置项或者其参考，该配置项可以被授权给栈内服务使用。配置项的来源可以是 `file` 或 `external`。 2408 | 2409 | - `file`: 配置项的内容在一个宿主机文件中。 2410 | - `external`: 如果设置为 `true`，表示该配置项已经创建就绪了。Docker将不会试图建立它，而是在起不存在时生成一个 `config not found` 错误。 2411 | - `name`: 该配置项在 Docker 中的名字。名字的值可被用于解决具有特殊字符名字的卷。注意该值被原样使用，引号不会被忽略，也不会被添加上栈名字前缀。 2412 | 2413 | 下面的例子中，当作为栈的一部分被部署时，`my_first_config` 会被自动创建并命名为 `_my_first_config`，至于 `my_second_config` 是已经存在的。 2414 | 2415 | ```yaml 2416 | configs: 2417 | my_first_config: 2418 | file: ./config_data 2419 | my_second_config: 2420 | external: true 2421 | ``` 2422 | 2423 | 另一种变化是外部配置项带有 `name` 定义的情况，此时该配置项在 Compose 中可以被以 `redis_config` 为名进行参考和使用： 2424 | 2425 | ```yaml 2426 | configs: 2427 | my_first_config: 2428 | file: ./config_data 2429 | my_second_config: 2430 | external: 2431 | name: redis_config 2432 | ``` 2433 | 2434 | 你仍需在栈内为每个服务声明 `configs` 章节以获得访问配置项的权利，参考 [grant access to the config](#configs)。 2435 | 2436 | 2437 | 2438 | ## 敏感信息项编排格式手册 - `secrets` 2439 | 2440 | 顶级的 `secrets` 章节声明，定义了一个敏感信息项或者其参考，该敏感信息项可以被授权给栈内服务使用。敏感信息项的来源可以是 `file` 或 `external`。 2441 | 2442 | - `file`: 敏感信息项的内容在一个宿主机文件中。 2443 | - `external`: 如果设置为 `true`，表示该敏感信息项已经创建就绪了。Docker将不会试图建立它，而是在起不存在时生成一个 `secret not found` 错误。 2444 | - `name`: 该敏感信息项在 Docker 中的名字。名字的值可被用于解决具有特殊字符名字的卷。注意该值被原样使用，引号不会被忽略，也不会被添加上栈名字前缀。 2445 | 2446 | 下面的例子中，当作为栈的一部分被部署时，`my_first_secret` 会被自动创建并命名为 `_my_first_secret`，至于 `my_second_secret` 是已经存在的。 2447 | 2448 | ```yaml 2449 | secrets: 2450 | my_first_secret: 2451 | file: ./secret_data 2452 | my_second_secret: 2453 | external: true 2454 | ``` 2455 | 2456 | 另一种变化是外部配置项带有 `name` 定义的情况，此时该配置项在 Compose 中可以被以 `redis_secret` 为名进行参考和使用。 2457 | 2458 | #### Compose File v3.5 及更高版本 2459 | 2460 | ```yaml 2461 | secrets: 2462 | my_first_secret: 2463 | file: ./secret_data 2464 | my_second_secret: 2465 | external: true 2466 | name: redis_secret 2467 | ``` 2468 | 2469 | ### Compose File v3.4 和更低版本 2470 | 2471 | ``` 2472 | my_second_secret: 2473 | external: 2474 | name: redis_secret 2475 | ``` 2476 | 2477 | 你仍需在栈内为每个服务声明 `secret` 章节以获得访问敏感信息项的权利，参考 [grant access to the secret](#secrets)。 2478 | 2479 | 2480 | 2481 | 2482 | 2483 | 2484 | 2485 | 2486 | 2487 | ## 变量替换 2488 | 2489 | Compose编排文件中可以使用环境变量。当 `docker-compose` 运行时，Compose 从 Shell 环境变量中抽取变量值。例如，假设操作系统的环境变量中包含 `POSTGRES_VERSION=9.3` 的定义，那么以下定义 2490 | 2491 | ```yaml 2492 | db: 2493 | image: "postgres:${POSTGRES_VERSION}" 2494 | ``` 2495 | 2496 | 等价于 2497 | 2498 | ```yaml 2499 | db: 2500 | image: "postgres:9.3" 2501 | ``` 2502 | 2503 | 如果环境变量并不存在或者为空串，那么它就被当做是空字符串。 2504 | 2505 | 你可以通过 `.env` 文件来为环境变量设定缺省值。Compose 将会自动查找当前文件夹中的 `.env` 文件以获得环境变量的值。 2506 | 2507 | > **IMPORTANT**: 注意 `.env` 文件只在 `docker-compose up` 场景中有效，而在 `docker stack deploy` 时它并不会被使用。 2508 | 2509 | 两种语法 `$VARIABLE` 和 `${VARIABLE}` 都是可用的。此外在 v2.1 格式中，类似于 Shell 语法的如下形式也可以被使用： 2510 | 2511 | - `${VARIABLE:-default}` 将会返回 `default`，如果环境变量 `VARIABLE` 为空字符串或未被设置的话。 2512 | - `${VARIABLE-default}` 将会返回 `default`，如果环境变量 `VARIABLE` 未被设置的话。 2513 | 2514 | 类似地，下面的语法有助于指定一个明确的值： 2515 | 2516 | - `${VARIABLE:?err}` 将会产生错误信息 `err`，如果环境变量 `VARIABLE` 为空或未被设置的话。 2517 | - `${VARIABLE?err}` 将会产生错误信息 `err`，如果环境变量 `VARIABLE` 未被设置的话。 2518 | 2519 | 其他的 Shell 语法特性并未被支持，例如 `${VARIABLE/foo/bar}`。 2520 | 2521 | 如果需要一个美元符号的话，请使用 `$$`。此时 `$$` 不再参与环境变量替换的解释。如下例： 2522 | 2523 | ```yaml 2524 | web: 2525 | build: . 2526 | command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE" 2527 | ``` 2528 | 2529 | 如果你忘记了这个规则而使用了一个 `$` 单个字符的话，Compose 会警告你： 2530 | 2531 | `The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.` 2532 | 2533 | 2534 | 2535 | 2536 | 2537 | 2538 | 2539 | ## 扩展字段 2540 | 2541 | > since v3.4 2542 | 2543 | 通过扩展字段，能够重用编排配置片段。它们可以是自由的格式，前提是你将它们定义在 yaml 文档的顶级，并且其章节名以 `x-` 开头： 2544 | 2545 | ```yaml 2546 | version: '3.4' 2547 | x-custom: 2548 | items: 2549 | - a 2550 | - b 2551 | options: 2552 | max-size: '12m' 2553 | name: "custom" 2554 | ``` 2555 | 2556 | > **NOTE** 2557 | > 2558 | > 从 v3.7 开始（对于 3.x 系列），或者从 v2.4 开始（对于 2.x 系列），扩展字段也可以被放在 服务，卷，网络，配置项以及敏感信息项顶级章节之下的第一级。 2559 | > 2560 | > 如同这样： 2561 | > 2562 | > ```yaml 2563 | > version: '3.7' 2564 | > services: 2565 | > redis: 2566 | > # ... 2567 | > x-custom: 2568 | > items: 2569 | > - a 2570 | > - b 2571 | > options: 2572 | > max-size: '12m' 2573 | > name: "custom" 2574 | > ``` 2575 | 2576 | 所谓的自由格式，是指这些定义并不被 Compose 所解释。然而当你在某个地方插入它们的引用时，它们会被展开到插入点，然后再结合上下文被 Compose 解释具体的语义。这使用了 [YAML anchors](http://www.yaml.org/spec/1.2/spec.html#id2765878) 语法。 2577 | 2578 | 例如，如果你的多个服务都会使用相同的日志记录选项： 2579 | 2580 | ```yaml 2581 | logging: 2582 | options: 2583 | max-size: '12m' 2584 | max-file: '5' 2585 | driver: json-file 2586 | ``` 2587 | 2588 | 你可以这样定义： 2589 | 2590 | ```yaml 2591 | x-logging: 2592 | &default-logging 2593 | options: 2594 | max-size: '12m' 2595 | max-file: '5' 2596 | driver: json-file 2597 | 2598 | services: 2599 | web: 2600 | image: myapp/web:latest 2601 | logging: *default-logging 2602 | db: 2603 | image: mysql:latest 2604 | logging: *default-logging 2605 | ``` 2606 | 2607 | 通过 [YAML merge type](http://yaml.org/type/merge.html) 语法，你也可以在插入扩展字段定义是覆盖某些子选项。例如： 2608 | 2609 | ```yaml 2610 | version: '3.4' 2611 | x-volumes: 2612 | &default-volume 2613 | driver: foobar-storage 2614 | 2615 | services: 2616 | web: 2617 | image: myapp/web:latest 2618 | volumes: ["vol1", "vol2", "vol3"] 2619 | volumes: 2620 | vol1: *default-volume 2621 | vol2: 2622 | << : *default-volume 2623 | name: volume02 2624 | vol3: 2625 | << : *default-volume 2626 | driver: default 2627 | name: volume-local 2628 | ``` 2629 | 2630 | 2631 | 2632 | 2633 | 2634 | ## Compose 文档参考 2635 | 2636 | - [User guide](https://docs.docker.com/compose/) 2637 | - [Installing Compose](https://docs.docker.com/compose/install/) 2638 | - [Compose file versions and upgrading](https://docs.docker.com/compose/compose-file/compose-versioning/) 2639 | - [Get started with Docker](https://docs.docker.com/get-started/) 2640 | - [Samples](https://docs.docker.com/samples/) 2641 | - [Command line reference](https://docs.docker.com/compose/reference/) 2642 | 2643 | 2644 | 2645 | ## 结束 2646 | 2647 | - 原文：https://docs.docker.com/compose/compose-file/ 。 2648 | - 译文：[https://github.com/hedzr/docker-compose-file-format](https://github.com/hedzr/docker-compose-file-format)。 2649 | 2650 | 2651 | 2652 | 2653 | 2654 | 2655 | 2656 | 2657 | 2658 | 2659 | 2660 | 2661 | 2662 | 2663 | 2664 | 2665 | 2666 | 2667 | 2668 | 2669 | 2670 | 2671 | 2672 | 2673 | 2674 | 2675 | 2676 | 2677 | 2678 | 2679 | 2680 | 2681 | 2682 | 2683 | 2684 | 2685 | 2686 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ~~docker-compose 编排指南 (v3.8) [ARCHIVED] ~~ 2 | 3 | 4 | 5 | ## ARCHIVED 6 | 7 | > Docker 发生了很多变化，Docker 公司也是。其中一个变化是：Dockerfile 以及 Docker Compose File 的格式现在一方面停止于 v3.8，一方面重新开始发展。 8 | > 9 | > 新的发展从具体的编排格式来讲的确还是沿袭旧格式的，但也确实有些东西已经变了。需要检索新文件格式文档的话，应该去 [Compose Specification repository](https://github.com/compose-spec/compose-spec) 和 [compose-spec.io](https://compose-spec.io/)。 10 | 11 | 本 repo 现在不再跟随 Docker 的新格式，就此存档。 12 | 13 | 再见。 14 | 15 | ## 缘起 16 | 17 | 关于 docker-compose 的安装，关于 docker 的基本介绍，不在本文的指导范围内。 18 | 19 | 这篇文章基本上是 docker-compose YAML 文件格式的严格的英译中。这么做，缘起于昨天想起扫描一下 docker-compose 编排中怎么使用 `${PWD}` 的问题，结果中文没有一点帮助，还是官网最终解决了我的模糊之处。因此我觉得还是应该做一篇比较严谨的译文以及说明，来阐释 docker-compose 编排的各项细节。 20 | 21 | 以下，我们主要是介绍 [docker-compose 编排文件格式版本3](https://docs.docker.com/compose/compose-file/) 的各项细节。 22 | 23 | 阅读本文，你应该有 docker-compose 的基本认识，至少有基本的早期（版本2）编排格式的了解。 24 | 25 | 26 | 27 | ### 关于授权 28 | 29 | 原文 30 | 31 | 译文从属于原文。 32 | 33 | 译文：https://hedzr.github.io/devops/docker/docker-compose-file-format-v3.8/ 34 | 35 | GitHub： 36 | 37 | 译文 本身以 MIT 方式（请忽略 hedzr.github.io 站台级 CC4 许可申明，遵循 repo 本身的申明）分发。 38 | 39 | 40 | 41 | ### v3.8 说明 42 | 43 | 上一次我做了一个旧的译文：[docker-compose 编排指南 (v3.7)](../docker-compose-file-format/) (@Original: )。这是基于 v3.7 的。今次的译文是对其的一个更新。不得不说，这种查漏补缺挺烦人的。 44 | 45 | 46 | 47 | ### 阅读建议 48 | 49 | 请在 github pages 处浏览我的博客版本，那里有目录边栏帮助你更好地导航，并且总是会采纳这里的最新版本： 50 | 51 | https://hedzr.github.io/devops/docker/docker-compose-file-format-v3.8/ 52 | 53 | 54 | 55 | 56 | 57 | ## 特别添加 58 | 59 | #### 编排文件结构与示例 60 | 61 | 这是一个版本3+的典型文件结构样本： 62 | 63 | ```yaml 64 | version: "3.7" # 适用于 v3.8 没问题 65 | services: 66 | 67 | redis: 68 | image: redis:alpine 69 | ports: 70 | - "6379" 71 | networks: 72 | - frontend 73 | deploy: 74 | replicas: 2 75 | update_config: 76 | parallelism: 2 77 | delay: 10s 78 | restart_policy: 79 | condition: on-failure 80 | 81 | db: 82 | image: postgres:9.4 83 | volumes: 84 | - db-data:/var/lib/postgresql/data 85 | networks: 86 | - backend 87 | deploy: 88 | placement: 89 | constraints: [node.role == manager] 90 | 91 | vote: 92 | image: dockersamples/examplevotingapp_vote:before 93 | ports: 94 | - "5000:80" 95 | networks: 96 | - frontend 97 | depends_on: 98 | - redis 99 | deploy: 100 | replicas: 2 101 | update_config: 102 | parallelism: 2 103 | restart_policy: 104 | condition: on-failure 105 | 106 | result: 107 | image: dockersamples/examplevotingapp_result:before 108 | ports: 109 | - "5001:80" 110 | networks: 111 | - backend 112 | depends_on: 113 | - db 114 | deploy: 115 | replicas: 1 116 | update_config: 117 | parallelism: 2 118 | delay: 10s 119 | restart_policy: 120 | condition: on-failure 121 | 122 | worker: 123 | image: dockersamples/examplevotingapp_worker 124 | networks: 125 | - frontend 126 | - backend 127 | deploy: 128 | mode: replicated 129 | replicas: 1 130 | labels: [APP=VOTING] 131 | restart_policy: 132 | condition: on-failure 133 | delay: 10s 134 | max_attempts: 3 135 | window: 120s 136 | placement: 137 | constraints: [node.role == manager] 138 | 139 | visualizer: 140 | image: dockersamples/visualizer:stable 141 | ports: 142 | - "8080:8080" 143 | stop_grace_period: 1m30s 144 | volumes: 145 | - "/var/run/docker.sock:/var/run/docker.sock" 146 | deploy: 147 | placement: 148 | constraints: [node.role == manager] 149 | 150 | networks: 151 | frontend: 152 | backend: 153 | 154 | volumes: 155 | db-data: 156 | ``` 157 | 158 | 159 | 160 | 在这个样本中，顶级结构由 `version`，`services`，`networks`，`volumes` 等等标签构成。这与版本2并没有什么翻天覆地的区别。 161 | 162 | 163 | 164 | 在 `services` 章节中，你可以定义若干个服务，每个服务通常运转着一个容器，这些服务构成了一个整体的设施栈，又或是服务群。 165 | 166 | 一般来说我们会把一堆拉拉杂杂的东西，例如一堆微服务什么的，编排成一个服务栈，让他们整体对外服务，从而避免细节外露，也可以加强架构设计弹性和对整个服务栈进行伸缩（而不是面对大批微服务去逐个处理）。 167 | 168 | 169 | 170 | #### [Dockerfile] 关于 `ENTRYPOINT` 和 `CMD` 171 | 172 | ##### [**Docker RUN vs CMD vs ENTRYPOINT - Go in Big Data**](https://goinbigdata.com/docker-run-vs-cmd-vs-entrypoint/) 173 | 174 | ##### In a nutshell 175 | 176 | - RUN executes command(s) in a new layer and creates a new image. E.g., it is often used for installing software packages. 177 | - CMD sets default command and/or parameters, which can be overwritten from command line when docker container runs. 178 | - ENTRYPOINT configures a container that will run as an executable. 179 | 180 | 在 Dockerfile 中讨论这三条命令： 181 | 182 | 首先，`RUN` 不考虑，其用途可以被视作执行一条Shell指令。 183 | 184 | `CMD` 和 `ENTRYPOING` 相似但实际上区别较大：`CMD` 指定默认命令及其命令行参数、或者命令行参数的结尾的部分，并且能够在启动容器时被覆盖（通过外部命令行指定的方式），`ENTRYPOINT` 指定该容器被运行时的启动命令，可以附带命令行参数，这条命令在被实际执行时还会附加 `CMD` 所指定的内容作为其命令行的结尾部分。 185 | 186 | 187 | 188 | ##### 典型用法 189 | 190 | 所以一个惯用法是： 191 | 192 | ```dockerfile 193 | ENTRYPOINT ["/bin/echo", "Hello"] 194 | CMD ["world"] 195 | ``` 196 | 197 | 然后执行该容器的效果类似于： 198 | 199 | ```bash 200 | $ docker run -it test-container 201 | Hello world 202 | $ docker run -it test-container David 203 | Hello David 204 | ``` 205 | 206 | 207 | 208 | ##### 用于你的容器 209 | 210 | 所以对于自定义容器来说，你的主要应用程序的路径可以被用作 `ENTRYPOINT` 而在 `CMD` 中提供默认参数： 211 | 212 | ```dockerfile 213 | ENTRYPOINT ["/usr/local/app/my-app"] 214 | CMD ["--help"] 215 | ``` 216 | 217 | 这将会包装你的 my-app 像一个外露的工具，默认时显示其帮助屏，你可以指定参数去运行 my-app： 218 | 219 | ```bash 220 | $ docker run -it my-app-container 221 | [... help screen here ...] 222 | $ docker run -it my-app-container server run --foreground 223 | [ 等同于执行 my-app server run --foreground ] 224 | ``` 225 | 226 | 227 | 228 | 229 | 230 | #### [Dockerfile] 多遍构建 231 | 232 | 多遍构建被典型地用于CI/CD。 233 | 234 | 例如步骤0可以被命名为 `builder`，负责从源码编译到目标文件，而步骤1则从步骤0中抽出目标文件用于部署打包，并生成最终的容器镜像，随后步骤0的中间层则被抛弃（仅指不被打包在结果容器中，实际上这些中间层在 Docker 的构建缓存中仍然是存在且可以被重用的），这些中间层不会出现在最终容器镜像中，从而有效地缩减了最终容器镜像的尺寸，而这个结果也是从语义上、从逻辑上被自洽的。 235 | 236 | 下面有一个 Golang 应用程序的多遍构建实例，尽管它包含了一些与 Docker 构建无关的细节，但作为一个真实世界中的案例，想必能够带给您更充分的展示（源码来自 https://github.com/hedzr/awesome-tool/blob/master/Dockerfile）： 237 | 238 | ```dockerfile 239 | ARG BASE_BUILD_IMAGE 240 | FROM ${BASE_BUILD_IMAGE:-golang:1.15} AS builder 241 | 242 | ARG VERSION 243 | ARG W_PKG 244 | ARG GO111MODULE 245 | ARG GOPROXY 246 | ARG CN 247 | ARG WORKDIR 248 | ARG APPNAME 249 | 250 | # docker build --build-arg CN=1 -t awesome-tool:latest . 251 | 252 | ENV AN=${APPNAME:-awesome-tool} 253 | ENV WDIR=${WORKDIR:-/var/lib/$AN} 254 | ENV GIT_REVISION "" 255 | ENV GOVERSION "1.15" 256 | ENV BUILDTIME "" 257 | ENV LDFLAGS "" 258 | 259 | WORKDIR /go/src/github.com/hedzr/$AN/ 260 | COPY . . 261 | RUN ls -ls ./; \ 262 | W_PKG=${W_PKG:-github.com/hedzr/cmdr/conf}; \ 263 | GOPROXY=${GOPROXY:-https://goproxy.io,direct}; \ 264 | V1=$(grep -E "Version[ \t]+=[ \t]+" doc.go|grep -Eo "[0-9.]+"); \ 265 | VERSION=${VERSION:-$V1}; \ 266 | GIT_REVISION="$(git rev-parse --short HEAD)"; \ 267 | GOVERSION="$(go version)"; \ 268 | BUILDTIME="$(date -u '+%Y-%m-%d_%H-%M-%S')"; \ 269 | LDFLAGS="-s -w \ 270 | -X '$W_PKG.Githash=$GIT_REVISION' \ 271 | -X '$W_PKG.GoVersion=$GOVERSION' \ 272 | -X '$W_PKG.Buildstamp=$BUILDTIME' \ 273 | -X '$W_PKG.Version=$VERSION'"; \ 274 | echo;echo;echo "Using GOPROXY: $GOPROXY";echo " CN: $CN";echo; \ 275 | CGO_ENABLED=0 GOOS=linux go build -v -a -installsuffix cgo \ 276 | -ldflags "$LDFLAGS" \ 277 | -o bin/$AN ./cli && \ 278 | ls -la bin/ 279 | 280 | 281 | ARG BASE_IMAGE 282 | FROM ${BASE_IMAGE:-alpine:latest} 283 | 284 | ARG CN 285 | ARG VERSION 286 | ARG WORKDIR 287 | ARG CONFDIR 288 | ARG APPNAME 289 | 290 | ENV AN=${APPNAME:-awesome-tool} 291 | ENV WDIR=${WORKDIR:-/var/lib/$AN} 292 | ENV CDIR=${CONFDIR:-/etc/$AN} 293 | 294 | LABEL by="hedzr" \ 295 | version="$VERSION" \ 296 | description="awesome-tool a command-line tool to retrieve the stars of all repos in an awesome-list" 297 | 298 | COPY --from=builder /go/src/github.com/hedzr/$AN/ci/etc/$AN /etc/$AN 299 | 300 | RUN ls -la $CDIR/ $CDIR/conf.d && echo " CN: $CN"; \ 301 | [[ "$CN" != "" ]] && { \ 302 | cp /etc/apk/repositories /etc/apk/repositories.bak; \ 303 | echo "http://mirrors.aliyun.com/alpine/latest-stable/main/" > /etc/apk/repositories; \ 304 | echo;echo;echo "apk updating...";apk update; }; \ 305 | apk --no-cache add ca-certificates && \ 306 | mkdir -p $WDIR/output /var/log/$AN /var/run/$AN && \ 307 | ls -la $WDIR/output /var/log/$AN /var/run/$AN 308 | 309 | 310 | VOLUME [ "$WDIR/output", "$CDIR/conf.d" ] 311 | WORKDIR $WDIR 312 | COPY --from=builder /go/src/github.com/hedzr/$AN/bin/$AN . 313 | RUN echo $WDIR && echo $AN && ls -la $WDIR 314 | 315 | ENTRYPOINT [ "./awesome-tool" ] 316 | CMD [ "--help" ] 317 | ``` 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | ## 编排格式版本3 326 | 327 | ### 历史 328 | 329 | 版本3是自 docker-engine 1.13 推出以来 docker-compose 所支持的格式。这之前 docker 在 1.12 中推出了 swarm mode 来构建一个虚拟网络中的虚拟计算资源，同时也大幅度改进了 docker 的网络以及存储的支持。 330 | 331 | 对于 docker-compose 编排格式与 docker-engine 之间的关系，下面这张表（摘自官网）有清晰的对照。 332 | 333 | | **Compose file format** | **Docker Engine release** | 334 | | :---------------------- | :------------------------ | 335 | | 3.8 | 19.03.0+ | 336 | | 3.7 | 18.06.0+ | 337 | | 3.6 | 18.02.0+ | 338 | | 3.5 | 17.12.0+ | 339 | | 3.4 | 17.09.0+ | 340 | | 3.3 | 17.06.0+ | 341 | | 3.2 | 17.04.0+ | 342 | | 3.1 | 1.13.1+ | 343 | | 3.0 | 1.13.0+ | 344 | | 2.4 | 17.12.0+ | 345 | | 2.3 | 17.06.0+ | 346 | | 2.2 | 1.13.0+ | 347 | | 2.1 | 1.12.0+ | 348 | | 2.0 | 1.10.0+ | 349 | | 1.0 | 1.9.1.+ | 350 | 351 | 352 | 353 | ## 编排格式手册 - `service` 配置参考 354 | 355 | > 接下来会是一个参考手册应有的章节结构，我们按照字母顺序列列举出了服务编排的指令，例如 `ports`，`volumes`，`cmd`，`entry` 等等。 356 | 357 | 358 | 359 | Compose 文件是一个 YAML格式的文本文件，其中定义了 service、networks 以及 volumes。缺省时 docker-compose 使用和检索 `./docker-compose.yml` 文件并解释之。 360 | 361 | > **Tip**: 你总是可以使用 `.yml` 或 `.yaml` 作为该脚本文件的后缀，它们都会正确工作。 362 | 363 | service （服务）的配置包含若干定义，它们指明了如何将一个容器运行为服务，这些定义实际上会被传递给 `docker run` 作为其命令行参数的一部分。同样的道理，networks、volumes 等等的定义也采用同样的原理去影响诸如 `docker network create`，或者 `docker volume create` 等命令的实际运行。 364 | 365 | 你可以使用在配置定义值中使用环境变量，它们有类似于 BASH 变量替代的语法，你可以以 `${VARIABLE}`，请参阅 [变量替换](#变量替换) 小节的深入探讨。 366 | 367 | 接下来本章节中列举所有有效的服务配置项。 368 | 369 | ### `build` 370 | 371 | 该选项被用于构建。 372 | 373 | `build` 可以是一个指向构建上下文的路径字符串，例如： 374 | 375 | ```yaml 376 | version: "3.8" 377 | services: 378 | webapp: 379 | build: ./dir 380 | ``` 381 | 382 | 也可以是一个更详细的定义。这包括了 `context` 项所指定的路径，以及可选的 `dockerfile` 文件和构建参数 `args`： 383 | 384 | ```yaml 385 | version: "3.8" 386 | services: 387 | webapp: 388 | build: 389 | context: ./dir 390 | dockerfile: Dockerfile-alternate 391 | args: 392 | buildno: 1 393 | ``` 394 | 395 | 如果你在指定了 `build` 的同时还指定了 `image`，那么构建的结果会被标记为相应的名字，这就好像 `docker build -t container-name:tag dir` 做的那样： 396 | 397 | ```yaml 398 | build: "./dir" 399 | image: "company/webapp:v1.1.9" 400 | ``` 401 | 402 | > 对于 YAML 而言，避免歧义的安全做法是对字符串加上引号包围。 403 | 404 | 上面这个例子，会找到 `./dir` 文件夹中的构建上下文（默认是寻找到 `Dockerfile`）并完成构建，最后将其标记为 `company/webapp` 的名字，以及 `v1.1.9` 的 Tag。 405 | 406 | > **NOTE** 当用在docker stack部署场景时： 407 | > 408 | > `build` 选项会被忽略。 409 | 410 | 411 | 412 | #### `context` 413 | 414 | 可以是一个包含 `Dockerfile` 的文件夹，也可以是一个指向 git repository 的 URL。 415 | 416 | 如果指定了一个相对路径，那么这个路径是相对于 `docker-compose.yml` 文件的。这个路径也会被传送给 Docker daemon 用于进行构建。 417 | 418 | docker-compose 发动构建动作和标记构建结果（按照`image`名字），在那之后按照对应的名字使用它。 419 | 420 | ```yaml 421 | build: 422 | context: ./dir 423 | ``` 424 | 425 | 426 | 427 | #### `dockerfile` 428 | 429 | 可以指定不同于默认名称 `Dockerfile` 的其它文件名用于构建。注意同时必须指定路径到 `context`： 430 | 431 | ```yaml 432 | build: 433 | context: . 434 | dockerfile: Dockerfile-alternate 435 | ``` 436 | 437 | 438 | 439 | #### `args` 440 | 441 | 指定构建参数。通常是指用于构建时的参数（参见 Dockerfile 中的 `ARG`）。 442 | 443 | 以下是一个简要的概述： 444 | 445 | 首先，在 Dockerfile 指定参数： 446 | 447 | ```dockerfile 448 | ARG buildno 449 | ARG gitcommithash 450 | 451 | RUN echo "Build number: $buildno" 452 | RUN echo "Based on commit: $gitcommithash" 453 | ``` 454 | 455 | 然后指定构建参数的实际值（传入Map或者数组都是可以的）： 456 | 457 | ```yaml 458 | build: 459 | context: . 460 | args: 461 | buildno: 1 462 | gitcommithash: cdc3b19 463 | ``` 464 | 465 | 或： 466 | 467 | ```yaml 468 | build: 469 | context: . 470 | args: 471 | - buildno=1 472 | - gitcommithash=cdc3b19 473 | ``` 474 | 475 | > **NOTE**: 在 Dockerfile中，如果在 `FROM` 之前指定 `ARG`，那么这个 `ARG` 对于其后的 `FROM` 闭包是无效的。 476 | > 477 | > 多个 `FROM` 分别切割出了多个构建的闭包。 478 | > 479 | > 想要 `ARG` 在每个 `FROM` 闭包中都有效，你需要在每个闭包中都指定它。 480 | > 481 | > 在 [Understand how ARGS and FROM interact](https://docs.docker.com/engine/reference/builder/#understand-how-arg-and-from-interact) 中有更详细的相关讨论。 482 | 483 | 你可以略过显式指定构建参数。此时，该参数的实际值取决于构建时运行环境。 484 | 485 | ```yaml 486 | args: 487 | - buildno 488 | - gitcommithash 489 | ``` 490 | 491 | > **NOTE**: YAML的布尔量（`true`, `false`, `yes`, `no`, `on`, `off`）必须用引号包围，以便 docker-compose正确处理。 492 | 493 | 494 | 495 | #### `cache_from` 496 | 497 | > since v3.2 498 | 499 | 指定一个映像列表，用于缓存的解决。 500 | 501 | ```yaml 502 | build: 503 | context: . 504 | cache_from: 505 | - alpine:latest 506 | - corp/web_app:3.14 507 | ``` 508 | 509 | 510 | 511 | #### `labels` 512 | 513 | > since v3.3 514 | 515 | 向构建的映像中添加元数据标签，可以是一个数组或一个字典。 516 | 517 | 我们推荐使用反向DNS标注性前缀以防止你的标签和使用者的标签相冲突： 518 | 519 | ```yaml 520 | build: 521 | context: . 522 | labels: 523 | com.example.description: "Accounting webapp" 524 | com.example.department: "Finance" 525 | com.example.label-with-empty-value: "" 526 | 527 | # anothor example 528 | build: 529 | context: . 530 | labels: 531 | - "com.example.description=Accounting webapp" 532 | - "com.example.department=Finance" 533 | - "com.example.label-with-empty-value" 534 | ``` 535 | 536 | 537 | 538 | #### `network` 539 | 540 | > Since v3.4 541 | 542 | 设置在 `RUN` 构建过程中要链接的网络，该网络也将被用于查询和提取依赖的容器。 543 | 544 | ```yaml 545 | build: 546 | context: . 547 | network: host 548 | build: 549 | context: . 550 | network: custom_network_1 551 | ``` 552 | 553 | 设为 `none` 则在构建时禁用网络查询和提取： 554 | 555 | ```yaml 556 | build: 557 | context: . 558 | network: none 559 | ``` 560 | 561 | 562 | 563 | #### `shm_size` 564 | 565 | > since v3.5 566 | 567 | 设置构建容器时的 `/dev/shm` 分区大小。整数格式按字节表示，但也可以使用字符串格式（[byte value](https://docs.docker.com/compose/compose-file/#specifying-byte-values)）： 568 | 569 | ```yaml 570 | build: 571 | context: . 572 | shm_size: '2gb' 573 | 574 | build: 575 | context: . 576 | shm_size: 10000000 577 | ``` 578 | 579 | 580 | 581 | #### `target` 582 | 583 | > since v3.4 584 | 585 | 构建定义与 Dockerfile 中的特定的步骤（Stage），参阅 [multi-stage build docs](https://docs.docker.com/engine/userguide/eng-image/multistage-build/)： 586 | 587 | ```yaml 588 | build: 589 | context: . 590 | target: prod 591 | ``` 592 | 593 | 594 | 595 | ### `cap_add`, `cap_drop` 596 | 597 | 添加或者移除容器的 Linux 能力。完整的清单可以参阅 `man 7 capabilities`。 598 | 599 | ```yaml 600 | cap_add: 601 | - ALL 602 | 603 | cap_drop: 604 | - NET_ADMIN 605 | - SYS_ADMIN 606 | ``` 607 | 608 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 609 | > 610 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 611 | 612 | Linux 能力机制很大程度上是一种安全机制。具体含义、用途和引申属于 Linux 操作系统范畴，不再赘述。 613 | 614 | 615 | 616 | ### `cgroup_parent` 617 | 618 | 可选地为容器指定一个上级 `cgroup`。`cgroup` 也是 Linux 容器化实现的最重要的基本概念之一。 619 | 620 | ```yaml 621 | cgroup_parent: m-executor-abcd 622 | ``` 623 | 624 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 625 | > 626 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 627 | 628 | 629 | 630 | ### `command` 631 | 632 | 覆盖容器内默认的 `command`. 633 | 634 | ```yaml 635 | command: bundle exec thin -p 3000 636 | ``` 637 | 638 | `command` 也可以被指定为一个列表。实际上这也是更被推荐的方式，无歧义而且安全，而且和 dockerfile 中的格式具有一致性： 639 | 640 | ```yaml 641 | command: ["bundle", "exec", "thin", "-p", "3000"] 642 | ``` 643 | 644 | 645 | 646 | ### configs 647 | 648 | 为每个服务提供具体化的访问 `config` 的权限。 649 | 650 | 一个 `config` 包含一系列的配置信息，这些信息可能被通过多种途径所创建。容器的部署引用这些配置时，可以更好地区格诸如生产环境参数这样的问题。另一方面，敏感信息也因此可以被单独隔离到一个安全的区域中，在一定程度上减少了泄露的可能性。 651 | 652 | > **NOTE**: 指定的配置必须已经存在，或者已经被定义在顶级 `configs` 中了（[defined in the top-level `configs` configuration](https://docs.docker.com/compose/compose-file/#configs-configuration-reference)）。否则整个容器栈的部署将会失败。 653 | 654 | 支持两个不同的语法变体格式。更详尽的信息应参考 [configs](https://docs.docker.com/engine/swarm/configs/)。 655 | 656 | #### 短格式 657 | 658 | 只指定配置名。容器因此可以访问配置 `/ **Note**: `config` 定义仅在 v3.3 及更高版本的 docker-compose 格式中被支持。 682 | 683 | 684 | 685 | #### 长格式 686 | 687 | 长格式提供更多的信息来表述一个 `config` 在哪儿，如何被找到，怎么被使用： 688 | 689 | - `source`: 配置名 690 | 691 | - `target`: 该配置将被挂载到容器中的路径。默认为 `/` 692 | 693 | - `uid` & `gid`: 数字值的 Linux/Unix `UID` 和 `GID`，如果没有指定则为0。Windows中不支持。 694 | 695 | - `mode`: 8进制的文件权限。默认值为 `0444`。 696 | 697 | 配置是不可写的，因为它们被挂载于临时的文件系统中。因此如果你设置了写许可，这将被忽略。 698 | 699 | 可执行位是可以被设置的。 700 | 701 | 下面的例子类似于短格式的例子： 702 | 703 | ```yaml 704 | version: "3.8" 705 | services: 706 | redis: 707 | image: redis:latest 708 | deploy: 709 | replicas: 1 710 | configs: 711 | - source: my_config 712 | target: /redis_config 713 | uid: '103' 714 | gid: '103' 715 | mode: 0440 716 | configs: 717 | my_config: 718 | file: ./my_config.txt 719 | my_other_config: 720 | external: true 721 | ``` 722 | 723 | 在这里，`redis` 容器的服务并未访问 `my_other_config`。 724 | 725 | 你可以授权一个服务访问多个配置，你也可以混用长短格式。 726 | 727 | （在顶级）定义一个配置（`config`）并未隐含着某个服务就能访问到它。 728 | 729 | 730 | 731 | ### `container_name` 732 | 733 | 指定一个自定义的容器名，而不是由 docker-compose 自己生成一个默认的。 734 | 735 | ```yaml 736 | container_name: my-web-container 737 | ``` 738 | 739 | 由于 Docker 容器名必须是唯一的，所以你无法伸缩一个自定义了容器名的服务。 740 | 741 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 742 | > 743 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 744 | 745 | 746 | 747 | ### `credential_spec` 748 | 749 | > since v3.3 750 | > 751 | > 从 v3.8 开始支持被用于组管理服务账户 gMSA（group Managed Service Account）方式。 752 | 753 | 为受控服务账户配置凭据。这个选项只被用于 Windows 容器服务。`credential_spce` 只能使用格式 `file://` or `registry://`。 754 | 755 | 当使用 `file:` 时，被参考的文件必须被置于 Docker 数据文件夹（通常是 `C:\ProgramData\Docker\`）的 `CredentialSpec` 子目录之下。下面的例子将会从 `C:\ProgramData\Docker\CredentialSpecs\my-credential-sp` 载入凭据信息： 756 | 757 | ```yaml 758 | credential_spec: 759 | file: my-credential-spec.json 760 | ``` 761 | 762 | 当使用 `registry:` 时，凭据信息将会被从 Docker daemon 主机的 Windows Registry 中读入。一个注册表表项必须位于： 763 | 764 | ``` 765 | HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs 766 | ``` 767 | 768 | 之中。 769 | 770 | 下面的例子读入 `my-credential-spec` 注册表项值： 771 | 772 | ```yaml 773 | credential_spec: 774 | registry: my-credential-spec 775 | ``` 776 | 777 | 778 | 779 | #### gMSA 配置例子 780 | 781 | 当为一个服务配置 gMSA 凭据时，参考如下的例子： 782 | 783 | ```yaml 784 | version: "3.8" 785 | services: 786 | myservice: 787 | image: myimage:latest 788 | credential_spec: 789 | config: my_credential_spec 790 | 791 | configs: 792 | my_credentials_spec: 793 | file: ./my-credential-spec.json| 794 | ``` 795 | 796 | 797 | 798 | ### `depends_on` 799 | 800 | 表示服务之间的依赖关系。服务依赖引发如下的行为： 801 | 802 | - `docker-compose up` 按照依赖顺序依次启动服务。在下面的例子中，`db` 和 `redis` 先于 `web` 被启动。 803 | - `docker-compose up SERVICE` 自动包括了 `SERVICE` 的依赖项。在下面的例子中，`docker-compose up web` 将会自动启动 `db` 和 `redis`。 804 | - `docker-compose stop` 按照依赖顺序依次停止服务。在下面的例子中，`web` 将会被先于 `db` 和 `redis` 被停止。 805 | 806 | 简单的示例如下： 807 | 808 | ```yaml 809 | version: "3.8" 810 | services: 811 | web: 812 | build: . 813 | depends_on: 814 | - db 815 | - redis 816 | redis: 817 | image: redis 818 | db: 819 | image: postgres 820 | ``` 821 | 822 | > 使用 `depends_on` 时应该注意的几件事： 823 | > 824 | > - `depends_on` 并不意味着等待 `db` 和 `redis` 就绪后才启动 `web`，而是在它们被启动后就会接着启动 `web`。如果要想等到服务就绪可用，应该参阅 [Controlling startup order](https://docs.docker.com/compose/startup-order/)。 825 | > 826 | > - 版本 3 不再支持 `condition` 表述。 827 | > 828 | > - `depends_on` 选项在部署到 swarm mode 时被忽略。 829 | > 830 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 831 | 832 | 833 | 834 | ### `deploy` 835 | 836 | > **[Version 3](https://docs.docker.com/compose/compose-file/compose-versioning/#version-3) only.** 837 | 838 | 指定和部署以及运行相关的配置。 839 | 840 | 只会对部署到一个使用 [docker stack deploy](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 的 [swarm](https://docs.docker.com/engine/swarm/) 有影响。 841 | 842 | 在 `docker-compose up` 和 `docker-compose run` 时被忽略。 843 | 844 | ```yaml 845 | version: "3.8" 846 | services: 847 | redis: 848 | image: redis:alpine 849 | deploy: 850 | replicas: 6 851 | update_config: 852 | parallelism: 2 853 | delay: 10s 854 | restart_policy: 855 | condition: on-failure 856 | ``` 857 | 858 | 几个子选项是可用的： 859 | 860 | #### `endpoint_mode` 861 | 862 | swarm. 863 | 864 | > Since **[Version 3.2](https://docs.docker.com/compose/compose-file/compose-versioning/#version-3).** 865 | 866 | 指定外部客户端连接到一个 swarm 集群时使用的服务发现方法。 867 | 868 | - `endpoint_mode: vip` - Docker 为服务请求一个虚拟IP（`VIP`）用于访问。 869 | 870 | Docker在客户端和服务的有效的工作节点之间对请求进行自动负载均衡路由。客户端无需知道服务有多少可用节点，也不必知道服务节点的IP地址和端口号。 871 | 872 | 这是默认方式。 873 | 874 | - `endpoint_mode: dnsrr` - 使用 DNS round-robin (DNSRR) 算法进行服务发现。Docker会为服务设置一个DNS条目，因而在进行对应的 DNS 解析时通过服务名称会返回一个IP地址清单。客户端因此直接选择一个具体的端点进行访问。 875 | 876 | ```yaml 877 | version: "3.8" 878 | 879 | services: 880 | wordpress: 881 | image: wordpress 882 | ports: 883 | - "8080:80" 884 | networks: 885 | - overlay 886 | deploy: 887 | mode: replicated 888 | replicas: 2 889 | endpoint_mode: vip 890 | 891 | mysql: 892 | image: mysql 893 | volumes: 894 | - db-data:/var/lib/mysql/data 895 | networks: 896 | - overlay 897 | deploy: 898 | mode: replicated 899 | replicas: 2 900 | endpoint_mode: dnsrr 901 | 902 | volumes: 903 | db-data: 904 | 905 | networks: 906 | overlay: 907 | ``` 908 | 909 | `endpoint_mode` 的选项也被同样地用作 swarm mode 命令行选项（参阅 [`docker service create`](https://docs.docker.com/engine/reference/commandline/service_create/)）。至于 docker swarm命令的一个快捷清单，可以查阅 [Swarm mode CLI commands](https://docs.docker.com/engine/swarm/#swarm-mode-key-concepts-and-tutorial)。 910 | 911 | 要学习更多关于 swarm mode 的网络模型已经服务发现机制 的知识，请查看 [Configure service discovery](https://docs.docker.com/engine/swarm/networking/#configure-service-discovery)。 912 | 913 | 914 | 915 | #### `labels` 916 | 917 | 为服务指定标签。这些标签只被作用于对应的服务，而不是被应用到服务的容器或者容器实例上。 918 | 919 | ```yaml 920 | version: "3.8" 921 | services: 922 | web: 923 | image: web 924 | deploy: 925 | labels: 926 | com.example.description: "This label will appear on the web service" 927 | ``` 928 | 929 | 要为容器设置标签的话，在 `deploy` 之外为服务指定 `labels`： 930 | 931 | ```yaml 932 | version: "3.8" 933 | services: 934 | web: 935 | image: web 936 | labels: 937 | com.example.description: "This label will appear on all containers for the web service" 938 | ``` 939 | 940 | 941 | 942 | #### `mode` 943 | 944 | 可以是 `global` 或 `replicated`。`global` 表示严格地一个 swarm node 跑一个服务，`replicated` 表示可以跑多个容器实例。默认是 `replicated`。 945 | 946 | 参阅 [swarm](https://docs.docker.com/engine/swarm/) 主题下的 [Replicated and global services](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/#replicated-and-global-services)。 947 | 948 | ```yaml 949 | version: "3.8" 950 | services: 951 | worker: 952 | image: dockersamples/examplevotingapp_worker 953 | deploy: 954 | mode: global 955 | ``` 956 | 957 | 958 | 959 | #### `placement` 960 | 961 | 指定 constaints 和 preferences。 962 | 963 | 参阅docker服务建立的相关文档以了解更多的关于 [constraints](https://docs.docker.com/engine/reference/commandline/service_create/#specify-service-constraints-constraint) 和 [preferences 的相关信息，包括相应的语法，可用的类型等等的完整描述。 964 | 965 | ```yaml 966 | version: "3.8" 967 | services: 968 | db: 969 | image: postgres 970 | deploy: 971 | placement: 972 | constraints: 973 | - node.role == manager 974 | - engine.labels.operatingsystem == ubuntu 14.04 975 | preferences: 976 | - spread: node.labels.zone 977 | ``` 978 | 979 | 980 | 981 | #### `max_replicas_per_node` 982 | 983 | > Since [version 3.8](https://docs.docker.com/compose/compose-file/compose-versioning/#version-38). 984 | 985 | 如果一个服务是可副本的 `replicated` (这是默认的), max_replicas_per_node 将会 [限制副本数量（limit the number of replicas）](https://docs.docker.com/engine/reference/commandline/service_create/#specify-maximum-replicas-per-node---replicas-max-per-node) 。 986 | 987 | 当太多任务申请新的任务节点且超出了 max_replicas_per_node 限制值时，一个 `no suitable node (max replicas per node limit exceed)` 错误将会被抛出。 988 | 989 | ```yaml 990 | version: "3.8" 991 | services: 992 | worker: 993 | image: dockersamples/examplevotingapp_worker 994 | networks: 995 | - frontend 996 | - backend 997 | deploy: 998 | mode: replicated 999 | replicas: 6 1000 | placement: 1001 | max_replicas_per_node: 1 1002 | ``` 1003 | 1004 | 1005 | 1006 | #### `replicas` 1007 | 1008 | 如果服务是 `replicated` 的，`replicas` 则为其指定一个数值，此数值指示了一个 swarm 节点上最多可以跑多少个容器实例。 1009 | 1010 | ```yaml 1011 | version: "3.7" 1012 | services: 1013 | worker: 1014 | image: dockersamples/examplevotingapp_worker 1015 | networks: 1016 | - frontend 1017 | - backend 1018 | deploy: 1019 | mode: replicated 1020 | replicas: 6 1021 | ``` 1022 | 1023 | 1024 | 1025 | #### `resources` 1026 | 1027 | 配置资源约束。 1028 | 1029 | >**NOTE**: 对于非 swarm mode 而言，这个表项替换 [older resource constraint options](https://docs.docker.com/compose/compose-file/compose-file-v2/#cpu-and-other-resources)（诸如 `cpu_shares`, `cpu_quota`, `cpuset`, `mem_limit`, `memswap_limit`, `mem_swappiness` 等在版本3之前版本中的表项）。 1030 | > 1031 | >在 [Upgrading version 2.x to 3.x](https://docs.docker.com/compose/compose-file/compose-versioning/#upgrading) 中有相应的描述。 1032 | 1033 | 这些资源约束表项都具有一个单一值，相当于 `docker service create` 中的等价物。 1034 | 1035 | 在如下的例子中，`redis` 服务被约束为不可使用超出50M的内存，单核50%的CPU使用率，同时也保留 20M 内存以及 25%的CPU使用率作为基准值。 1036 | 1037 | ```yaml 1038 | version: "3.8" 1039 | services: 1040 | redis: 1041 | image: redis:alpine 1042 | deploy: 1043 | resources: 1044 | limits: 1045 | cpus: '0.50' 1046 | memory: 50M 1047 | reservations: 1048 | cpus: '0.25' 1049 | memory: 20M 1050 | ``` 1051 | 1052 | 以下的主题描述 swarm 场景下的服务或容器资源约束的可用选项。 1053 | 1054 | ##### Out Of Memory Exceptions (OOME) 1055 | 1056 | 企图在你的服务和容器实例中使用超过系统拥有的内存，那么将得到 Out Of Memory Exception (OOME) 。此时，容器实例，或者 Docker daemon，可能会被内核的 OOM 管理器所清除。 1057 | 1058 | 要防止这样的情况发生，请确定你的应用程序合法有效地使用内存。对于这样的风险，查阅 [Understand the risks of running out of memory](https://docs.docker.com/engine/admin/resource_constraints/#understand-the-risks-of-running-out-of-memory) 以获知进一步的评估须知。 1059 | 1060 | 1061 | 1062 | #### `restart_policy` 1063 | 1064 | 指示当容器实例退出时，如何重启。替换 `restart`： 1065 | 1066 | - `condition`: 可以为 `none`, `on-failure` 或 `any` (默认为 `any`) 1067 | - `delay`: 在尝试重启之前的等候时长（默认为0）。应该为其指定一个 [duration](https://docs.docker.com/compose/compose-file/#specifying-durations)。 1068 | - `max_attempts`: 试图尝试重启多少次后放弃重启的尝试。默认为不放弃。 1069 | - `window`: 要确定一次重启是否成功，需要等候的时长。默认为无等待立即认定为已成功。应该为其指定一个 [duration](https://docs.docker.com/compose/compose-file/#specifying-durations)。 1070 | 1071 | ```yaml 1072 | version: "3.8" 1073 | services: 1074 | redis: 1075 | image: redis:alpine 1076 | deploy: 1077 | restart_policy: 1078 | condition: on-failure 1079 | delay: 5s 1080 | max_attempts: 3 1081 | window: 120s 1082 | ``` 1083 | 1084 | 1085 | 1086 | #### `rollback_config` 1087 | 1088 | > [Version 3.7 file format](https://docs.docker.com/compose/compose-file/compose-versioning/#version-37) and up 1089 | 1090 | 在滚动更新失败的场景下服务应该如何回滚： 1091 | 1092 | - `parallelism`：同时回滚的容器的数量值。如果设置为0，所有容器将被同时回滚。 1093 | - `delay`: 每个容器组被回滚前的等待时长（默认为0） 1094 | - `failure_action`: 一个回滚失败时应当执行的动作。可以是 `continue` 或 `pause`（默认为`pause`） 1095 | - `monitor`: 失败的回滚状态被更新到监视器的周期（`ns|us|ms|s|m|h`）默认为 `0s`。 1096 | - `max_failure_ratio`: 回滚时失败的可容忍的比例（默认为0） 1097 | - `order`: 回滚的操作顺序。可以为 `stop-first` 或 `start-first`（默认为 `stop-first`） 1098 | 1099 | 1100 | 1101 | #### `update_config` 1102 | 1103 | 指示服务应该如何被更新。这对于配置为滚动更新时有用： 1104 | 1105 | - `parallelism`：同时更新的容器的数量值。如果设置为0，所有容器将被同时回滚。 1106 | - `delay`: 每个容器组被更新前的等待时长（默认为0） 1107 | - `failure_action`: 一个更新失败时应当执行的动作。可以是 `continue`, `rollback` 或 `pause`（默认为`pause`） 1108 | - `monitor`: 失败的更新状态被更新到监视器的周期（`ns|us|ms|s|m|h`）默认为 `0s`。 1109 | - `max_failure_ratio`: 更新时失败的可容忍的比例（默认为0） 1110 | - `order`: 更新的操作顺序。可以为 `stop-first` 或 `start-first`（默认为 `stop-first`） 1111 | 1112 | > **NOTE**：`order` 只在 v3.4 及之后有效。 1113 | 1114 | ```yaml 1115 | version: "3.8" 1116 | services: 1117 | vote: 1118 | image: dockersamples/examplevotingapp_vote:before 1119 | depends_on: 1120 | - redis 1121 | deploy: 1122 | replicas: 2 1123 | update_config: 1124 | parallelism: 2 1125 | delay: 10s 1126 | order: stop-first 1127 | ``` 1128 | 1129 | 1130 | 1131 | #### `DOCKER STACK DEPLOY` 不支持者 1132 | 1133 | 下列的子选项（为 `docker-compose up` 和 `docker-compose run` 所支持）是在 `docker stack deploy` 中不被支持的： 1134 | 1135 | - [build](https://docs.docker.com/compose/compose-file/#build) 1136 | - [cgroup_parent](https://docs.docker.com/compose/compose-file/#cgroup_parent) 1137 | - [container_name](https://docs.docker.com/compose/compose-file/#container_name) 1138 | - [devices](https://docs.docker.com/compose/compose-file/#devices) 1139 | - [tmpfs](https://docs.docker.com/compose/compose-file/#tmpfs) 1140 | - [external_links](https://docs.docker.com/compose/compose-file/#external_links) 1141 | - [links](https://docs.docker.com/compose/compose-file/#links) 1142 | - [network_mode](https://docs.docker.com/compose/compose-file/#network_mode) 1143 | - [restart](https://docs.docker.com/compose/compose-file/#restart) 1144 | - [security_opt](https://docs.docker.com/compose/compose-file/#security_opt) 1145 | - [userns_mode](https://docs.docker.com/compose/compose-file/#userns_mode) 1146 | 1147 | > **Tip:** 请参阅 [如何为 service 服务模式和 swarm 集群模式使用卷而配置 docker-stack.yml 文件 - how to configure volumes for services, swarms, and docker-stack.yml files](https://docs.docker.com/compose/compose-file/#volumes-for-services-swarms-and-stack-files) 章节。 Volumes（卷）在 swarms 模式和 services 模式中*是*被支持的，但你只能采用命名卷，又或是与受约束于有权访问*必需*卷的节点的服务关联. 1148 | 1149 | ### `devices` 1150 | 1151 | 要被映射的设备清单。其用法和 docker 命令的 `--device` 相同。 1152 | 1153 | ``` 1154 | devices: 1155 | - "/dev/ttyUSB0:/dev/ttyUSB0" 1156 | ``` 1157 | 1158 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1159 | > 1160 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1161 | 1162 | 1163 | 1164 | ### `dns` 1165 | 1166 | 自定义 DNS 服务器列表。可以指定单一值或一个清单。 1167 | 1168 | ``` 1169 | dns: 8.8.8.8 1170 | dns: 1171 | - 8.8.8.8 1172 | - 9.9.9.9 1173 | ``` 1174 | 1175 | 1176 | 1177 | ### `dns_search` 1178 | 1179 | 自定义DNS搜索域名。可以指定单一值或一个清单。 1180 | 1181 | ``` 1182 | dns_search: example.com 1183 | dns_search: 1184 | - dc1.example.com 1185 | - dc2.example.com 1186 | ``` 1187 | 1188 | 1189 | 1190 | ### `entrypoint` 1191 | 1192 | 覆盖 dockerfile 中定义的默认的 entrypoint 值。 1193 | 1194 | ```yaml 1195 | entrypoint: /code/entrypoint.sh 1196 | ``` 1197 | 1198 | 入口点也可以是一个清单： 1199 | 1200 | ```yaml 1201 | entrypoint: 1202 | - php 1203 | - -d 1204 | - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so 1205 | - -d 1206 | - memory_limit=-1 1207 | - vendor/bin/phpunit 1208 | ``` 1209 | 1210 | > **NOTE**: 设置一个 `entrypoint` 不但覆盖 Dockerfile 中的任何 `ENTRYPOINT` 默认值，还会清理 Dockerfile 中的任何 `CMD` 默认值。所以 Dockerfile 中的 `CMD` 将会被忽略。 1211 | 1212 | 1213 | 1214 | ### `env_file` 1215 | 1216 | 从给定的文件中引入环境变量值。可以是单一值或一个清单。 1217 | 1218 | ```yaml 1219 | env_file: .env 1220 | env_file: 1221 | - ./common.env 1222 | - ./apps/web.env 1223 | - /opt/secrets.env 1224 | ``` 1225 | 1226 | 对于 `docker-compose -f FILE` 来说，`env_file` 的路径是相对于 `FILE` 所在文件夹的。 1227 | 1228 | 在 `environment` 中声明的环境变量将会覆盖掉这里所引入的值。 1229 | 1230 | 对应的文件中，每一行应该使用 `VAR=VAL` 格式定义一个环境变量。行首为 `#` 表示为注释行，和空白行一样被忽略。 1231 | 1232 | ```bash 1233 | # Set Rails/Rack environment 1234 | RACK_ENV=development 1235 | ``` 1236 | 1237 | > **NOTE**: 如果服务定义了 `build` 项，在构建过程中，由 `env_file` 所定义的环境变量并不可见。只能使用 `build` 的子选项 `args` 去定义构建时环境变量值。 1238 | 1239 | `VAL` 的值被原样照用，且不能被修改。例如如果值由引号所包围，那么值的表示量中也包含引号。 1240 | 1241 | *环境变量文件的顺序也需要被注意*。位置靠后的环境变量文件中所定义的变量值会覆盖掉早前定义的旧值。 1242 | 1243 | > **按**：原文竟然说了这么多！ 1244 | > 1245 | > Keep in mind that *the order of files in the list is significant in determining the value assigned to a variable that shows up more than once*. The files in the list are processed from the top down. For the same variable specified in file `a.env` and assigned a different value in file `b.env`, if `b.env` is listed below (after), then the value from `b.env` stands. For example, given the following declaration in `docker-compose.yml`: 1246 | 1247 | ``` 1248 | services: 1249 | some-service: 1250 | env_file: 1251 | - a.env 1252 | - b.env 1253 | ``` 1254 | 1255 | And the following files: 1256 | 1257 | ``` 1258 | # a.env 1259 | VAR=1 1260 | ``` 1261 | 1262 | and 1263 | 1264 | ``` 1265 | # b.env 1266 | VAR=hello 1267 | ``` 1268 | 1269 | `$VAR` is `hello`. 1270 | 1271 | 1272 | 1273 | ### `environment` 1274 | 1275 | 添加环境变量。可以使用一个数组或者一个字典。任何布尔量：true, false, yes, no 等等都必须用引号包围为字符串字面量。 1276 | 1277 | 只有key值的环境变量的value值依赖于 docker-compose 运行时的主机环境，这对于防止敏感信息泄露是有用的。 1278 | 1279 | ```yaml 1280 | environment: 1281 | RACK_ENV: development 1282 | SHOW: 'true' 1283 | SESSION_SECRET: 1284 | 1285 | # 或 1286 | environment: 1287 | - RACK_ENV=development 1288 | - SHOW=true 1289 | - SESSION_SECRET 1290 | ``` 1291 | 1292 | > **NOTE**: 如果服务定义了 `build` 项，在构建过程中，由 `env_file` 所定义的环境变量并不可见。只能使用 `build` 的子选项 `args` 去定义构建时环境变量值。 1293 | 1294 | 1295 | 1296 | ### `expose` 1297 | 1298 | 暴露端口到链接的服务。这些端口并不会被发布到宿主机。只能指定内部端口被用于暴露。 1299 | 1300 | ``` 1301 | expose: 1302 | - "3000" 1303 | - "8000" 1304 | ``` 1305 | 1306 | 1307 | 1308 | ### `external_links` 1309 | 1310 | 将在 `docker-compose.yml` 之外启动的容器链接到给定服务上。 1311 | 1312 | 和遗留选项 `links` 有相似的语义。 1313 | 1314 | ```yaml 1315 | external_links: 1316 | - redis_1 1317 | - project_db_1:mysql 1318 | - project_db_1:postgresql 1319 | ``` 1320 | 1321 | > **Note** 1322 | > 1323 | > 在 docker-compose.yml 之外建立的容器（The externally-created containers）必须至少连接到一个相同的网络，才能与一个定义在 docker-compose.yml 中的服务相链接 。[Links](https://docs.docker.com/compose/compose-file/compose-file-v2#links) 选项已经过时了，我们推荐使用 [networks](https://docs.docker.com/compose/compose-file/#networks) 来代替它。 1324 | 1325 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1326 | > 1327 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1328 | 1329 | 更推荐的做法是通过 `networks` 构造一个子网以进行容器之间的链接。 1330 | 1331 | 1332 | 1333 | ### `extra_hosts` 1334 | 1335 | 添加主机名映射。这些映射关系会被添加到 `/etc/hosts` 中。此功能等价于命令行参数 `--add-host`。 1336 | 1337 | ```yaml 1338 | extra_hosts: 1339 | - "somehost:162.242.195.82" 1340 | - "otherhost:50.31.209.229" 1341 | ``` 1342 | 1343 | 对于这个服务来说，在容器中的 `/etc/hosts` 文件中，相应的主机名及其IP将被建立为一个条目。例如： 1344 | 1345 | ``` 1346 | 162.242.195.82 somehost 1347 | 50.31.209.229 otherhost 1348 | ``` 1349 | 1350 | 1351 | 1352 | ### `healthcheck` 1353 | 1354 | > since v2.1 1355 | 1356 | 用于确认一个服务是否是“健康”的。参阅 [HEALTHCHECK Dockerfile instruction](https://docs.docker.com/engine/reference/builder/#healthcheck)。 1357 | 1358 | ```yaml 1359 | healthcheck: 1360 | test: ["CMD", "curl", "-f", "http://localhost"] 1361 | interval: 1m30s 1362 | timeout: 10s 1363 | retries: 3 1364 | start_period: 40s 1365 | ``` 1366 | 1367 | `interval`, `timeout` 和 `start_period` 应该被指定为 [durations](https://docs.docker.com/compose/compose-file/#specifying-durations). 1368 | 1369 | > **Note**: `start_period` 只在 v3.4 及以后可用。 1370 | 1371 | `test` 必须是一个单一字符串值或一个列表。如果是一个列表，那么第一项必须是 `NONE`, `CMD`, `CMD-SHELL` 之一。如果是一个字符串，隐含地表示一个 `CMD-SHELL` 前缀。 1372 | 1373 | ```yaml 1374 | # Hit the local web app 1375 | test: ["CMD", "curl", "-f", "http://localhost"] 1376 | ``` 1377 | 1378 | 如上述示例，但隐含调用 `/bin/sh`，和以下的形式是等效的。 1379 | 1380 | ```yaml 1381 | test: ["CMD-SHELL", "curl -f http://localhost || exit 1"] 1382 | test: curl -f https://localhost || exit 1 1383 | ``` 1384 | 1385 | 要禁用任何在映像内指定的缺省的健康检查向，可以使用 `disable: true`。这和指定 `test: ["NONE"]` 是等效的。 1386 | 1387 | ```yaml 1388 | healthcheck: 1389 | disable: true 1390 | ``` 1391 | 1392 | 1393 | 1394 | ### `image` 1395 | 1396 | 指定映像的名称。 1397 | 1398 | ```yaml 1399 | image: redis 1400 | image: ubuntu:14.04 1401 | image: tutum/influxdb 1402 | image: example-registry.com:4000/postgresql 1403 | image: a4bc65fd 1404 | ``` 1405 | 1406 | 如果映像在宿主机不存在，Compose 会尝试下拉它，除非你也指定了 `build` 项。 1407 | 1408 | 1409 | 1410 | ### `init` 1411 | 1412 | > since v3.7 1413 | 1414 | 在容器中运行一个 init 进程并转发信号。设置为 `true` 为服务使能这个特性。 1415 | 1416 | ```yaml 1417 | version: "3.8" 1418 | services: 1419 | web: 1420 | image: alpine:latest 1421 | init: true 1422 | ``` 1423 | 1424 | > 缺省的 init 进程使用二进制执行文件 [Tini](https://github.com/krallin/tini)，在需要时它将被安装于 daemon主机的位置 `/usr/libexec/docker-init` 。你也可以配置 daemon 使用一个不同的二进制文件，通过 `init-path`，参阅 [configuration option](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file)。 1425 | 1426 | 1427 | 1428 | ### `isolation` 1429 | 1430 | 指定一个容器的隔离层级/技术。在 Linux 中，仅支持 `default` 值。在 Windows 中，可以接受的值有：`default`, `process` 和 `hyperv`。 1431 | 1432 | 1433 | 1434 | ### `labels` 1435 | 1436 | 为容器添加元数据标签，参考 [Docker labels](https://docs.docker.com/engine/userguide/labels-custom-metadata/)。可以为其指定一个数组或一个字典。 1437 | 1438 | 我们建议你采用反向DNS标注方式来定义你的标签，这可以有效地避免标签名称的冲突。 1439 | 1440 | ```yaml 1441 | labels: 1442 | com.example.description: "Accounting webapp" 1443 | com.example.department: "Finance" 1444 | com.example.label-with-empty-value: "" 1445 | labels: 1446 | - "com.example.description=Accounting webapp" 1447 | - "com.example.department=Finance" 1448 | - "com.example.label-with-empty-value" 1449 | ``` 1450 | 1451 | 1452 | 1453 | ### `links` 1454 | 1455 | > 已经是一个遗留特征了。在不久的未来将被移除。 1456 | > 1457 | > 按：所以我也不精确翻译了:) 太啰嗦了。 1458 | 1459 | 链接另一个服务到本容器。可以同时制定服务名称和链接别名（`SERVICE:ALIAS`），也可以略过链接别名。 1460 | 1461 | ```yaml 1462 | web: 1463 | links: 1464 | - db 1465 | - db:database 1466 | - redis 1467 | ``` 1468 | 1469 | 已经被链入的服务将会是主机名（即链接别名 `ALIAS`）可访问的。 1470 | 1471 | 对于服务间通讯来说，链接并不是必须的。默认情况下，任何服务都可以通过服务名访问到其他服务。参阅 [Links topic in Networking in Compose](https://docs.docker.com/compose/networking/#links)。 1472 | 1473 | 链接也表示一个依赖关系，但这已经是 `depends_on` 的任务了，所以链接也并不必要了。 1474 | 1475 | 1476 | 1477 | ### `logging` 1478 | 1479 | 为服务指定日志转发配置。 1480 | 1481 | ```yaml 1482 | logging: 1483 | driver: syslog 1484 | options: 1485 | syslog-address: "tcp://192.168.0.42:123" 1486 | ``` 1487 | 1488 | `driver` 指定了驱动名称，这和 `--log-driver` 是等效的。 1489 | 1490 | 缺省值为 `json-file`。 1491 | 1492 | ```yaml 1493 | driver: "json-file" 1494 | driver: "syslog" 1495 | driver: "none" 1496 | ``` 1497 | 1498 | > **Note** 1499 | > 1500 | > 使用 `docker-compose up` 和 `docker-compose logs` 检索日志时，只有 `json-file` 和 `journald` 驱动格式的日志才能被打印到控制台，其他日志驱动程序会将日志转发到对应的目的地，本地将不会检索到任何日志输出信息。 1501 | 1502 | 可用的转发驱动器可以参考 https://docs.docker.com/config/containers/logging/configure/。 1503 | 1504 | 使用 `option` 指定驱动器的选项，如同 `--log-opt` 那样。例如为 `syslog` 这样指定： 1505 | 1506 | ```yaml 1507 | driver: "syslog" 1508 | options: 1509 | syslog-address: "tcp://192.168.0.42:123" 1510 | ``` 1511 | 1512 | 缺省的日志转发驱动为 `json-file`。对此可以指定日志切割尺寸以及最多保持的日志历史文件个数： 1513 | 1514 | ```yaml 1515 | options: 1516 | max-size: "200k" 1517 | max-file: "10" 1518 | ``` 1519 | 1520 | 上面显示的这个例子中，日志的文件存储将被限制为 200kB，并且在超出时会被截断到旧历史日志，这样的历史文件将被限制为不超过 10 个，更旧的历史文件将被抛弃。 1521 | 1522 | 这里有一个完整的 `docker-compose.yml` 文件实例，演示了如何限制日志存储空间： 1523 | 1524 | ```yaml 1525 | version: "3.8" 1526 | services: 1527 | some-service: 1528 | image: some-service 1529 | logging: 1530 | driver: "json-file" 1531 | options: 1532 | max-size: "200k" 1533 | max-file: "10" 1534 | ``` 1535 | 1536 | > 有效可用的日志选项有赖于具体使用的日志驱动程序。 1537 | > 1538 | > 上面的控制日志文件个数及其大小的日志选项，适用于 [json-file driver](https://docs.docker.com/config/containers/logging/json-file/)。它们可能并不适用于别的日志驱动程序。要了解完整的针对每个日志驱动程序可用的日志选项，请查阅 [logging drivers](https://docs.docker.com/config/containers/logging/configure/) 文档。 1539 | 1540 | 1541 | 1542 | ### `network_mode` 1543 | 1544 | 网络模型。 1545 | 1546 | 和 `--network` 的取值相同。但额外支持 `service:[service name]` 模式。 1547 | 1548 | ```yaml 1549 | network_mode: "bridge" 1550 | network_mode: "host" 1551 | network_mode: "none" 1552 | network_mode: "service:[service name]" 1553 | network_mode: "container:[container name/id]" 1554 | ``` 1555 | 1556 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1557 | > 1558 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1559 | 1560 | > **NOTE**: `network_mode: "host"` 不能和 [links](https://docs.docker.com/compose/compose-file/#links) 混用。 1561 | 1562 | 1563 | 1564 | ### `networks` 1565 | 1566 | 要加入的网络。目标网络是在 `docker-compose.yml` 顶级的 `networks` 项中定义的。 1567 | 1568 | ```yaml 1569 | services: 1570 | some-service: 1571 | networks: 1572 | - some-network 1573 | - other-network 1574 | ``` 1575 | 1576 | 1577 | 1578 | #### ALIASES 1579 | 1580 | 指定网络中该服务的别名（也即主机名）。相同网络中别的容器可以使用服务名或者服务别名来连接到该服务的容器实例。 1581 | 1582 | 既然 `aliases` 是网络范围（网络域）内的，同一个服务在不同网络中可以有不同的别名。 1583 | 1584 | > **Note** 1585 | > 1586 | > 一个网络域别名，可以被多个容器、甚至是多个服务所共享——你可以在不同容器、不同服务之间使用重名的别名。如果你这么做了，别名会被解决为哪个确定的容器是无法保证的。 1587 | 1588 | 别名定义的格式如同这样： 1589 | 1590 | ```yaml 1591 | services: 1592 | some-service: 1593 | networks: 1594 | some-network: 1595 | aliases: 1596 | - alias1 1597 | - alias3 1598 | other-network: 1599 | aliases: 1600 | - alias2 1601 | ``` 1602 | 1603 | 一个更复杂而完整的例子：下面提供了三个服务：``web`, `worker`, 和 `db`，分别属于两个网络：`new` 和 `legacy`。通过 `new` 网络中的主机名 `db` 或 `database` 来访问，或者 `legacy` 网络的主机名 `db` 或 `mysql`，都可以访问到 `db` 服务。 1604 | 1605 | ```yaml 1606 | version: "3.8" 1607 | 1608 | services: 1609 | web: 1610 | image: "nginx:alpine" 1611 | networks: 1612 | - new 1613 | 1614 | worker: 1615 | image: "my-worker-image:latest" 1616 | networks: 1617 | - legacy 1618 | 1619 | db: 1620 | image: mysql 1621 | networks: 1622 | new: 1623 | aliases: 1624 | - database 1625 | legacy: 1626 | aliases: 1627 | - mysql 1628 | 1629 | networks: 1630 | new: 1631 | legacy: 1632 | ``` 1633 | 1634 | #### IPV4_ADDRESS, IPV6_ADDRESS 1635 | 1636 | 指定一个静态IP地址。 1637 | 1638 | 注意相应的顶级网络配置中，必须有 `ipam` 块对子网进行了配置且静态IP地址符合该子网定义。 1639 | 1640 | > If IPv6 addressing is desired, the [`enable_ipv6`](https://docs.docker.com/compose/compose-file/compose-file-v2/##enable_ipv6) option must be set, and you must use a [version 2.x Compose file](https://docs.docker.com/compose/compose-file/compose-file-v2/#ipv4_address-ipv6_address). *IPv6 options do not currently work in swarm mode*. 1641 | 1642 | 一个例子是： 1643 | 1644 | ```yaml 1645 | version: "3.8" 1646 | 1647 | services: 1648 | app: 1649 | image: nginx:alpine 1650 | networks: 1651 | app_net: 1652 | ipv4_address: 172.16.238.10 1653 | ipv6_address: 2001:3984:3989::10 1654 | 1655 | networks: 1656 | app_net: 1657 | ipam: 1658 | driver: default 1659 | config: 1660 | - subnet: "172.16.238.0/24" 1661 | - subnet: "2001:3984:3989::/64" 1662 | ``` 1663 | 1664 | 1665 | 1666 | ### `pid` 1667 | 1668 | ```yaml 1669 | pid: "host" 1670 | ``` 1671 | 1672 | 设置服务使用主机的 PID 模式。这使得容器内的服务进程和宿主机操作系统级能够共享 PID 地址空间。这是一个典型的 Linux/Unix 操作系统概念，因此这里不再展开叙述了。这样的共享的作用，可以使能安全的、借助PID地址空间的 IPC 通讯。 1673 | 1674 | 1675 | 1676 | ### `ports` 1677 | 1678 | 暴露端口到宿主机。 1679 | 1680 | > **Note**: 端口暴露功能和 `network_mode: host` 不能兼容。 1681 | 1682 | #### 短格式 1683 | 1684 | 可以同时指定宿主机和容器端口 (`HOST:CONTAINER`) 以完成映射，也可以仅指定容器端口以自动映射为~~相同的主机端口~~一个临时端口（从32768开始）。 1685 | 1686 | > **Note** 1687 | > 1688 | > 当采用 `HOST:CONTAINER` 格式来映射端口时，如果使用的容器端口小于60的话，你可能会**接受**到一个错误。这是因为 YAML 解析器将格式 `xx:yy` 视为一个 60 进制的数值。这挺荒谬的，是不是？由于这个原因，我们不得不推荐你在端口号这里总是使用引号做包围，令其成为一个 string 值，以免收到不如预期的反应。 1689 | 1690 | ```yaml 1691 | ports: 1692 | - "3000" 1693 | - "3000-3005" 1694 | - "8000:8000" 1695 | - "9090-9091:8080-8081" 1696 | - "49100:22" 1697 | - "127.0.0.1:8001:8001" 1698 | - "127.0.0.1:5000-5010:5000-5010" 1699 | - "6060:6060/udp" 1700 | ``` 1701 | 1702 | #### 长格式 1703 | 1704 | 允许进行冗长的定义： 1705 | 1706 | - `target`: 指定容器内的端口号 1707 | - `published`: 指定暴露给 docker 宿主机的端口号 1708 | - `protocol`: 协议 (`tcp` or `udp`) 1709 | - `mode`: `host` 表示每个节点的端口号都发布为宿主机端口，`ingress` 专用于 swarm 集群，所有节点的端口会被负载均衡为宿主机端口。 1710 | 1711 | ```yaml 1712 | ports: 1713 | - target: 80 1714 | published: 8080 1715 | protocol: tcp 1716 | mode: host 1717 | ``` 1718 | 1719 | > 意义明显，所以略过解说。 1720 | 1721 | > **NOTE**：长格式仅在 v3.2 及之后有效。 1722 | 1723 | 1724 | 1725 | ### `restart` 1726 | 1727 | `no` 是默认的重启策略。此时无论容器怎么退出、怎么失败也不会被自动重启。 1728 | 1729 | 指定 `always` 时任何情况下容器都会被重启。 1730 | 1731 | `on-failure` 策略可在容器失败退出时才重启。 1732 | 1733 | ```yaml 1734 | restart: "no" 1735 | restart: always 1736 | restart: on-failure 1737 | restart: unless-stopped 1738 | ``` 1739 | 1740 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。（此时可以使用 `restart_policy` 达到目的） 1741 | > 1742 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1743 | 1744 | 1745 | 1746 | ### `secrets` 1747 | 1748 | 从每个服务配置中，授权访问顶级 `secrets` 定义的表项。支持长短两个格式。 1749 | 1750 | #### 短格式 1751 | 1752 | 短格式仅指定敏感内容的名字。这使得容器能够挂载对应内容到 `/run/secrets/` 位置并访问它。 1753 | 1754 | 下面的例子使用短格式，让 `redis` 能够访问 `my_secret` 和 `my_other_secret`。`my_secret` 的具体内容被定义在 `./my_secret.txt`，`my_other_secret` 被定义为外部资源，例如通过 `docker secret create` 方式预先定义。如果找不到对应的外部资源，stack部署将会失败并抛出一个 `secret not found` 错误。 1755 | 1756 | ```yaml 1757 | version: "3.8" 1758 | services: 1759 | redis: 1760 | image: redis:latest 1761 | deploy: 1762 | replicas: 1 1763 | secrets: 1764 | - my_secret 1765 | - my_other_secret 1766 | secrets: 1767 | my_secret: 1768 | file: ./my_secret.txt 1769 | my_other_secret: 1770 | external: true 1771 | ``` 1772 | 1773 | #### 长格式 1774 | 1775 | 长格式可以更精细地定义敏感内容如何被用于 stack 内容器。 1776 | 1777 | - `source`： 敏感内容在 Docker 中所被定义的名字。 1778 | - `target`: 被挂载到容器内 `/run/secrets/` 中的文件名。如果没指定则使用 `source` 名。 1779 | - `uid` & `gid`: 容器内挂载的文件的 UID 和 GID。如未指定则为0。在 Windows 中无效。 1780 | - `mode`: 容器内挂载的文件的八进制许可权限。在 Docker 1.13.1 中默认值为 `0000`，但在更新的版本中为 `0444`。挂载的文件是不可写的。执行位可以被设置，但一般情况下没有意义。 1781 | 1782 | 下面是一个例子： 1783 | 1784 | ```yaml 1785 | version: "3.8" 1786 | services: 1787 | redis: 1788 | image: redis:latest 1789 | deploy: 1790 | replicas: 1 1791 | secrets: 1792 | - source: my_secret 1793 | target: redis_secret 1794 | uid: '103' 1795 | gid: '103' 1796 | mode: 0440 1797 | secrets: 1798 | my_secret: 1799 | file: ./my_secret.txt 1800 | my_other_secret: 1801 | external: true 1802 | ``` 1803 | 1804 | 长短格式时可以被混用的，如果你在定义多个敏感内容。 1805 | 1806 | 1807 | 1808 | ### `security_opt` 1809 | 1810 | 为每个容器覆盖掉默认的标签语义。 1811 | 1812 | ```yaml 1813 | security_opt: 1814 | - label:user:USER 1815 | - label:role:ROLE 1816 | ``` 1817 | 1818 | 通常这和 seccomp 有关，这会是与安全配置有关的一个冗长的话题，故而此处不做展开。 1819 | 1820 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1821 | > 1822 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1823 | 1824 | 1825 | 1826 | ### stop_grace_period 1827 | 1828 | 指定一个等待时长，如果容器未能拦住 `SIGTERM` 信号（或者通过 `stop_signal` 定义的别的信号）正常地关闭自己，则在此时长之后强制清除容器实例的相应进程（通过 `SIGKILL` 信号）。 1829 | 1830 | ```yaml 1831 | stop_grace_period: 1s 1832 | stop_grace_period: 1m30s 1833 | ``` 1834 | 1835 | 默认时，将会等候 10s 。 1836 | 1837 | 1838 | 1839 | ### `stop_signal` 1840 | 1841 | 设置一个替代信号以正常关闭容器实例。默认时使用 `SIGTERM` 信号. 1842 | 1843 | ```yaml 1844 | stop_signal: SIGUSR1 1845 | ``` 1846 | 1847 | 1848 | 1849 | ### `sysctls` 1850 | 1851 | 为容器设定内核参数。可以使用一个数组或字典。 1852 | 1853 | ```yaml 1854 | sysctls: 1855 | net.core.somaxconn: 1024 1856 | net.ipv4.tcp_syncookies: 0 1857 | sysctls: 1858 | - net.core.somaxconn=1024 1859 | - net.ipv4.tcp_syncookies=0 1860 | ``` 1861 | 1862 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1863 | > 1864 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1865 | 1866 | 1867 | 1868 | ### `tmpfs` 1869 | 1870 | > v2 的解说在 v3.8 的原文里已经被删除了： 1871 | 1872 | > > since v2 1873 | > 1874 | > 挂载一个临时文件系统到容器中。可以是一个单一值或一个列表。 1875 | > 1876 | > ```yaml 1877 | > tmpfs: /run 1878 | > tmpfs: 1879 | > - /run 1880 | > - /tmp 1881 | > ``` 1882 | > 1883 | > > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1884 | > > 1885 | > > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1886 | > 1887 | 1888 | 1889 | 1890 | > since v3.6 1891 | 1892 | 挂载一个临时文件系统到容器中。可以使用一个单一值或一个数组。 1893 | 1894 | ```yaml 1895 | tmpfs: /run 1896 | 1897 | tmpfs: 1898 | - /run 1899 | - /tmp 1900 | ``` 1901 | 1902 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1903 | > 1904 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1905 | 1906 | 挂载一个临时文件系统到容器中。Size参数可以指定文件系统尺寸的字节大小。默认值为无限。 1907 | 1908 | ```yaml 1909 | - type: tmpfs 1910 | target: /app 1911 | tmpfs: 1912 | size: 1000 1913 | ``` 1914 | 1915 | 1916 | 1917 | ### `ulimits` 1918 | 1919 | 覆盖容器内指定的默认的 ulimits 值。可以指定一个整数作为单一的 limit 限制，或者指定一个 mapping 以分别表示 soft/hard limit 限制。 1920 | 1921 | ```yaml 1922 | ulimits: 1923 | nproc: 65535 1924 | nofile: 1925 | soft: 20000 1926 | hard: 40000 1927 | ``` 1928 | 1929 | 1930 | 1931 | ### `userns_mode` 1932 | 1933 | ```yaml 1934 | userns_mode: "host" 1935 | ``` 1936 | 1937 | 禁用用户名字空间。如果 Docker daemon 被配置运行在一个 user namespace 之中的话。 1938 | 1939 | > **NOTE**: 这些选项在部署一个栈到 swarm mode 时被忽略。 1940 | > 1941 | > 也参阅 [deploying a stack in swarm mode](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 。 1942 | 1943 | 1944 | 1945 | ### `volumes` 1946 | 1947 | 挂载宿主机路径或者命名卷。 1948 | 1949 | 可以挂载一个主机路径到一个服务中，此时无需在顶级 `volumes` 中对其进行定义。 1950 | 1951 | 如果想要重用一个卷到多个服务，那么应该在顶级 `volumes` 中定义它并命名它。 1952 | 1953 | 可以在 [services, swarms, and stack files](https://docs.docker.com/compose/compose-file/#volumes-for-services-swarms-and-stack-files) 中使用命名卷。 1954 | 1955 | > **NOTE**： 在顶级 `volumes` 中定义一个命名卷，并在一个服务的 `volumes` 列表中引用它。 1956 | > 1957 | > 早期的 `volumes_from` 不再使用了。 1958 | > 1959 | > 可以参阅 [Use volumes](https://docs.docker.com/engine/admin/volumes/volumes/) and [Volume Plugins](https://docs.docker.com/engine/extend/plugins_volume/)。 1960 | 1961 | 下面的例子示意了一个命名卷 `my_data` ，且被用于 `web` 服务。在 `web` 中也使用一个主机文件夹 `./static` 到容器内的挂载；在 `db` 中挂载了一个主机文件到容器内的对应文件，并使用了另一个命名卷 `dbdata`。 1962 | 1963 | ```yaml 1964 | version: "3.8" 1965 | services: 1966 | web: 1967 | image: nginx:alpine 1968 | volumes: 1969 | - type: volume 1970 | source: mydata 1971 | target: /data 1972 | volume: 1973 | nocopy: true 1974 | - type: bind 1975 | source: ./static 1976 | target: /opt/app/static 1977 | 1978 | db: 1979 | image: postgres:latest 1980 | volumes: 1981 | - "/var/run/postgres/postgres.sock:/var/run/postgres/postgres.sock" 1982 | - "dbdata:/var/lib/postgresql/data" 1983 | 1984 | volumes: 1985 | mydata: 1986 | dbdata: 1987 | ``` 1988 | 1989 | > **Note** 1990 | > 1991 | > 关于卷的更多信息，请参阅 [use volumes](https://docs.docker.com/storage/volumes/) 和 [volume plugins](https://docs.docker.com/engine/extend/plugins_volume/) 章节。 1992 | 1993 | #### 短格式 1994 | 1995 | 可以使用 `HOST:CONTAINER` 格式，或者附带一个访问模式 `HOST:CONTAINER:ro`。 1996 | 1997 | 短格式的语法为 `[SOURCE:]TARGET[:MODE]`。`SOURCE` 可以是一个主机路径，也可以是一个卷名。`TARGET` 是一个容器内路径 T，主机路径将被挂载到该路径 T。`MODE` 可以是 `ro` 或者 `rw`，分别代表着 只读 和 可读写。 1998 | 1999 | 可以挂载一个主机中的相对路径，此路径是相对于 docker compose 文件而被展开的。相对路径应该总是以 `.` 或者 `..` 开始。 2000 | 2001 | ```yaml 2002 | volumes: 2003 | # Just specify a path and let the Engine create a volume 2004 | - /var/lib/mysql 2005 | 2006 | # Specify an absolute path mapping 2007 | - /opt/data:/var/lib/mysql 2008 | 2009 | # Path on the host, relative to the Compose file 2010 | - ./cache:/tmp/cache 2011 | 2012 | # User-relative path 2013 | - ~/configs:/etc/configs/:ro 2014 | 2015 | # Named volume 2016 | - datavolume:/var/lib/mysql 2017 | ``` 2018 | 2019 | #### 长格式 2020 | 2021 | 长格式可以进行更精细的控制。 2022 | 2023 | - `type`: 挂载类型 为 `volume`, `bind`, `tmpfs` 和 `npipe` 2024 | - `source`：挂载的源位置。可以是一个主机路径，一个定义于顶级 volumes 中的卷名称，等等。如果是挂载 `tmpfs` 则此参数无意义。 2025 | - `target`: 容器内的挂载点路径。 2026 | - `read_only`: 布尔值以设定卷的可写性。 2027 | - `bind`: 配置附加的 bind 选项。 2028 | - `propagation`: 用于 bind 的传播模式。 2029 | - `volume`: 配置附加的 卷 选项 2030 | - `nocopy`：布尔量以禁用数据复制（默认时当卷被首次创建时，容器内的内容将被复制到卷内） 2031 | - `tmpfs`: 配置附加的 tmpfs 选项 2032 | - `size`: tmpfs的容量，按字节数。 2033 | - `consistency`：挂载的一致性要求：`consistent` 主机和容器有同样的视图，`cached` 读操作被缓冲，主机视图为主体，`delegated` 读写操作被缓冲，容器视图为主体。 2034 | 2035 | ```yaml 2036 | version: "3.8" 2037 | services: 2038 | web: 2039 | image: nginx:alpine 2040 | ports: 2041 | - "80:80" 2042 | volumes: 2043 | - type: volume 2044 | source: mydata 2045 | target: /data 2046 | volume: 2047 | nocopy: true 2048 | - type: bind 2049 | source: ./static 2050 | target: /opt/app/static 2051 | 2052 | networks: 2053 | webnet: 2054 | 2055 | volumes: 2056 | mydata: 2057 | ``` 2058 | 2059 | > ~~长格式在 v3.2 之后可用~~ 2060 | > 2061 | > **Note** 2062 | > 2063 | > 在做绑定主机目录并挂载到容器操作时，长格式语法需要你提前将主机文件夹准备就绪。使用短格式的话，对应文件夹将被就地创建，如果它尚未存在的话。详情请参阅 [bind mounts documentation](https://docs.docker.com/storage/bind-mounts/#differences-between--v-and---mount-behavior)。 2064 | 2065 | #### VOLUMES FOR SERVICES, SWARMS, AND STACK FILES 2066 | 2067 | 当工作在 services, swarms, 或 `docker-stack.yml` 场景下，要注意一个服务在 swarm 中可能被部署到任意节点，而每当服务被更新之后再次启动时，可能已经不再在原来的节点上了。 2068 | 2069 | 当指定名称的卷并不存在时，Docker会自动创建一个匿名卷用于引用的服务。匿名卷是不可持久化的，因此当关联的容器实例退出并被移除时，匿名卷也会被销毁。 2070 | 2071 | 如果想要持久化你的数据，采用命名卷以及选择恰当的卷驱动程序，这个驱动应该是跨主机的，这样数据才能在不同的主机之间漫游。否则的话，你应该设置服务的约束条件以便该服务只会被部署到特定的节点上，这些节点上有相应的卷服务在正确工作。 2072 | 2073 | 作为一个例子，[votingapp sample in Docker Labs](https://github.com/docker/labs/blob/master/beginner/chapters/votingapp.md) 的 `docker-stack.yml` 文件定义了 `db` 服务，运行着 postgresql。它使用了一个命名卷 `db-data` 来持久化数据库数据，这个卷被通过swarm约束在只能运行在 `manager` 这个节点上，因此一切疑难都不存在了。下面是源码： 2074 | 2075 | ```yaml 2076 | version: "3.8" 2077 | services: 2078 | db: 2079 | image: postgres:9.4 2080 | volumes: 2081 | - db-data:/var/lib/postgresql/data 2082 | networks: 2083 | - backend 2084 | deploy: 2085 | placement: 2086 | constraints: [node.role == manager] 2087 | ``` 2088 | 2089 | #### CACHING OPTIONS FOR VOLUME MOUNTS (DOCKER DESKTOP FOR MAC) 2090 | 2091 | 在 Docker 17.04 CE Edge 以及其后版本中（乃至于 17.06CE Edge 和 Stable 版本），你可以配置容器和主机之间卷如何被同步的一致性约束参数。这些标志包括： 2092 | 2093 | - `consistent` 完全一致。主机和容器有同样的视图，这是默认的策略。 2094 | 2095 | - `cached` 宿主机为准。对卷的读操作被缓冲，主机视图为主体， 2096 | 2097 | - `delegated` 容器为准。对卷的读写操作被缓冲，容器视图为主体。 2098 | 2099 | 这是专为 Docker Desktop for Mac 而适配的。由于已经知道的 `osxfx` 的关于文件共享特性原因，合理的设置一致性标志能够改善容器内外访问挂载卷时的性能问题。 2100 | 2101 | 下面是一个`cached`卷的例子： 2102 | 2103 | ```yaml 2104 | version: "3.7" 2105 | services: 2106 | php: 2107 | image: php:7.1-fpm 2108 | ports: 2109 | - "9000" 2110 | volumes: 2111 | - .:/var/www/project:cached 2112 | ``` 2113 | 2114 | 对于读写操作均被缓冲的情况，即使容器中发生了什么修改（对于向PHP Website这样的典型架构来说，./config.php 经常是可能被写入的），也不会立即体现到宿主机中来，容器中的写入将会被堆积。 2115 | 2116 | 卷在容器内外的一致性问题，应该参考 [Performance tuning for volume mounts (shared filesystems)](https://docs.docker.com/docker-for-mac/osxfs-caching/)。 2117 | 2118 | > 在这里我未能原样翻译，因为那样会带来较长的篇幅，我尚未能就此问题组织好语言。 2119 | 2120 | 2121 | 2122 | ### `domainname`, `hostname`, `ipc`, `mac_address`, `privileged`, `read_only`, `shm_size`, `stdin_open`, `tty`, `user`, `working_dir` 2123 | 2124 | 这些配置具有单一值。和 `docker run` 的相应命令行参数相对应。`mac_address` 已经是被遗弃的设定。 2125 | 2126 | ```yaml 2127 | user: postgresql 2128 | working_dir: /code 2129 | 2130 | domainname: foo.com 2131 | hostname: foo 2132 | ipc: host 2133 | mac_address: 02:42:ac:11:65:43 2134 | 2135 | privileged: true 2136 | 2137 | 2138 | read_only: true 2139 | shm_size: 64M 2140 | stdin_open: true 2141 | tty: true 2142 | ``` 2143 | 2144 | 2145 | 2146 | 2147 | 2148 | ## 指定时间段 duration 2149 | 2150 | 有的配置选项，例如 `interval` 或者 `timeout`（都是 `check `的子选项），接受一个字符串风格的时间周期或时间段的参数值。它们应该具有这样的格式： 2151 | 2152 | ```yaml 2153 | 2.5s 2154 | 10s 2155 | 1m30s 2156 | 2h32m 2157 | 5h34m56s 2158 | ``` 2159 | 2160 | 可以为数值附加的后缀单位有 `us`, `ms`, `s`, `m`, 以及 `h`。 2161 | 2162 | 含义自明。 2163 | 2164 | 2165 | 2166 | ## 指定字节值 2167 | 2168 | 有的配置选项，例如 `build` 的子选项 `shm_size`，接受一个字符串分隔的容量尺寸参数值。它们应该具有这样的格式： 2169 | 2170 | ```yaml 2171 | 2b 2172 | 1024kb 2173 | 2048k 2174 | 300m 2175 | 1gb 2176 | ``` 2177 | 2178 | 有效的后缀单位包括 `b`, `k`, `m` 和 `g`。此外，`kb`, `mb` 和 `gb` 也是合法的。纯粹的十进制数值并不合法。 2179 | 2180 | 2181 | 2182 | 2183 | 2184 | 2185 | 2186 | ## 卷编排格式手册 - `volumes` 2187 | 2188 | 顶级的 volumes 章节可以声明和创建命名卷（无需使用 `volume_from`），这些卷能够被用于在 service 章节下的 [volumes](#volumes) 小节中被引用。所以我们可以重用它们，甚至能够跨越多个 services。docker命令的 [docker volume](https://docs.docker.com/engine/reference/commandline/volume_create/) 子命令有更多的参考信息。 2189 | 2190 | 关于卷的使用，也可以参考 [Use volumes](https://docs.docker.com/engine/admin/volumes/volumes/) 和 [Volume Plugins](https://docs.docker.com/engine/extend/plugins_volume/)。 2191 | 2192 | 这里有一个示例，包含了两个服务，数据库的数据存储文件夹在两个服务之间被共享，因而数据库可以使用这个存储文件夹，而备份服务同样可以操作它以完成备份任务： 2193 | 2194 | ```yaml 2195 | version: "3.8" 2196 | 2197 | services: 2198 | db: 2199 | image: db 2200 | volumes: 2201 | - data-volume:/var/lib/db 2202 | backup: 2203 | image: backup-service 2204 | volumes: 2205 | - data-volume:/var/lib/backup/data 2206 | 2207 | volumes: 2208 | data-volume: 2209 | ``` 2210 | 2211 | 顶级 `volumes` 章节下的条目可以是空，无需指定细节，这样的话，默认的卷驱动程序将被应用（通常都会是 `local` 卷驱动）。 2212 | 2213 | 但你也可以通过下面的参数对其进行定制： 2214 | 2215 | ### `driver` 2216 | 2217 | 指定哪一个卷驱动程序会被采用。一般来说，默认值会是 `local`。如果卷驱动程序无效、或不能工作，在 `docker-compose up` 时 Docker Engine将会返回一个错误。 2218 | 2219 | ```yaml 2220 | driver: foobar 2221 | ``` 2222 | 2223 | ### `driver_opts` 2224 | 2225 | 可选地指定一组键值对参数集，这些参数将被传递给卷驱动程序。所以这些参数集是和卷驱动程序相关的，请参考卷驱动程序的有关文档。 2226 | 2227 | ```yaml 2228 | volumes: 2229 | example: 2230 | driver_opts: 2231 | type: "nfs" 2232 | o: "addr=10.40.0.199,nolock,soft,rw" 2233 | device: ":/docker/example" 2234 | ``` 2235 | 2236 | ### `external` 2237 | 2238 | 如果设置为 `true`，表示相应的卷是在 compose 编排文件之外被创建就绪的。此时 `docker-compse up` 将不会尝试创建这个卷，而如果该卷尚未存在则会返回一个错误。 2239 | 2240 | 对于 v3.3 以及更低的 compose 编排格式版本而言，`external` 不可以被用于与其他卷配置参数组合使用，例如 `driver`, `driver_opts`, `labels` 等等。但对于 v3.4 以及更高版本来说不再有此限制。 2241 | 2242 | 下面的示例中，Compose 查找一个名为 `data` 的外部卷并挂载它到 `db` 服务中，而不是尝试创建一个名为 `[projectname]_data` 的新卷。 2243 | 2244 | ```yaml 2245 | version: "3.8" 2246 | 2247 | services: 2248 | db: 2249 | image: postgres 2250 | volumes: 2251 | - data:/var/lib/postgresql/data 2252 | 2253 | volumes: 2254 | data: 2255 | external: true 2256 | ``` 2257 | 2258 | > `external.name` 在 v3.4+ 已被废弃，这之后直接使用 `name`。 2259 | 2260 | 你也可以单独指定卷名字（这时，`data` 被认为是该卷在当前编排文件中被引用时的 卷别名）： 2261 | 2262 | ``` 2263 | volumes: 2264 | data: 2265 | external: 2266 | name: actual-name-of-volume 2267 | ``` 2268 | 2269 | > **External volumes are always created with docker stack deploy** 2270 | > 2271 | > 在使用 [docker stack deploy](https://docs.docker.com/compose/compose-file/#deploy) 部署到 swarm 中时，外部卷如果不存在，则总是自动被创建。进一步的有关信息请参阅 [moby/moby#29976](https://github.com/moby/moby/issues/29976)、 2272 | 2273 | ### `labels` 2274 | 2275 | 使用 [Docker labels](https://docs.docker.com/engine/userguide/labels-custom-metadata/) 为容器添加元数据。可以是数组格式或者字典格式。 2276 | 2277 | 我们建议你使用反向DNS标注方式，为你的元数据表键添加反向域名前缀，从而避免潜在的和其它应用的相同名字的表键发生冲突： 2278 | 2279 | ```yaml 2280 | labels: 2281 | com.example.description: "Database volume" 2282 | com.example.department: "IT/Ops" 2283 | com.example.label-with-empty-value: "" 2284 | labels: 2285 | - "com.example.description=Database volume" 2286 | - "com.example.department=IT/Ops" 2287 | - "com.example.label-with-empty-value" 2288 | ``` 2289 | 2290 | 2291 | 2292 | ### `name` 2293 | 2294 | > since v3.4+ 2295 | 2296 | 为卷指定一个自定义的名字。名字的值可被用于解决具有特殊字符名字的卷。注意该值被原样使用，引号不会被忽略，也不会被添加上栈名字前缀。 2297 | 2298 | ```yaml 2299 | version: "3.8" 2300 | volumes: 2301 | data: 2302 | name: my-app-data 2303 | ``` 2304 | 2305 | `name` 可以被与 `external` 相组合： 2306 | 2307 | ``` 2308 | version: "3.8" 2309 | volumes: 2310 | data: 2311 | external: true 2312 | name: my-app-data 2313 | ``` 2314 | 2315 | 2316 | 2317 | ## 网络编排格式手册 - `networks` 2318 | 2319 | 顶级章节 `networks` 使得你可以配置想要创建和使用的网络（Compose内网）。 2320 | 2321 | - 完整的在 Compose 中使用 Docker 网络环境特性的有关说明，以及所有的网络驱动程序选项，请参考 [Networking guide](https://docs.docker.com/compose/networking/)。 2322 | - 对于 [Docker Labs](https://github.com/docker/labs/blob/master/README.md) 的和网络相关的辅导用例，请仔细阅读 [Designing Scalable, Portable Docker Container Networks](https://github.com/docker/labs/blob/master/networking/README.md)。 2323 | 2324 | ### `driver` 2325 | 2326 | 指定该网络的驱动程序。 2327 | 2328 | 缺省的驱动程序由 Docker Engine 的启动参数所指定。通常情况下，启动参数内置为在单节点宿主机上使用 `bridge` 驱动，而在 `swarm mode` 中使用 `overlay` 驱动。 2329 | 2330 | 如果驱动程序不可用，Docker Engine 将会返回一个错误。 2331 | 2332 | ```yaml 2333 | driver: overlay 2334 | ``` 2335 | 2336 | 2337 | 2338 | #### `bridge` 2339 | 2340 | 缺省时 Docker 在每个宿主机节点上使用 `bridge` 驱动。有关桥接网络是如何工作的，可以参考 [Docker Labs](https://github.com/docker/labs/blob/master/README.md) 的和网络相关的辅导用例：[Bridge networking](https://github.com/docker/labs/blob/master/networking/A2-bridge-networking.md)。 2341 | 2342 | 2343 | 2344 | #### `overlay` 2345 | 2346 | `overlay` 驱动在多个 `swarm mode` 节点之间建立一个命名子网，这是一个跨主机的虚拟网络。 2347 | 2348 | - 在 `swarm mode` 中如何建立 `overlay` 网络并籍此令服务跨主机正确工作，请参考 [Docker Labs](https://github.com/docker/labs/blob/master/README.md) 的和网络相关的辅导用例： [Overlay networking and service discovery](https://github.com/docker/labs/blob/master/networking/A3-overlay-networking.md)。 2349 | - 如果想要深究 `overlay` 是如何跨主机完成虚拟网络构建和报文如何流转的，可以参考 [Overlay Driver Network Architecture](https://github.com/docker/labs/blob/master/networking/concepts/06-overlay-networks.md)。 2350 | 2351 | 2352 | 2353 | #### `host` 或 `none` 2354 | 2355 | 使用主机网络栈，或者不使用网络。 2356 | 2357 | 和命令行参数 `--net=host` 以及 `--net=none` 是等价的。 2358 | 2359 | 这两种驱动及网络模型只能被用于 `docker stack` 之中。如果你正在使用 `docker compose` 相关指令，请使用 `network_mode` 来指定它们。 2360 | 2361 | If you want to use a particular network on a common build, use [network] as mentioned in the second yaml file example. 2362 | 2363 | 使用内建的网络模型，例如 `host` 和 `none`，语法上有一点点需要注意的地方：如果用 `host` 或 `none` 这样的名字定义一个外部网络（注意你并不需要真的创建他们，这两者都属于Docker内置的网络模型），那么在 Compose 编排文件中引用它们时你需要使用 `hostnet` 或 `nonet`，如同这样： 2364 | 2365 | ```yaml 2366 | version: "3.8" 2367 | services: 2368 | web: 2369 | networks: 2370 | hostnet: {} 2371 | 2372 | networks: 2373 | hostnet: 2374 | external: true 2375 | name: host 2376 | 2377 | --- 2378 | services: 2379 | web: 2380 | ... 2381 | build: 2382 | ... 2383 | network: host 2384 | context: . 2385 | ... 2386 | services: 2387 | web: 2388 | ... 2389 | networks: 2390 | nonet: {} 2391 | 2392 | networks: 2393 | nonet: 2394 | external: true 2395 | name: none 2396 | ``` 2397 | 2398 | 2399 | 2400 | ### `driver_opts` 2401 | 2402 | 指定一组键值对表示的选项集，以传递给网络驱动程序。它们是和驱动程序密切相关的，所以具体的可用参数应该参考对应的驱动程序文档。 2403 | 2404 | ```yaml 2405 | driver_opts: 2406 | foo: "bar" 2407 | baz: 1 2408 | ``` 2409 | 2410 | 2411 | 2412 | ### `attachable` 2413 | 2414 | > since v3.2+ 2415 | 2416 | 只能用于 `driver: overlay` 的场景。 2417 | 2418 | 如果被设置为 `true`，独立运行的容器也能被附着在该网络之中。如果独立运行的容器实例被附着到了一个 overlay 网络中，那么容器中的服务与单独的容器实例之间能够互相通讯。请注意你甚至可以附着其他 Docker daemon 中的容器实例到本 overlay 网络中。 2419 | 2420 | ```yaml 2421 | networks: 2422 | mynet1: 2423 | driver: overlay 2424 | attachable: true 2425 | ``` 2426 | 2427 | 2428 | 2429 | ### `enable_ipv6` 2430 | 2431 | 在该网络/子网中启用 IPv6。 2432 | 2433 | >在 v3+ 中不被支持。 2434 | > 2435 | >`enable_ipv6` 需要你使用 v2 的编排格式，而且也不能被用于 swarm mode 中。 2436 | 2437 | 2438 | 2439 | ### `ipam` 2440 | 2441 | 自定义 IPAM 配置。每一项子配置都是可选参数。 2442 | 2443 | - `driver`: 自定义 IPAM 驱动程序，而不使用默认值 2444 | - `config`: 一个列表，包含一到多个配置块。每个配置块具有下列子参数： 2445 | - `subnet`: CIDR格式的子网定义，以划定一个网段。 2446 | 2447 | 一个完整的例子： 2448 | 2449 | ```yaml 2450 | ipam: 2451 | driver: default 2452 | config: 2453 | - subnet: 172.28.0.0/16 2454 | ``` 2455 | 2456 | > **NOTE**：附加IPAM如 `gateway` 只在 v2 中可用。 2457 | 2458 | 2459 | 2460 | ### `internal` 2461 | 2462 | 默认时，Docker也会连接到一个桥接网络以提供外部可连接性。如果你想建立一个外部的隔离的 overlay 网络，请设置本选项为 `true`。 2463 | 2464 | 2465 | 2466 | ### `labels` 2467 | 2468 | 使用 [Docker labels](https://docs.docker.com/engine/userguide/labels-custom-metadata/) 为容器添加元数据。可以是数组格式或者字典格式。 2469 | 2470 | 我们建议你使用反向DNS标注方式，为你的元数据表键添加反向域名前缀，从而避免潜在的和其它应用的相同名字的表键发生冲突： 2471 | 2472 | ```yaml 2473 | labels: 2474 | com.example.description: "Financial transaction network" 2475 | com.example.department: "Finance" 2476 | com.example.label-with-empty-value: "" 2477 | labels: 2478 | - "com.example.description=Financial transaction network" 2479 | - "com.example.department=Finance" 2480 | - "com.example.label-with-empty-value" 2481 | ``` 2482 | 2483 | 2484 | 2485 | ### `external` 2486 | 2487 | 如果设置为 `true`，那么本网络是在 Compose 编排文件之外被创建和管理的。此时 `dockercompose up` 不会试图创建它，如果网络并不存在则返回一个错误。 2488 | 2489 | 对于 v3.3 以及更低版本的格式，`external` 不可与 `driver`, `driver_opts`, `ipam`, `internal` 等连用。此限制在 v3.4+ 之后被取消。 2490 | 2491 | 下面的例子里，`proxy` 是一个外部世界中的网关，Compose将会寻找通过 `docker network create outside` 所建立的 `outside` 外部网络，而不是试图去自动建立一个名为 `[projectname]_outside` 的新网络： 2492 | 2493 | ```yaml 2494 | version: "3.8" 2495 | 2496 | services: 2497 | proxy: 2498 | build: ./proxy 2499 | networks: 2500 | - outside 2501 | - default 2502 | app: 2503 | build: ./app 2504 | networks: 2505 | - default 2506 | 2507 | networks: 2508 | outside: 2509 | external: true 2510 | ``` 2511 | 2512 | > `external.name` 在 v3.5 及之后已经被废弃，请改用 `name`。 2513 | 2514 | 你也可以单独指定一个网络名用于在Compose编排文件内被引用。 2515 | 2516 | 2517 | 2518 | ### `name` 2519 | 2520 | > since v3.5 2521 | 2522 | 为网络设置一个自定义名字。名字的值可被用于解决具有特殊字符名字的卷。注意该值被原样使用，引号不会被忽略，也不会被添加上栈名字前缀。 2523 | 2524 | ```yaml 2525 | version: "3.8" 2526 | networks: 2527 | network1: 2528 | name: my-app-net 2529 | ``` 2530 | 2531 | `name` 可以与 `external` 一起连用： 2532 | 2533 | ```yaml 2534 | version: "3.8" 2535 | networks: 2536 | network1: 2537 | external: true 2538 | name: my-app-net 2539 | ``` 2540 | 2541 | 2542 | 2543 | 2544 | 2545 | 2546 | 2547 | ## 配置项编排格式手册 - `configs` 2548 | 2549 | 顶级的 `configs` 章节声明，定义了一个配置项或者其参考，该配置项可以被授权给栈内服务使用。配置项的来源可以是 `file` 或 `external`。 2550 | 2551 | - `file`: 配置项的内容在一个宿主机文件中。 2552 | - `external`: 如果设置为 `true`，表示该配置项已经创建就绪了。Docker将不会试图建立它，而是在起不存在时生成一个 `config not found` 错误。 2553 | - `name`: 该配置项在 Docker 中的名字。名字的值可被用于解决具有特殊字符名字的卷。注意该值被原样使用，引号不会被忽略，也不会被添加上栈名字前缀。 2554 | - `driver` and `driver_opts`: The name of a custom secret driver, and driver-specific options passed as key/value pairs. Introduced in version 3.8 file format, and only supported when using `docker stack`. 2555 | - `template_driver`: The name of the templating driver to use, which controls whether and how to evaluate the secret payload as a template. If no driver is set, no templating is used. The only driver currently supported is `golang`, which uses a `golang`. Introduced in version 3.8 file format, and only supported when using `docker stack`. Refer to [use a templated config](https://docs.docker.com/engine/swarm/configs/#example-use-a-templated-config) for a examples of templated configs. 2556 | 2557 | 下面的例子中，当作为栈的一部分被部署时，`my_first_config` 会被自动创建并命名为 `_my_first_config`，至于 `my_second_config` 是已经存在的。 2558 | 2559 | ```yaml 2560 | configs: 2561 | my_first_config: 2562 | file: ./config_data 2563 | my_second_config: 2564 | external: true 2565 | ``` 2566 | 2567 | 另一种变化是外部配置项带有 `name` 定义的情况，此时该配置项在 Compose 中可以被以 `redis_config` 为名进行参考和使用： 2568 | 2569 | ```yaml 2570 | configs: 2571 | my_first_config: 2572 | file: ./config_data 2573 | my_second_config: 2574 | external: 2575 | name: redis_config 2576 | ``` 2577 | 2578 | 你仍需在栈内为每个服务声明 `configs` 章节以获得访问配置项的权利，参考 [grant access to the config](#configs)。 2579 | 2580 | 2581 | 2582 | ## 敏感信息项编排格式手册 - `secrets` 2583 | 2584 | 顶级的 `secrets` 章节声明，定义了一个敏感信息项或者其参考，该敏感信息项可以被授权给栈内服务使用。敏感信息项的来源可以是 `file` 或 `external`。 2585 | 2586 | - `file`: 敏感信息项的内容在一个宿主机文件中。 2587 | - `external`: 如果设置为 `true`，表示该敏感信息项已经创建就绪了。Docker将不会试图建立它，而是在起不存在时生成一个 `secret not found` 错误。 2588 | - `name`: 该敏感信息项在 Docker 中的名字。名字的值可被用于解决具有特殊字符名字的卷。注意该值被原样使用，引号不会被忽略，也不会被添加上栈名字前缀。 2589 | - `template_driver`: The name of the templating driver to use, which controls whether and how to evaluate the secret payload as a template. If no driver is set, no templating is used. The only driver currently supported is `golang`, which uses a `golang`. Introduced in version 3.8 file format, and only supported when using `docker stack`. 2590 | 2591 | 下面的例子中，当作为栈的一部分被部署时，`my_first_secret` 会被自动创建并命名为 `_my_first_secret`，至于 `my_second_secret` 是已经存在的。 2592 | 2593 | ```yaml 2594 | secrets: 2595 | my_first_secret: 2596 | file: ./secret_data 2597 | my_second_secret: 2598 | external: true 2599 | ``` 2600 | 2601 | 另一种变化是外部配置项带有 `name` 定义的情况，此时该配置项在 Compose 中可以被以 `redis_secret` 为名进行参考和使用。 2602 | 2603 | #### Compose File v3.5 及更高版本 2604 | 2605 | ```yaml 2606 | secrets: 2607 | my_first_secret: 2608 | file: ./secret_data 2609 | my_second_secret: 2610 | external: true 2611 | name: redis_secret 2612 | ``` 2613 | 2614 | ### Compose File v3.4 和更低版本 2615 | 2616 | ``` 2617 | my_second_secret: 2618 | external: 2619 | name: redis_secret 2620 | ``` 2621 | 2622 | 你仍需在栈内为每个服务声明 `secret` 章节以获得访问敏感信息项的权利，参考 [grant access to the secret](#secrets)。 2623 | 2624 | 2625 | 2626 | 2627 | 2628 | 2629 | 2630 | 2631 | 2632 | ## 变量替换 2633 | 2634 | Compose编排文件中可以使用环境变量。当 `docker-compose` 运行时，Compose 从 Shell 环境变量中抽取变量值。例如，假设操作系统的环境变量中包含 `POSTGRES_VERSION=9.3` 的定义，那么以下定义 2635 | 2636 | ```yaml 2637 | db: 2638 | image: "postgres:${POSTGRES_VERSION}" 2639 | ``` 2640 | 2641 | 等价于 2642 | 2643 | ```yaml 2644 | db: 2645 | image: "postgres:9.3" 2646 | ``` 2647 | 2648 | 如果环境变量并不存在或者为空串，那么它就被当做是空字符串。 2649 | 2650 | 你可以通过 `.env` 文件来为环境变量设定缺省值。Compose 将会自动查找当前文件夹中的 `.env` 文件以获得环境变量的值。 2651 | 2652 | > **IMPORTANT**: 注意 `.env` 文件只在 `docker-compose up` 场景中有效，而在 `docker stack deploy` 时它并不会被使用。 2653 | 2654 | 两种语法 `$VARIABLE` 和 `${VARIABLE}` 都是可用的。此外在 v2.1 格式中，类似于 Shell 语法的如下形式也可以被使用： 2655 | 2656 | - `${VARIABLE:-default}` 将会返回 `default`，如果环境变量 `VARIABLE` 为空字符串或未被设置的话。 2657 | - `${VARIABLE-default}` 将会返回 `default`，如果环境变量 `VARIABLE` 未被设置的话。 2658 | 2659 | 类似地，下面的语法有助于指定一个明确的值： 2660 | 2661 | - `${VARIABLE:?err}` 将会产生错误信息 `err`，如果环境变量 `VARIABLE` 为空或未被设置的话。 2662 | - `${VARIABLE?err}` 将会产生错误信息 `err`，如果环境变量 `VARIABLE` 未被设置的话。 2663 | 2664 | 其他的 Shell 语法特性并未被支持，例如 `${VARIABLE/foo/bar}`。 2665 | 2666 | 如果需要一个美元符号的话，请使用 `$$`。此时 `$$` 不再参与环境变量替换的解释。如下例： 2667 | 2668 | ```yaml 2669 | web: 2670 | build: . 2671 | command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE" 2672 | ``` 2673 | 2674 | 如果你忘记了这个规则而使用了一个 `$` 单个字符的话，Compose 会警告你： 2675 | 2676 | `The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.` 2677 | 2678 | 2679 | 2680 | 2681 | 2682 | 2683 | 2684 | ## 扩展字段 2685 | 2686 | > since v3.4 2687 | 2688 | 通过扩展字段，能够重用编排配置片段。它们可以是自由的格式，前提是你将它们定义在 yaml 文档的顶级，并且其章节名以 `x-` 开头： 2689 | 2690 | ```yaml 2691 | version: '3.4' 2692 | x-custom: 2693 | items: 2694 | - a 2695 | - b 2696 | options: 2697 | max-size: '12m' 2698 | name: "custom" 2699 | ``` 2700 | 2701 | > **NOTE** 2702 | > 2703 | > 从 v3.7 开始（对于 3.x 系列），或者从 v2.4 开始（对于 2.x 系列），扩展字段也可以被放在 服务，卷，网络，配置项以及敏感信息项顶级章节之下的第一级。 2704 | > 2705 | > 如同这样： 2706 | > 2707 | > ```yaml 2708 | > version: '3.7' 2709 | > services: 2710 | > redis: 2711 | > # ... 2712 | > x-custom: 2713 | > items: 2714 | > - a 2715 | > - b 2716 | > options: 2717 | > max-size: '12m' 2718 | > name: "custom" 2719 | > ``` 2720 | 2721 | 所谓的自由格式，是指这些定义并不被 Compose 所解释。然而当你在某个地方插入它们的引用时，它们会被展开到插入点，然后再结合上下文被 Compose 解释具体的语义。这使用了 [YAML anchors](http://www.yaml.org/spec/1.2/spec.html#id2765878) 语法。 2722 | 2723 | 例如，如果你的多个服务都会使用相同的日志记录选项： 2724 | 2725 | ```yaml 2726 | logging: 2727 | options: 2728 | max-size: '12m' 2729 | max-file: '5' 2730 | driver: json-file 2731 | ``` 2732 | 2733 | 你可以这样定义： 2734 | 2735 | ```yaml 2736 | x-logging: 2737 | &default-logging 2738 | options: 2739 | max-size: '12m' 2740 | max-file: '5' 2741 | driver: json-file 2742 | 2743 | services: 2744 | web: 2745 | image: myapp/web:latest 2746 | logging: *default-logging 2747 | db: 2748 | image: mysql:latest 2749 | logging: *default-logging 2750 | ``` 2751 | 2752 | 通过 [YAML merge type](http://yaml.org/type/merge.html) 语法，你也可以在插入扩展字段定义是覆盖某些子选项。例如： 2753 | 2754 | ```yaml 2755 | version: '3.4' 2756 | x-volumes: 2757 | &default-volume 2758 | driver: foobar-storage 2759 | 2760 | services: 2761 | web: 2762 | image: myapp/web:latest 2763 | volumes: ["vol1", "vol2", "vol3"] 2764 | volumes: 2765 | vol1: *default-volume 2766 | vol2: 2767 | << : *default-volume 2768 | name: volume02 2769 | vol3: 2770 | << : *default-volume 2771 | driver: default 2772 | name: volume-local 2773 | ``` 2774 | 2775 | 2776 | 2777 | 2778 | 2779 | ## Compose 文档参考 2780 | 2781 | - [User guide](https://docs.docker.com/compose/) 2782 | - [Installing Compose](https://docs.docker.com/compose/install/) 2783 | - [Compose file versions and upgrading](https://docs.docker.com/compose/compose-file/compose-versioning/) 2784 | - [Get started with Docker](https://docs.docker.com/get-started/) 2785 | - [Samples](https://docs.docker.com/samples/) 2786 | - [Command line reference](https://docs.docker.com/compose/reference/) 2787 | 2788 | 2789 | 2790 | ## 结束 2791 | 2792 | - 原文：https://docs.docker.com/compose/compose-file/ 。 2793 | - 译文：[https://github.com/hedzr/docker-compose-file-format](https://github.com/hedzr/docker-compose-file-format)。 2794 | 2795 | 2796 | 2797 | ## 🔚 2798 | -------------------------------------------------------------------------------- /README_en.md: -------------------------------------------------------------------------------- 1 | # Interesting translation about chinese tech posts 2 | 3 | 4 | 5 | > 我很高兴搜索时意外地发现了英文翻译版。要知道，我的英文是很糟糕的。 6 | > 7 | > 8 | > 9 | > 下面副本一下，不过这一次我不标注来源了，如果有疑问的话，issue我取消也没问题。 10 | > 11 | > 12 | > 13 | > 其实，我就是觉得吧，这本来就是译本，反向翻译回去是不是有点多余？ 14 | 15 | 16 | 17 | 18 | 19 | ## origin 20 | 21 | About the installation of [docker-compose](https://developpaper.com/tag/docker-compose/), the basic introduction of [docker](https://developpaper.com/tag/docker/) is not within the scope of this article. 22 | 23 | This article is basically a strict English translation of docker-compose YAML file format. That’s because yesterday I thought about scanning docker-compose orchestration.`${PWD}`As a result, Chinese is not helpful, or the official website has finally solved my ambiguity. So I think we should do a more rigorous translation and explanation to explain the details of docker-compose arrangement. 24 | 25 | Following, we mainly introduce the details of docker-compose format version 3. 26 | 27 | Reading this article, you should have a basic understanding of docker-compose, at least the basic early (version 2) format. 28 | 29 | ### About authorization 30 | 31 | The translation is subordinate to the original https://docs.docker.com/compo… 32 | 33 | The translation https://github.com/hedzr/docker-compose-file-format itself is distributed in MIT mode. 34 | 35 | ## Arrangement Format Version 3 36 | 37 | ### History 38 | 39 | Version 3 is a format supported by docker-compose since the launch of docker-engine 1.13. Before that, docker introduced swarm mode in 1.12 to build virtual computing resources in a virtual network, and greatly improved the network and storage support of docker. 40 | 41 | For the relationship between docker-compose format and docker-engine, the following table (extracted from the official website) has a clear contrast. 42 | 43 | | **Compose file format** | **Docker Engine release** | 44 | | :---------------------- | :------------------------ | 45 | | 3.7 | 18.06.0+ | 46 | | 3.6 | 18.02.0+ | 47 | | 3.5 | 17.12.0+ | 48 | | 3.4 | 17.09.0+ | 49 | | 3.3 | 17.06.0+ | 50 | | 3.2 | 17.04.0+ | 51 | | 3.1 | 1.13.1+ | 52 | | 3.0 | 1.13.0+ | 53 | | 2.4 | 17.12.0+ | 54 | | 2.3 | 17.06.0+ | 55 | | 2.2 | 1.13.0+ | 56 | | 2.1 | 1.12.0+ | 57 | | 2.0 | 1.10.0+ | 58 | | 1.0 | 1.9.1.+ | 59 | 60 | ### Arrangement file structure and examples 61 | 62 | This is a typical file structure sample of Version 3+: 63 | 64 | ``` 65 | version: "3.7" 66 | services: 67 | 68 | redis: 69 | image: redis:alpine 70 | ports: 71 | - "6379" 72 | networks: 73 | - frontend 74 | deploy: 75 | replicas: 2 76 | update_config: 77 | parallelism: 2 78 | delay: 10s 79 | restart_policy: 80 | condition: on-failure 81 | 82 | db: 83 | image: postgres:9.4 84 | volumes: 85 | - db-data:/var/lib/postgresql/data 86 | networks: 87 | - backend 88 | deploy: 89 | placement: 90 | constraints: [node.role == manager] 91 | 92 | vote: 93 | image: dockersamples/examplevotingapp_vote:before 94 | ports: 95 | - "5000:80" 96 | networks: 97 | - frontend 98 | depends_on: 99 | - redis 100 | deploy: 101 | replicas: 2 102 | update_config: 103 | parallelism: 2 104 | restart_policy: 105 | condition: on-failure 106 | 107 | result: 108 | image: dockersamples/examplevotingapp_result:before 109 | ports: 110 | - "5001:80" 111 | networks: 112 | - backend 113 | depends_on: 114 | - db 115 | deploy: 116 | replicas: 1 117 | update_config: 118 | parallelism: 2 119 | delay: 10s 120 | restart_policy: 121 | condition: on-failure 122 | 123 | worker: 124 | image: dockersamples/examplevotingapp_worker 125 | networks: 126 | - frontend 127 | - backend 128 | deploy: 129 | mode: replicated 130 | replicas: 1 131 | labels: [APP=VOTING] 132 | restart_policy: 133 | condition: on-failure 134 | delay: 10s 135 | max_attempts: 3 136 | window: 120s 137 | placement: 138 | constraints: [node.role == manager] 139 | 140 | visualizer: 141 | image: dockersamples/visualizer:stable 142 | ports: 143 | - "8080:8080" 144 | stop_grace_period: 1m30s 145 | volumes: 146 | - "/var/run/docker.sock:/var/run/docker.sock" 147 | deploy: 148 | placement: 149 | constraints: [node.role == manager] 150 | 151 | networks: 152 | frontend: 153 | backend: 154 | 155 | volumes: 156 | db-data: 157 | ``` 158 | 159 | In this sample, the top-level structure is determined by`version`，`services`，`networks`，`volumes`And so on label composition. This is not much different from Version 2. 160 | 161 | stay`services`In this chapter, you can define several services, each of which usually runs a container. These services form a whole stack of facilities, or a service group. 162 | 163 | Generally speaking, we will arrange a bunch of miscellaneous things, such as a bunch of micro-services, into a service stack, so that they can serve the outside world as a whole, thus avoiding the exposure of details. We can also enhance the flexibility of architecture design and scale the whole service stack (instead of dealing with a large number of micro-services one by one). 164 | 165 | ## Format Manual-`service` 166 | 167 | Next comes the chapter structure that a reference manual should have. We list the instructions for service choreography in alphabetical order, such as`ports`，`volumes`，`cmd`，`entry`Wait. 168 | 169 | ### `build` 170 | 171 | This option is used for construction. 172 | 173 | `build`It can be a path string pointing to the construction context, such as: 174 | 175 | ``` 176 | version: "3.7" 177 | services: 178 | webapp: 179 | build: ./dir 180 | ``` 181 | 182 | It can also be a more detailed definition. This includes`context`Path specified by item, and optional`dockerfile`File and build parameters`args`： 183 | 184 | ``` 185 | version: "3.7" 186 | services: 187 | webapp: 188 | build: 189 | context: ./dir 190 | dockerfile: Dockerfile-alternate 191 | args: 192 | buildno: 1 193 | ``` 194 | 195 | If you are appointing`build`It is also specified.`image`Then the result of the build will be marked with the corresponding name, as if`docker build -t container-name:tag dir`Do as follows: 196 | 197 | ``` 198 | build: "./dir" 199 | image: "company/webapp:v1.1.9" 200 | ``` 201 | 202 | > For YAML, the safe way to avoid ambiguity is to surround the string with quotation marks. 203 | 204 | The example above will be found.`./dir`Build context in folders (by default, find`Dockerfile`) And complete the build, and finally mark it as`company/webapp`Name, and`v1.1.9`Tag. 205 | 206 | #### `context` 207 | 208 | It can be a inclusion`Dockerfile`A folder can also be a URL to git repository. 209 | 210 | If a relative path is specified, the path is relative to`docker-compose.yml`Documentation. This path will also be sent to Docker daemon for construction. 211 | 212 | Docker-compose initiates build actions and tags build results (as per`image`After that, use it according to the corresponding name. 213 | 214 | #### `dockerfile` 215 | 216 | You can specify a different name from the default`Dockerfile`Other filenames are used for building. Note that you must also specify a path to`context`： 217 | 218 | ``` 219 | build: 220 | context: . 221 | dockerfile: Dockerfile-alternate 222 | ``` 223 | 224 | #### `args` 225 | 226 | Specify build parameters. Usually refers to the parameters used for construction (see Dockerfile)`ARG`）。 227 | 228 | The following is a brief overview: 229 | 230 | First, specify parameters in Dockerfile: 231 | 232 | ``` 233 | ARG buildno 234 | ARG gitcommithash 235 | 236 | RUN echo "Build number: $buildno" 237 | RUN echo "Based on commit: $gitcommithash" 238 | ``` 239 | 240 | Then specify the actual value of the build parameter (either an incoming Map or an array is possible): 241 | 242 | ``` 243 | build: 244 | context: . 245 | args: 246 | buildno: 1 247 | gitcommithash: cdc3b19 248 | ``` 249 | 250 | Or: 251 | 252 | ``` 253 | build: 254 | context: . 255 | args: 256 | - buildno=1 257 | - gitcommithash=cdc3b19 258 | ``` 259 | 260 | > **NOTE**In Dockerfile, if`FROM`Previously specified`ARG`Well, this one`ARG`For the following`FROM`Closures are invalid. 261 | > 262 | > Multiple`FROM`Several constructed closures were cut out. 263 | > 264 | > To want to`ARG`In each`FROM`It works in closures, and you need to specify it in each closure. 265 | > 266 | > More detailed discussions are included in Understand how ARGS and FROM interact. 267 | 268 | You can skip specifying build parameters. At this point, the actual value of this parameter depends on the environment at build time. 269 | 270 | ``` 271 | args: 272 | - buildno 273 | - gitcommithash 274 | ``` 275 | 276 | > **NOTE**Boolean quantity of YAML（`true`, `false`, `yes`, `no`, `on`, `off`) Quotation marks must be surrounded for docker-compose to handle correctly. 277 | 278 | #### `cache_from` 279 | 280 | > since v3.2 281 | 282 | Specifies a list of images for cache resolution. 283 | 284 | ``` 285 | build: 286 | context: . 287 | cache_from: 288 | - alpine:latest 289 | - corp/web_app:3.14 290 | ``` 291 | 292 | #### `labels` 293 | 294 | > since v3.3 295 | 296 | Adding metadata labels to the built image can be an array or a dictionary. 297 | 298 | We recommend the use of reverse DNS annotative prefixes to prevent conflicts between your label and the user’s label: 299 | 300 | ``` 301 | build: 302 | context: . 303 | labels: 304 | com.example.description: "Accounting webapp" 305 | com.example.department: "Finance" 306 | com.example.label-with-empty-value: "" 307 | 308 | # anothor example 309 | build: 310 | context: . 311 | labels: 312 | - "com.example.description=Accounting webapp" 313 | - "com.example.department=Finance" 314 | - "com.example.label-with-empty-value" 315 | ``` 316 | 317 | #### `shm_size` 318 | 319 | > since v3.5 320 | 321 | Setting up when building containers`/dev/shm`Partition size. Integer format is expressed in bytes, but byte value can also be used: 322 | 323 | ``` 324 | build: 325 | context: . 326 | shm_size: '2gb' 327 | 328 | build: 329 | context: . 330 | shm_size: 10000000 331 | ``` 332 | 333 | #### `target` 334 | 335 | > since v3.4 336 | 337 | Build definitions and specific steps in Dockerfile (Stage), refer to multi-stage build docs: 338 | 339 | ``` 340 | build: 341 | context: . 342 | target: prod 343 | ``` 344 | 345 | > Multiple builds are typically used for CI/CD. 346 | > 347 | > For example, step 0 can be named`builder`Step 1 extracts the target file from Step 0 for deployment packaging and generates the final container image. Then the middle layer of Step 0 is discarded. These middle layers will not appear in the final container image, thus effectively reducing the size of the final container image. The result is also semantically and logically consistent. 348 | > 349 | > ``` 350 | > FROM golang:1.7.3 AS builder 351 | > WORKDIR /go/src/github.com/alexellis/href-counter/ 352 | > RUN go get -d -v golang.org/x/net/html 353 | > COPY app.go . 354 | > RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app . 355 | > 356 | > FROM alpine:latest 357 | > RUN apk --no-cache add ca-certificates 358 | > WORKDIR /root/ 359 | > COPY --from=builder /go/src/github.com/alexellis/href-counter/app . 360 | > CMD ["./app"] 361 | > ``` 362 | > 363 | >  364 | 365 | ### `cap_add`, `cap_drop` 366 | 367 | Add or remove the Linux capabilities of containers. A complete list can be consulted.`man 7 capabilities`。 368 | 369 | ``` 370 | cap_add: 371 | - ALL 372 | 373 | cap_drop: 374 | - NET_ADMIN 375 | - SYS_ADMIN 376 | ``` 377 | 378 | > **NOTE**These options are ignored when deploying a stack to swarm mode. 379 | > 380 | > See also deploying a stack in swarm mode. 381 | 382 | Linux capability mechanism is largely a security mechanism. The specific meaning, usage and extension belong to the category of Linux operating system, and will not be further elaborated. 383 | 384 | ### `cgroup_parent` 385 | 386 | Optionally assign a superior to the container`cgroup`。`cgroup`It is also one of the most important basic concepts of Linux container implementation. 387 | 388 | ``` 389 | cgroup_parent: m-executor-abcd 390 | ``` 391 | 392 | > **NOTE**These options are ignored when deploying a stack to swarm mode. 393 | > 394 | > See also deploying a stack in swarm mode. 395 | 396 | ### `command` 397 | 398 | Overlay the default in the container`command`. 399 | 400 | ``` 401 | command: bundle exec thin -p 3000 402 | ``` 403 | 404 | `command`It can also be specified as a list. In fact, it’s also a more recommended approach, unambiguous and secure, and consistent with the format in [dockerfile]: 405 | 406 | ``` 407 | command: ["bundle", "exec", "thin", "-p", "3000"] 408 | ``` 409 | 410 | ### configs 411 | 412 | Provide specific access to each service`config`Permissions. 413 | 414 | One`config`Contains a series of configuration information that may be created in a variety of ways. When the deployment of containers refers to these configurations, problems such as production environment parameters can be better partitioned. On the other hand, sensitive information can be separated into a secure area, which reduces the possibility of leakage to a certain extent. 415 | 416 | > **NOTE**The specified configuration must already exist or be defined at the top level`configs`Defined in the top-level`configs`Configuration). Otherwise, the deployment of the entire container stack will fail. 417 | 418 | Two different grammatical variants are supported. More detailed information should refer to configs. 419 | 420 | #### Short format 421 | 422 | Specify only the configuration name. Containers therefore have access to the configuration`/ **Note**: `config`Definitions are supported only in the docker-compose format of v3.3 and later. 446 | 447 | #### Long format 448 | 449 | Long format provides more information to express one`config`Where, how to be found, how to be used: 450 | 451 | - `source`Configuration name 452 | 453 | - `target`The configuration will be mounted to the path in the container. Default is`/` 454 | 455 | - `uid` & `gid`Linux/Unix for digital values`UID`and`GID`If not specified, 0. Windows does not support it. 456 | 457 | - ``` 458 | mode 459 | ``` 460 | 461 | 8-digit file permissions. The default value is 462 | 463 | ``` 464 | 0444 465 | ``` 466 | 467 | 。 468 | 469 | 470 | 471 | Configurations are not writable because they are mounted on temporary file systems. So if you set a write license, it will be ignored. 472 | 473 | Executable bits can be set. 474 | 475 | The following example is similar to the short format example: 476 | 477 | ``` 478 | version: "3.7" 479 | services: 480 | redis: 481 | image: redis:latest 482 | deploy: 483 | replicas: 1 484 | configs: 485 | - source: my_config 486 | target: /redis_config 487 | uid: '103' 488 | gid: '103' 489 | mode: 0440 490 | configs: 491 | my_config: 492 | file: ./my_config.txt 493 | my_other_config: 494 | external: true 495 | ``` 496 | 497 | Ad locum,`redis`Container services are not accessed`my_other_config`。 498 | 499 | You can authorize a service to access multiple configurations, or you can mix long and short formats. 500 | 501 | Define a configuration (at the top level)（`config`) It does not imply that a service can be accessed. 502 | 503 | ### `container_name` 504 | 505 | Specify a custom container name instead of a default generated by docker-compose itself. 506 | 507 | ``` 508 | container_name: my-web-container 509 | ``` 510 | 511 | Because the Docker container name must be unique, you cannot scale a service that customizes the container name. 512 | 513 | > **NOTE**These options are ignored when deploying a stack to swarm mode. 514 | > 515 | > See also deploying a stack in swarm mode. 516 | 517 | ### `credential_spec` 518 | 519 | > since v3.3 520 | > 521 | > Since v3.8, support has been provided for the gMSA (group Managed Service Account) approach used for group management service accounts. 522 | 523 | Configure credentials for controlled service accounts. This option is only used for Windows Container Services.`credential_spce`Format only`file://` or `registry://`。 524 | 525 | When used`file:`When the reference file must be placed in the Docker data folder (usually`C:\ProgramData\Docker\`）的`CredentialSpec`Under the subdirectory. The following example will be from`C:\ProgramData\Docker\CredentialSpecs\my-credential-sp`Load credential information: 526 | 527 | ``` 528 | credential_spec: 529 | file: my-credential-spec.json 530 | ``` 531 | 532 | When used`registry:`Credential information will be read from the Windows Registry of the Docker daemon host. A registry entry must be located at: 533 | 534 | ``` 535 | HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs 536 | ``` 537 | 538 | In 539 | 540 | The following example is read in`my-credential-spec`Registry key values: 541 | 542 | ``` 543 | credential_spec: 544 | registry: my-credential-spec 545 | ``` 546 | 547 | #### GMSA configuration example 548 | 549 | When configuring gMSA credentials for a service, refer to the following example: 550 | 551 | ``` 552 | version: "3.8" 553 | services: 554 | myservice: 555 | image: myimage:latest 556 | credential_spec: 557 | config: my_credential_spec 558 | 559 | configs: 560 | my_credentials_spec: 561 | file: ./my-credential-spec.json| 562 | ``` 563 | 564 | ### `depends_on` 565 | 566 | Represents the dependencies between services. Service dependency triggers the following behavior: 567 | 568 | - `docker-compose up`Start the service in sequence of dependencies. In the following example,`db`and`redis`Precede`web`Be activated. 569 | - `docker-compose up SERVICE`Automatically included`SERVICE`Dependencies of the ___________. In the following example,`docker-compose up web`Will start automatically`db`and`redis`。 570 | - `docker-compose stop`Stop the service in order of dependency. In the following example,`web`Will be preceded by`db`and`redis`Be stopped. 571 | 572 | A simple example is as follows: 573 | 574 | ``` 575 | version: "3.7" 576 | services: 577 | web: 578 | build: . 579 | depends_on: 580 | - db 581 | - redis 582 | redis: 583 | image: redis 584 | db: 585 | image: postgres 586 | ``` 587 | 588 | > Use`depends_on`Several things should be paid attention to: 589 | > 590 | > - `depends_on`It doesn’t mean waiting.`db`and`redis`Start after you are ready`web`It starts after they are started.`web`。 If you want to wait until the service is ready to be available, you should refer to Controlling startup order. 591 | > - Version 3 is no longer supported`condition`Expression. 592 | > - `depends_on`Options are ignored when deployed to swarm mode. 593 | > 594 | > See also deploying a stack in swarm mode. 595 | 596 | ### `deploy` 597 | 598 | > **Version 3 only.** 599 | 600 | Specify and deploy and run related configurations. 601 | 602 | It only affects the deployment to a swarm using docker stack deployment. 603 | 604 | stay`docker-compose up`and`docker-compose run`It was overlooked. 605 | 606 | ``` 607 | version: "3.7" 608 | services: 609 | redis: 610 | image: redis:alpine 611 | deploy: 612 | replicas: 6 613 | update_config: 614 | parallelism: 2 615 | delay: 10s 616 | restart_policy: 617 | condition: on-failure 618 | ``` 619 | 620 | Several sub-options are available: 621 | 622 | #### `endpoint_mode` 623 | 624 | swarm. 625 | 626 | > **Version 3.3 only.** 627 | 628 | - ``` 629 | endpoint_mode: vip 630 | ``` 631 | 632 | – Docker requests a virtual IP for the service（ 633 | 634 | ``` 635 | VIP 636 | ``` 637 | 638 | ) Used for access. 639 | 640 | 641 | 642 | Docker routes requests automatically between the client and the service’s valid working nodes. The client does not need to know how many nodes are available for the service, nor does it need to know the IP address and port number of the service node. 643 | 644 | This is the default way. 645 | 646 | - `endpoint_mode: dnsrr`– DNS round-robin (DNSRR) algorithm is used for service discovery. Docker sets up a DNS entry for the service, so a list of IP addresses is returned through the service name when the corresponding DNS resolution is performed. Clients therefore directly select a specific endpoint for access. 647 | 648 | ``` 649 | version: "3.7" 650 | 651 | services: 652 | wordpress: 653 | image: wordpress 654 | ports: 655 | - "8080:80" 656 | networks: 657 | - overlay 658 | deploy: 659 | mode: replicated 660 | replicas: 2 661 | endpoint_mode: vip 662 | 663 | mysql: 664 | image: mysql 665 | volumes: 666 | - db-data:/var/lib/mysql/data 667 | networks: 668 | - overlay 669 | deploy: 670 | mode: replicated 671 | replicas: 2 672 | endpoint_mode: dnsrr 673 | 674 | volumes: 675 | db-data: 676 | 677 | networks: 678 | overlay: 679 | ``` 680 | 681 | `endpoint_mode`The option of swarm mode is also used as the command line option (see`docker service create`) For a quick list of docker swarm commands, you can refer to Swarm mode CLI commands. 682 | 683 | To learn more about swarm mode’s network model and service discovery mechanism, see Configure service discovery. 684 | 685 | #### `labels` 686 | 687 | Specify labels for services. These tags are only applied to the corresponding service, not to the container or container instance of the service. 688 | 689 | ``` 690 | version: "3.7" 691 | services: 692 | web: 693 | image: web 694 | deploy: 695 | labels: 696 | com.example.description: "This label will appear on the web service" 697 | ``` 698 | 699 | To set labels for containers, the`deploy`Specify services beyond`labels`： 700 | 701 | ``` 702 | version: "3.7" 703 | services: 704 | web: 705 | image: web 706 | labels: 707 | com.example.description: "This label will appear on all containers for the web service" 708 | ``` 709 | 710 | #### `mode` 711 | 712 | Could be`global`or`replicated`。`global`Represents strictly a swarm node running a service.`replicated`Represents that multiple container instances can be run. The default is`replicated`。 713 | 714 | Refer to Replicated and Global Services under the swarm theme. 715 | 716 | ``` 717 | version: "3.7" 718 | services: 719 | worker: 720 | image: dockersamples/examplevotingapp_worker 721 | deploy: 722 | mode: global 723 | ``` 724 | 725 | #### `placement` 726 | 727 | Specify constraints and preferences. 728 | 729 | Refer to the documentation of docker service establishment for more information about constraints and preferences, including the corresponding grammar, available types, and so on. 730 | 731 | ``` 732 | version: "3.7" 733 | services: 734 | db: 735 | image: postgres 736 | deploy: 737 | placement: 738 | constraints: 739 | - node.role == manager 740 | - engine.labels.operatingsystem == ubuntu 14.04 741 | preferences: 742 | - spread: node.labels.zone 743 | ``` 744 | 745 | #### `replicas` 746 | 747 | If the service is`replicated`,`replicas`Specifies a value for it, which indicates how many container instances can be run on a swarm node at most. 748 | 749 | ``` 750 | version: "3.7" 751 | services: 752 | worker: 753 | image: dockersamples/examplevotingapp_worker 754 | networks: 755 | - frontend 756 | - backend 757 | deploy: 758 | mode: replicated 759 | replicas: 6 760 | ``` 761 | 762 | #### `resources` 763 | 764 | Configuration resource constraints. 765 | 766 | > **NOTE**For non-swarm mode, this table entry replaces older resource constraint options (such as`cpu_shares`, `cpu_quota`, `cpuset`, `mem_limit`, `memswap_limit`, `mem_swappiness`Table entries waiting before version 3. 767 | > 768 | > It is described in Upgrading version 2.x to 3.x. 769 | 770 | These resource constraint table entries all have a single value, equivalent to`docker service create`The equivalents in the. 771 | 772 | In the following example,`redis`Services are constrained to not use more than 50M of memory, 50% CPU usage per single core, while retaining 20M of memory and 25% CPU usage as benchmarks. 773 | 774 | ``` 775 | version: "3.7" 776 | services: 777 | redis: 778 | image: redis:alpine 779 | deploy: 780 | resources: 781 | limits: 782 | cpus: '0.50' 783 | memory: 50M 784 | reservations: 785 | cpus: '0.25' 786 | memory: 20M 787 | ``` 788 | 789 | The following topics describe the available options for service or container resource constraints in a swarm scenario. 790 | 791 | ##### Out Of Memory Exceptions (OOME) 792 | 793 | If you attempt to use more memory than the system has in your service and container instances, you will get Out of Memory Exception (OOME). At this point, a container instance, or Docker daemon, may be cleaned up by the OOM manager of the kernel. 794 | 795 | To prevent this from happening, make sure that your application uses memory legally and efficiently. For such risks, consult Understand the risks of running out of memory for further assessment instructions. 796 | 797 | #### `restart_policy` 798 | 799 | Indicates how to restart a container instance when it exits. replace`restart`： 800 | 801 | - `condition`It can be`none`, `on-failure`or`any`(by default)`any`) 802 | - `delay`Waiting time before attempting to restart (default is 0). A duration should be specified for it. 803 | - `max_attempts`Trying to restart how many times and then giving up the attempt to restart. The default is not to give up. 804 | - `window`To determine whether a reboot is successful, you need to wait a long time. The default is that no waiting is immediately recognized as successful. A duration should be specified for it. 805 | 806 | ``` 807 | version: "3.7" 808 | services: 809 | redis: 810 | image: redis:alpine 811 | deploy: 812 | restart_policy: 813 | condition: on-failure 814 | delay: 5s 815 | max_attempts: 3 816 | window: 120s 817 | ``` 818 | 819 | #### `rollback_config` 820 | 821 | > Version 3.7 file format and up 822 | 823 | How should the service roll back in a scenario where rolling updates fail: 824 | 825 | - `parallelism`Number of containers rolled back at the same time. If set to 0, all containers will be rolled back at the same time. 826 | - `delay`Waiting time before each container group is rolled back (default is 0) 827 | - `failure_action`An action that should be performed when a rollback fails. Could be`continue`or`pause`(by default)`pause`） 828 | - `monitor`The failed rollback status is updated to the monitor cycle（`ns|us|ms|s|m|h`Default is`0s`。 829 | - `max_failure_ratio`Tolerable percentage of failures when rollback occurs (default is 0) 830 | - `order`Rollback operation sequence. Can be`stop-first`or`start-first`(by default)`stop-first`） 831 | 832 | #### `update_config` 833 | 834 | Indicates how the service should be updated. This is useful for configuring scrolling updates: 835 | 836 | - `parallelism`Number of containers updated at the same time. If set to 0, all containers will be rolled back at the same time. 837 | - `delay`Waiting time before each container group is updated (default is 0) 838 | - `failure_action`An action that should be performed when an update fails. Could be`continue`or`pause`(by default)`pause`） 839 | - `monitor`The failed update status is updated to the monitor cycle（`ns|us|ms|s|m|h`Default is`0s`。 840 | - `max_failure_ratio`Tolerable percentage of failures when updating (default 0) 841 | - `order`Update the order of operation. Can be`stop-first`or`start-first`(by default)`stop-first`） 842 | 843 | > **NOTE**：`order`Valid only after v3.4. 844 | 845 | ``` 846 | version: "3.7" 847 | services: 848 | vote: 849 | image: dockersamples/examplevotingapp_vote:before 850 | depends_on: 851 | - redis 852 | deploy: 853 | replicas: 2 854 | update_config: 855 | parallelism: 2 856 | delay: 10s 857 | order: stop-first 858 | ``` 859 | 860 | #### NOT SUPPORTED FOR `DOCKER STACK DEPLOY` 861 | 862 | The following sub-options (for`docker-compose up`and`docker-compose run`Supported)`docker stack deploy`Unsupported: 863 | 864 | - build 865 | - cgroup_parent 866 | - container_name 867 | - devices 868 | - tmpfs 869 | - external_links 870 | - links 871 | - network_mode 872 | - restart 873 | - security_opt 874 | - sysctls 875 | - userns_mode 876 | 877 | > **Tip:** See the section on how to configure volumes for services, swarms, and docker-stack.yml files. Volumes *are* supported but to work with swarms and services, they must be configured as named volumes or associated with services that are constrained to nodes with access to the requisite volumes. 878 | 879 | ### `devices` 880 | 881 | List of devices to be mapped. Its usage and docker command`--device`The same. 882 | 883 | ``` 884 | devices: 885 | - "/dev/ttyUSB0:/dev/ttyUSB0" 886 | ``` 887 | 888 | > **NOTE**These options are ignored when deploying a stack to swarm mode. 889 | > 890 | > See also deploying a stack in swarm mode. 891 | 892 | ### `dns` 893 | 894 | Customize DNS server list. You can specify a single value or a list. 895 | 896 | ``` 897 | dns: 8.8.8.8 898 | dns: 899 | - 8.8.8.8 900 | - 9.9.9.9 901 | ``` 902 | 903 | ### `dns_search` 904 | 905 | Customize DNS search domain name. You can specify a single value or a list. 906 | 907 | ``` 908 | dns_search: example.com 909 | dns_search: 910 | - dc1.example.com 911 | - dc2.example.com 912 | ``` 913 | 914 | ### `entrypoint` 915 | 916 | Override the default entrypoint value defined in the dockerfile. 917 | 918 | ``` 919 | entrypoint: /code/entrypoint.sh 920 | ``` 921 | 922 | The entry point can also be a list: 923 | 924 | ``` 925 | entrypoint: 926 | - php 927 | - -d 928 | - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so 929 | - -d 930 | - memory_limit=-1 931 | - vendor/bin/phpunit 932 | ``` 933 | 934 | > **NOTE**Set up a`entrypoint`Not only does it cover anything in Dockerfile`ENTRYPOINT`Default value, also cleans up any of the Dockerfile`CMD`Default value. So in Dockerfile`CMD`It will be ignored. 935 | 936 | ### `env_file` 937 | 938 | Introduce environment variable values from a given file. It can be a single value or a list. 939 | 940 | ``` 941 | env_file: .env 942 | env_file: 943 | - ./common.env 944 | - ./apps/web.env 945 | - /opt/secrets.env 946 | ``` 947 | 948 | about`docker-compose -f FILE`For example,`env_file`The path is relative to`FILE`The one in the folder. 949 | 950 | stay`environment`The environment variables declared in this statement will override the values introduced here. 951 | 952 | In the corresponding file, each line should be used`VAR=VAL`Format defines an environment variable. The first line is`#`Represents a comment line, which is ignored as a blank line. 953 | 954 | ``` 955 | # Set Rails/Rack environment 956 | RACK_ENV=development 957 | ``` 958 | 959 | > **NOTE**If the service is defined`build`Items, in the construction process, are`env_file`The environment variables defined are not visible. Only use`build`Suboptions`args`Define the value of the environment variable at build time. 960 | 961 | `VAL`The value is used as it is and cannot be modified. For example, if the value is surrounded by quotation marks, then quotation marks are also included in the representation of the value. 962 | 963 | The order of environment variable files also needs to be noted. The value of the variable defined in the environment variable file at the back of the location overrides the old value defined earlier. 964 | 965 | ### `environment` 966 | 967 | Add environment variables. You can use an array or a dictionary. Any Boolean quantities: true, false, yes, no, etc. must be surrounded by quotation marks as string literals. 968 | 969 | Value values of environment variables with only key values depend on the host environment of the docker-compose runtime, which is useful for preventing sensitive information leakage. 970 | 971 | ``` 972 | environment: 973 | RACK_ENV: development 974 | SHOW: 'true' 975 | SESSION_SECRET: 976 | environment: 977 | - RACK_ENV=development 978 | - SHOW=true 979 | - SESSION_SECRET 980 | ``` 981 | 982 | > **NOTE**If the service is defined`build`Items, in the construction process, are`env_file`The environment variables defined are not visible. Only use`build`Suboptions`args`Define the value of the environment variable at build time. 983 | 984 | ### `expose` 985 | 986 | Expose ports to linked services. These ports will not be published to the host. Only internal ports can be specified for exposure. 987 | 988 | ``` 989 | expose: 990 | - "3000" 991 | - "8000" 992 | ``` 993 | 994 | ### `external_links` 995 | 996 | Will be in`docker-compose.yml`Containers started outside are linked to a given service. 997 | 998 | And legacy options`links`It has similar semantics. 999 | 1000 | ``` 1001 | external_links: 1002 | - redis_1 1003 | - project_db_1:mysql 1004 | - project_db_1:postgresql 1005 | ``` 1006 | 1007 | > **NOTE**These options are ignored when deploying a stack to swarm mode. 1008 | > 1009 | > See also deploying a stack in swarm mode. 1010 | 1011 | The more recommended approach is through`networks`Construct a subnet to link containers. 1012 | 1013 | ### `extra_hosts` 1014 | 1015 | Add host name mapping. These mappings will be added`/etc/hosts`Medium. This function is equivalent to command line parameters`--add-host`。 1016 | 1017 | ``` 1018 | extra_hosts: 1019 | - "somehost:162.242.195.82" 1020 | - "otherhost:50.31.209.229" 1021 | ``` 1022 | 1023 | ### `healthcheck` 1024 | 1025 | > since v2.1 1026 | 1027 | Used to confirm whether a service is “healthy”. See HEALTHCHECK Docker file instruction. 1028 | 1029 | ``` 1030 | healthcheck: 1031 | test: ["CMD", "curl", "-f", "http://localhost"] 1032 | interval: 1m30s 1033 | timeout: 10s 1034 | retries: 3 1035 | start_period: 40s 1036 | ``` 1037 | 1038 | `interval`, `timeout`and`start_period`It should be designated durations. 1039 | 1040 | > **Note**: `start_period`Only available in v3.4 and beyond. 1041 | 1042 | `test`Must be a single string value or a list. If it’s a list, the first item must be`NONE`, `CMD`, `CMD-SHELL`One of. If it’s a string, it implicitly represents a string`CMD-SHELL`Prefix. 1043 | 1044 | ``` 1045 | # Hit the local web app 1046 | test: ["CMD", "curl", "-f", "http://localhost"] 1047 | ``` 1048 | 1049 | As in the above example, but implicitly invoked`/bin/sh`It is equivalent to the following form. 1050 | 1051 | ``` 1052 | test: ["CMD-SHELL", "curl -f http://localhost || exit 1"] 1053 | test: curl -f https://localhost || exit 1 1054 | ``` 1055 | 1056 | To disable any default health check directions specified in the image, use`disable: true`。 This and specify`test: ["NONE"]`It is equivalent. 1057 | 1058 | ``` 1059 | healthcheck: 1060 | disable: true 1061 | ``` 1062 | 1063 | ### `image` 1064 | 1065 | Specify the name of the image. 1066 | 1067 | ``` 1068 | image: redis 1069 | image: ubuntu:14.04 1070 | image: tutum/influxdb 1071 | image: example-registry.com:4000/postgresql 1072 | image: a4bc65fd 1073 | ``` 1074 | 1075 | If the image does not exist on the host, Compose will try to drop it down unless you specify it as well.`build`Item. 1076 | 1077 | ### `init` 1078 | 1079 | > since v3.7 1080 | 1081 | Run an init process in the container and forward the signal. Set to`true`Enabling this feature for service. 1082 | 1083 | ``` 1084 | version: "3.7" 1085 | services: 1086 | web: 1087 | image: alpine:latest 1088 | init: true 1089 | ``` 1090 | 1091 | > The default init process uses the binary execution file Tini, which will be installed in the location of the daemon host as needed`/usr/libexec/docker-init`。 You can also configure daemon to use a different binary file by`init-path`Refer to configuration option. 1092 | 1093 | ### `isolation` 1094 | 1095 | Specify the isolation level/technology for a container. In Linux, only support`default`Value. In Windows, acceptable values are:`default`, `process`and`hyperv`。 1096 | 1097 | ### `labels` 1098 | 1099 | Add metadata labels to the container, refer to Docker labels. You can specify an array or a dictionary for it. 1100 | 1101 | We recommend that you use reverse DNS tagging to define your tags, which can effectively avoid tag name conflicts. 1102 | 1103 | ``` 1104 | labels: 1105 | com.example.description: "Accounting webapp" 1106 | com.example.department: "Finance" 1107 | com.example.label-with-empty-value: "" 1108 | labels: 1109 | - "com.example.description=Accounting webapp" 1110 | - "com.example.department=Finance" 1111 | - "com.example.label-with-empty-value" 1112 | ``` 1113 | 1114 | ### `links` 1115 | 1116 | > It’s already a legacy feature. It will be removed in the near future. 1117 | 1118 | Link another service to this container. Service names and link aliases can be developed simultaneously（`SERVICE:ALIAS`You can also skip the link alias. 1119 | 1120 | ``` 1121 | web: 1122 | links: 1123 | - db 1124 | - db:database 1125 | - redis 1126 | ``` 1127 | 1128 | The service that has been chained in will be the host name (that is, the link alias).`ALIAS`) Accessible. 1129 | 1130 | Links are not necessary for inter-service communication. By default, any service can access other services by service name. See Links topics in Networking in Compose. 1131 | 1132 | Links also indicate a dependency, but this is already the case`depends_on`Tasks, so links are not necessary. 1133 | 1134 | ### `logging` 1135 | 1136 | Specify the log forwarding configuration for the service. 1137 | 1138 | ``` 1139 | logging: 1140 | driver: syslog 1141 | options: 1142 | syslog-address: "tcp://192.168.0.42:123" 1143 | ``` 1144 | 1145 | `driver`The driver name is specified. This and`--log-driver`It is equivalent. The default value is`json-file`。 1146 | 1147 | ``` 1148 | driver: "json-file" 1149 | driver: "syslog" 1150 | driver: "none" 1151 | ``` 1152 | 1153 | The available forwarding drivers can be referred to at https://docs.docker.com/confi… 1154 | 1155 | Use`option`Specify driver options as follows`--log-opt`That way. For example`syslog`This specifies: 1156 | 1157 | ``` 1158 | driver: "syslog" 1159 | options: 1160 | syslog-address: "tcp://192.168.0.42:123" 1161 | ``` 1162 | 1163 | The default log forwarding driver is`json-file`。 For this purpose, you can specify the log cutting size and the maximum number of log history files to maintain: 1164 | 1165 | ``` 1166 | version: "3.7" 1167 | services: 1168 | some-service: 1169 | image: some-service 1170 | logging: 1171 | driver: "json-file" 1172 | options: 1173 | max-size: "200k" 1174 | max-file: "10" 1175 | ``` 1176 | 1177 | ### `network_mode` 1178 | 1179 | Network model. 1180 | 1181 | and`--network`The values are the same. But additional support`service:[service name]`Pattern. 1182 | 1183 | ``` 1184 | network_mode: "bridge" 1185 | network_mode: "host" 1186 | network_mode: "none" 1187 | network_mode: "service:[service name]" 1188 | network_mode: "container:[container name/id]" 1189 | ``` 1190 | 1191 | > **NOTE**These options are ignored when deploying a stack to swarm mode. 1192 | > 1193 | > See also deploying a stack in swarm mode. 1194 | > 1195 | > **NOTE**: `network_mode: "host"`You can’t mix it with links. 1196 | 1197 | ### `networks` 1198 | 1199 | The network to join. The target network is`docker-compose.yml`Top-level`networks`Defined in the item. 1200 | 1201 | ``` 1202 | services: 1203 | some-service: 1204 | networks: 1205 | - some-network 1206 | - other-network 1207 | ``` 1208 | 1209 | #### ALIASES 1210 | 1211 | Specify an alias for the service (that is, the host name) in the network. Other containers in the same network can use service names or service aliases to connect to container instances of the service. 1212 | 1213 | Since`aliases`Is within the scope of the network, the same service in different networks can have different aliases. 1214 | 1215 | ``` 1216 | services: 1217 | some-service: 1218 | networks: 1219 | some-network: 1220 | aliases: 1221 | - alias1 1222 | - alias3 1223 | other-network: 1224 | aliases: 1225 | - alias2 1226 | ``` 1227 | 1228 | A more complex and complete example: 1229 | 1230 | ``` 1231 | version: "3.7" 1232 | 1233 | services: 1234 | web: 1235 | image: "nginx:alpine" 1236 | networks: 1237 | - new 1238 | 1239 | worker: 1240 | image: "my-worker-image:latest" 1241 | networks: 1242 | - legacy 1243 | 1244 | db: 1245 | image: mysql 1246 | networks: 1247 | new: 1248 | aliases: 1249 | - database 1250 | legacy: 1251 | aliases: 1252 | - mysql 1253 | 1254 | networks: 1255 | new: 1256 | legacy: 1257 | ``` 1258 | 1259 | #### IPV4_ADDRESS, IPV6_ADDRESS 1260 | 1261 | Specify a static IP address. 1262 | 1263 | Note that in the corresponding top-level network configuration, there must be`ipam`The block configures the subnet and the static IP address conforms to the definition of the subnet. 1264 | 1265 | > If IPv6 addressing is desired, the `enable_ipv6` option must be set, and you must use a version 2.x Compose file. *IPv6 options do not currently work in swarm mode*. 1266 | 1267 | An example is: 1268 | 1269 | ``` 1270 | version: "3.7" 1271 | 1272 | services: 1273 | app: 1274 | image: nginx:alpine 1275 | networks: 1276 | app_net: 1277 | ipv4_address: 172.16.238.10 1278 | ipv6_address: 2001:3984:3989::10 1279 | 1280 | networks: 1281 | app_net: 1282 | ipam: 1283 | driver: default 1284 | config: 1285 | - subnet: "172.16.238.0/24" 1286 | - subnet: "2001:3984:3989::/64" 1287 | ``` 1288 | 1289 | ### `pid` 1290 | 1291 | ``` 1292 | pid: "host" 1293 | ``` 1294 | 1295 | Set up the service to use the host’s PID mode. This enables the service process in the container and the host operating system level to share the PID address space. This is a typical Linux/Unix operating system concept, so it’s not covered here. Such sharing can enable secure IPC communication with the help of PID address space. 1296 | 1297 | ### `ports` 1298 | 1299 | Expose the port to the host. 1300 | 1301 | > **Note**Port Exposure Function and`network_mode: host`Not compatible. 1302 | 1303 | ### Short format 1304 | 1305 | Host and container ports can be specified at the same time（`HOST:CONTAINER`) To complete the mapping, you can also specify only container ports to automatically map to~~Same host port~~A temporary port (from 32768). 1306 | 1307 | ``` 1308 | ports: 1309 | - "3000" 1310 | - "3000-3005" 1311 | - "8000:8000" 1312 | - "9090-9091:8080-8081" 1313 | - "49100:22" 1314 | - "127.0.0.1:8001:8001" 1315 | - "127.0.0.1:5000-5010:5000-5010" 1316 | - "6060:6060/udp" 1317 | ``` 1318 | 1319 | #### Long format 1320 | 1321 | Lengthy definitions are allowed: 1322 | 1323 | ``` 1324 | ports: 1325 | - target: 80 1326 | published: 8080 1327 | protocol: tcp 1328 | mode: host 1329 | ``` 1330 | 1331 | > The significance is obvious, so skip the explanation. 1332 | > 1333 | > **NOTE**Long format is valid only after v3.2. 1334 | 1335 | ### `restart` 1336 | 1337 | `no`It is the default restart policy. No matter how the container exits or fails, it will not be restarted automatically. 1338 | 1339 | Appoint`always`In any case, the container will be restarted. 1340 | 1341 | `on-failure`Policies can be restarted only when the container fails to exit. 1342 | 1343 | ``` 1344 | restart: "no" 1345 | restart: always 1346 | restart: on-failure 1347 | restart: unless-stopped 1348 | ``` 1349 | 1350 | > **NOTE**These options are ignored when deploying a stack to swarm mode. (At this point, you can use`restart_policy`To achieve the goal) 1351 | > 1352 | > See also deploying a stack in swarm mode. 1353 | 1354 | ### `secrets` 1355 | 1356 | From each service configuration, authorize access to the top level`secrets`Defined table entries. Supports two formats, length and length. 1357 | 1358 | #### Short format 1359 | 1360 | Short formats specify only the names of sensitive content. This enables the container to mount the corresponding content to`/run/secrets/`Location and access it. 1361 | 1362 | The following example uses a short format to let`redis`Can access`my_secret`and`my_other_secret`。`my_secret`Specific content is defined in`./my_secret.txt`，`my_other_secret`Defined as external resources, such as through`docker secret create`The way is predefined. If no corresponding external resource is found, stack deployment will fail and throw one`secret not found`Mistake. 1363 | 1364 | ``` 1365 | version: "3.7" 1366 | services: 1367 | redis: 1368 | image: redis:latest 1369 | deploy: 1370 | replicas: 1 1371 | secrets: 1372 | - my_secret 1373 | - my_other_secret 1374 | secrets: 1375 | my_secret: 1376 | file: ./my_secret.txt 1377 | my_other_secret: 1378 | external: true 1379 | ``` 1380 | 1381 | #### Long format 1382 | 1383 | Long formats can define more precisely how sensitive content is used in stack contexts. 1384 | 1385 | - `source`Names of sensitive content defined in Docker. 1386 | - `target`To be mounted in a container`/run/secrets/`File name in. Use if not specified`source`Name. 1387 | - `uid` & `gid`The UID and GID of the files mounted in the container. If not specified, 0. Invalid in Windows. 1388 | - `mode`Octal permissions for files mounted in containers. Default value in Docker 1.13.1`0000`But in the updated version`0444`。 The mounted file is not writable. Execution bits can be set, but in general they don’t make sense. 1389 | 1390 | Here is an example: 1391 | 1392 | ``` 1393 | version: "3.7" 1394 | services: 1395 | redis: 1396 | image: redis:latest 1397 | deploy: 1398 | replicas: 1 1399 | secrets: 1400 | - source: my_secret 1401 | target: redis_secret 1402 | uid: '103' 1403 | gid: '103' 1404 | mode: 0440 1405 | secrets: 1406 | my_secret: 1407 | file: ./my_secret.txt 1408 | my_other_secret: 1409 | external: true 1410 | ``` 1411 | 1412 | Long and short formats can be mixed up if you define multiple sensitive content. 1413 | 1414 | ### `security_opt` 1415 | 1416 | Override the default tag semantics for each container. 1417 | 1418 | ``` 1419 | security_opt: 1420 | - label:user:USER 1421 | - label:role:ROLE 1422 | ``` 1423 | 1424 | Usually this is related to seccomp, which is a lengthy topic related to security configuration, so don’t expand here. 1425 | 1426 | > **NOTE**These options are ignored when deploying a stack to swarm mode. (At this point, you can use`restart_policy`To achieve the goal) 1427 | > 1428 | > See also deploying a stack in swarm mode. 1429 | 1430 | ### stop_grace_period 1431 | 1432 | Specify a waiting time if the container fails to block`SIGTERM`Signal (or through)`stop_signal`The other signals defined) shut themselves down normally, and then force the removal of the corresponding process of the container instance long after that time (via`SIGKILL`Signal). 1433 | 1434 | ``` 1435 | stop_grace_period: 1s 1436 | stop_grace_period: 1m30s 1437 | ``` 1438 | 1439 | By default, it will wait 10 seconds. 1440 | 1441 | ### `stop_signal` 1442 | 1443 | Set an alternate signal to close the container instance normally. Use by default`SIGTERM`Signal. 1444 | 1445 | ``` 1446 | stop_signal: SIGUSR1 1447 | ``` 1448 | 1449 | ### `sysctls` 1450 | 1451 | Set the kernel parameters for the container. You can use an array or dictionary. 1452 | 1453 | ``` 1454 | sysctls: 1455 | net.core.somaxconn: 1024 1456 | net.ipv4.tcp_syncookies: 0 1457 | sysctls: 1458 | - net.core.somaxconn=1024 1459 | - net.ipv4.tcp_syncookies=0 1460 | ``` 1461 | 1462 | > **NOTE**These options are ignored when deploying a stack to swarm mode. (At this point, you can use`restart_policy`To achieve the goal) 1463 | > 1464 | > See also deploying a stack in swarm mode. 1465 | 1466 | ### `tmpfs` 1467 | 1468 | > since v2 1469 | 1470 | Mount a temporary file system into the container. It can be a single value or a list. 1471 | 1472 | ``` 1473 | tmpfs: /run 1474 | tmpfs: 1475 | - /run 1476 | - /tmp 1477 | ``` 1478 | 1479 | > **NOTE**These options are ignored when deploying a stack to swarm mode. (At this point, you can use`restart_policy`To achieve the goal) 1480 | > 1481 | > See also deploying a stack in swarm mode. 1482 | 1483 | > since v3.6 1484 | 1485 | Mount a temporary file system into the container. The Size parameter specifies the byte size of the file system size. The default value is infinite. 1486 | 1487 | ``` 1488 | - type: tmpfs 1489 | target: /app 1490 | tmpfs: 1491 | size: 1000 1492 | ``` 1493 | 1494 | ### `ulimits` 1495 | 1496 | Overrides the default ulimits value specified in the container. You can specify an integer as a single limit limit or a mapping to represent soft / hard limit limits, respectively. 1497 | 1498 | ``` 1499 | ulimits: 1500 | nproc: 65535 1501 | nofile: 1502 | soft: 20000 1503 | hard: 40000 1504 | ``` 1505 | 1506 | ### `userns_mode` 1507 | 1508 | ``` 1509 | userns_mode: "host" 1510 | ``` 1511 | 1512 | Disable user namespace. If Docker daemon is configured to run in a user namespace. 1513 | 1514 | > **NOTE**These options are ignored when deploying a stack to swarm mode. (At this point, you can use`restart_policy`To achieve the goal) 1515 | > 1516 | > See also deploying a stack in swarm mode. 1517 | 1518 | ### `volumes` 1519 | 1520 | Mount the host path or named volume. 1521 | 1522 | You can mount a host path to a service without having to be at the top level`volumes`It is defined. 1523 | 1524 | If you want to reuse one volume to multiple services, you should be at the top level`volumes`Define it and name it. 1525 | 1526 | Named volumes can be used in services, swarms, and stack files. 1527 | 1528 | > **NOTE**At the top`volumes`Define a named volume in a service`volumes`Refer to it in the list. 1529 | > 1530 | > Early`volumes_from`No longer in use. 1531 | > 1532 | > Refer to Use volumes and Volume Plugins. 1533 | 1534 | The following example illustrates a named volume`my_data`And used for`web`Service. stay`web`A host folder is also used in the`./static`To mount in a container; to mount in a container.`db`It mounts a host file to the corresponding file in the container and uses another named volume.`dbdata`。 1535 | 1536 | ``` 1537 | version: "3.7" 1538 | services: 1539 | web: 1540 | image: nginx:alpine 1541 | volumes: 1542 | - type: volume 1543 | source: mydata 1544 | target: /data 1545 | volume: 1546 | nocopy: true 1547 | - type: bind 1548 | source: ./static 1549 | target: /opt/app/static 1550 | 1551 | db: 1552 | image: postgres:latest 1553 | volumes: 1554 | - "/var/run/postgres/postgres.sock:/var/run/postgres/postgres.sock" 1555 | - "dbdata:/var/lib/postgresql/data" 1556 | 1557 | volumes: 1558 | mydata: 1559 | dbdata: 1560 | ``` 1561 | 1562 | #### Short format 1563 | 1564 | have access to`HOST:CONTAINER`Format, or with an access mode`HOST:CONTAINER:ro`。 1565 | 1566 | Relative paths in a host can be mounted. 1567 | 1568 | ``` 1569 | volumes: 1570 | # Just specify a path and let the Engine create a volume 1571 | - /var/lib/mysql 1572 | 1573 | # Specify an absolute path mapping 1574 | - /opt/data:/var/lib/mysql 1575 | 1576 | # Path on the host, relative to the Compose file 1577 | - ./cache:/tmp/cache 1578 | 1579 | # User-relative path 1580 | - ~/configs:/etc/configs/:ro 1581 | 1582 | # Named volume 1583 | - datavolume:/var/lib/mysql 1584 | ``` 1585 | 1586 | #### Long format 1587 | 1588 | Long formats can be controlled more finely. 1589 | 1590 | - `type`The mount type is`volume`, `bind`, `tmpfs`and`npipe` 1591 | - `source`The source location of the mount. It can be a host path, a volume name defined in top-level volumes, and so on. If mounted`tmpfs`This parameter is meaningless. 1592 | - `target`The mount point path in the container. 1593 | - `read_only`Boolean values to set the writability of volumes. 1594 | - `bind`Configure additional bind options. 1595 | - `propagation`Communication mode for bind. 1596 | - `volume`Configure additional volume options 1597 | - `nocopy`Boolean Quantity to disable data replication (by default, when the volume is first created, the contents of the container will be replicated into the volume) 1598 | - `tmpfs`Configure additional TMPFS options 1599 | - `size`The capacity of tmpfs, in bytes. 1600 | - `consistency`Consistency requirements for mounting:`consistent`Host and container have the same view.`cached`The read operation is buffered and the host view is the main body.`delegated`Read and write operations are buffered and container views are the main body. 1601 | 1602 | ``` 1603 | version: "3.7" 1604 | services: 1605 | web: 1606 | image: nginx:alpine 1607 | ports: 1608 | - "80:80" 1609 | volumes: 1610 | - type: volume 1611 | source: mydata 1612 | target: /data 1613 | volume: 1614 | nocopy: true 1615 | - type: bind 1616 | source: ./static 1617 | target: /opt/app/static 1618 | 1619 | networks: 1620 | webnet: 1621 | 1622 | volumes: 1623 | mydata: 1624 | ``` 1625 | 1626 | > Long formats are available after v3.2 1627 | 1628 | #### VOLUMES FOR SERVICES, SWARMS, AND STACK FILES 1629 | 1630 | When working in services, swarms, or`docker-stack.yml`In this scenario, it is important to note that a service may be deployed to any node in swarm and may no longer be on the original node whenever the service is restarted after being updated. 1631 | 1632 | When a volume with a specified name does not exist, Docker automatically creates an anonymous volume for a reference service. Anonymous volumes are not persistent, so when the associated container instance exits and is removed, the anonymous volumes are destroyed. 1633 | 1634 | If you want to persist your data, use named volumes and choose the appropriate volume driver. This driver should be cross-host so that data can roam between different hosts. Otherwise, you should set constraints on the service so that it can only be deployed to specific nodes where the corresponding volume service is working correctly. 1635 | 1636 | As an example, votingapp sample in Docker Labs`docker-stack.yml`File definition`db`Service, running postgresql. It uses a named volume`db-data`To persist database data, this volume is constrained by swarm to run only in`manager`On this node, so no problem exists. The following is the source code: 1637 | 1638 | ``` 1639 | version: "3.7" 1640 | services: 1641 | db: 1642 | image: postgres:9.4 1643 | volumes: 1644 | - db-data:/var/lib/postgresql/data 1645 | networks: 1646 | - backend 1647 | deploy: 1648 | placement: 1649 | constraints: [node.role == manager] 1650 | ``` 1651 | 1652 | #### CACHING OPTIONS FOR VOLUME MOUNTS (DOCKER DESKTOP FOR MAC) 1653 | 1654 | In Docker 17.04 CE Edge and later versions (even 17.06CE Edge and Stable versions), you can configure consistency constraints on how volumes between containers and hosts are synchronized. These signs include: 1655 | 1656 | - `consistent`It’s exactly the same. Host and container have the same view, which is the default policy. 1657 | - `cached`Host is the best. The read operation of the volume is buffered and the host view is the main body. 1658 | - `delegated`Containers shall prevail. Read and write operations on volumes are buffered, with container views as the main body. 1659 | 1660 | This is designed for Docker Desktop for Mac. Because of what we already know.`osxfx`Regarding the reasons for file sharing characteristics, reasonable setting of consistency flags can improve the performance problems when accessing mounted volumes inside and outside containers. 1661 | 1662 | Here’s one`cached`Examples of volumes: 1663 | 1664 | ``` 1665 | version: "3.7" 1666 | services: 1667 | php: 1668 | image: php:7.1-fpm 1669 | ports: 1670 | - "9000" 1671 | volumes: 1672 | - .:/var/www/project:cached 1673 | ``` 1674 | 1675 | For the case where both read and write operations are buffered, even if any modifications occur in the container (for a typical architecture like PHP Website,. / config. PHP is often written), they will not immediately be reflected in the host, and the writes in the container will be accumulated. 1676 | 1677 | Performance tuning for volume mounts (shared filesystems) should be referred to for consistency issues inside and outside containers. 1678 | 1679 | > I have not been able to translate it as it is, because it will bring a long space, and I have not yet been able to organize the language on this issue. 1680 | 1681 | ### `domainname`, `hostname`, `ipc`, `mac_address`, `privileged`, `read_only`, `shm_size`, `stdin_open`, `tty`, `user`, `working_dir` 1682 | 1683 | These configurations have a single value. and`docker run`The corresponding command line parameters correspond.`mac_address`It has been abandoned. 1684 | 1685 | ``` 1686 | user: postgresql 1687 | working_dir: /code 1688 | 1689 | domainname: foo.com 1690 | hostname: foo 1691 | ipc: host 1692 | mac_address: 02:42:ac:11:65:43 1693 | 1694 | privileged: true 1695 | 1696 | 1697 | read_only: true 1698 | shm_size: 64M 1699 | stdin_open: true 1700 | tty: true 1701 | ``` 1702 | 1703 | ## Specified duration 1704 | 1705 | Some configuration options, such as`interval`perhaps`timeout`(all are`check `Suboption, which accepts a string-style parameter value for a time period or period. They should have such formats: 1706 | 1707 | ``` 1708 | 2.5s 1709 | 10s 1710 | 1m30s 1711 | 2h32m 1712 | 5h34m56s 1713 | ``` 1714 | 1715 | Suffix units that can be added to values are`us`, `ms`, `s`, `m`As well as`h`。 1716 | 1717 | The meaning is self-evident. 1718 | 1719 | ## Specify byte values 1720 | 1721 | Some configuration options, such as`build`Suboptions`shm_size`Accepts a string-separated capacity size parameter value. They should have such formats: 1722 | 1723 | ``` 1724 | 2b 1725 | 1024kb 1726 | 2048k 1727 | 300m 1728 | 1gb 1729 | ``` 1730 | 1731 | Valid suffix units include`b`, `k`, `m`and`g`。 Besides,`kb`, `mb`and`gb`It’s also legal. Pure decimal values are not legal. 1732 | 1733 | ## Volume Format Manual-`volumes` 1734 | 1735 | Top-level volumes chapters can declare and create named volumes (no need to use them)`volume_from`These volumes can be used for reference in the volume section under the service section. So we can reuse them, even across multiple services. The docker volume subcommand of the docker command has more reference information. 1736 | 1737 | For volume usage, you can also refer to Use volumes and Volume Plugins. 1738 | 1739 | Here is an example, which contains two services. The data storage folder of the database is shared between the two services, so the database can use the storage folder, and the backup service can also operate it to complete the backup task: 1740 | 1741 | ``` 1742 | version: "3.7" 1743 | 1744 | services: 1745 | db: 1746 | image: db 1747 | volumes: 1748 | - data-volume:/var/lib/db 1749 | backup: 1750 | image: backup-service 1751 | volumes: 1752 | - data-volume:/var/lib/backup/data 1753 | 1754 | volumes: 1755 | data-volume: 1756 | ``` 1757 | 1758 | top-level`volumes`The entries under the chapters can be empty without specifying details, so that the default volume driver will be applied (usually`local`Volume drive). 1759 | 1760 | But you can also customize it with the following parameters: 1761 | 1762 | ### `driver` 1763 | 1764 | Specify which volume driver will be adopted. Generally speaking, the default value will be`local`。 If the volume driver is invalid or does not work, the`docker-compose up`Docker Engine will return an error. 1765 | 1766 | ``` 1767 | driver: foobar 1768 | ``` 1769 | 1770 | ### `driver_opts` 1771 | 1772 | Optionally specify a set of key-value pair parameters that will be passed to the volume driver. So these parameter sets are related to the volume driver, please refer to the relevant documentation of the volume driver. 1773 | 1774 | ``` 1775 | volumes: 1776 | example: 1777 | driver_opts: 1778 | type: "nfs" 1779 | o: "addr=10.40.0.199,nolock,soft,rw" 1780 | device: ":/docker/example" 1781 | ``` 1782 | 1783 | ### `external` 1784 | 1785 | If set to`true`That means that the corresponding volume is created outside the compose orchestration file. here`docker-compse up`No attempt will be made to create the volume, and an error will be returned if the volume does not yet exist. 1786 | 1787 | For v3.3 and lower compose format versions,`external`Can not be used in combination with other volume configuration parameters, such as`driver`, `driver_opts`, `labels`Wait. But for v3.4 and later versions, there is no longer such restriction. 1788 | 1789 | In the following example, Compose finds a name named`data`External volume and mount it to`db`In the service, instead of trying to create a name`[projectname]_data`New volume. 1790 | 1791 | ``` 1792 | version: "3.7" 1793 | 1794 | services: 1795 | db: 1796 | image: postgres 1797 | volumes: 1798 | - data:/var/lib/postgresql/data 1799 | 1800 | volumes: 1801 | data: 1802 | external: true 1803 | ``` 1804 | 1805 | > `external.name`After v3.4 + has been discarded, it can be used directly.`name`。 1806 | 1807 | You can also specify the volume name separately.`data`The volume alias is considered when the volume is referenced in the current orchestration file: 1808 | 1809 | ``` 1810 | volumes: 1811 | data: 1812 | external: 1813 | name: actual-name-of-volume 1814 | ``` 1815 | 1816 | > **External volumes are always created with docker stack deploy** 1817 | > 1818 | > When deployed to swarm using docker stack deployment, external volumes are always created automatically if they do not exist. For further information, please refer to moby/moby_976, 1819 | 1820 | ### `labels` 1821 | 1822 | Use Docker labels to add metadata to the container. It can be in array format or dictionary format. 1823 | 1824 | We recommend that you use reverse DNS annotation to add reverse domain name prefixes to your metadata table keys to avoid potential conflicts with table keys with the same name as other applications: 1825 | 1826 | ``` 1827 | labels: 1828 | com.example.description: "Database volume" 1829 | com.example.department: "IT/Ops" 1830 | com.example.label-with-empty-value: "" 1831 | labels: 1832 | - "com.example.description=Database volume" 1833 | - "com.example.department=IT/Ops" 1834 | - "com.example.label-with-empty-value" 1835 | ``` 1836 | 1837 | ### `name` 1838 | 1839 | > since v3.4+ 1840 | 1841 | Specify a custom name for the volume. The value of a name can be used to solve volumes with special character names. Note that the value is used as it is, quotation marks will not be ignored, nor will they be prefixed with the name of the upper stack. 1842 | 1843 | ``` 1844 | version: "3.7" 1845 | volumes: 1846 | data: 1847 | name: my-app-data 1848 | ``` 1849 | 1850 | `name`Can be associated with`external`Facies combination: 1851 | 1852 | ``` 1853 | version: "3.7" 1854 | volumes: 1855 | data: 1856 | external: true 1857 | name: my-app-data 1858 | ``` 1859 | 1860 | ## Network Format Manual-`networks` 1861 | 1862 | Top level chapters`networks`This allows you to configure the network you want to create and use (Compose Intranet). 1863 | 1864 | - For a complete description of the features of using Docker network environment in Compose and all network driver options, please refer to the Networking Guide. 1865 | - For Docker Labs’network-related tutorial cases, read Designing Scalable, Portable Docker Container Networks carefully. 1866 | 1867 | ### `driver` 1868 | 1869 | Specify the driver for the network. 1870 | 1871 | The default driver is specified by the Docker Engine startup parameter. Usually, the startup parameters are built-in for use on a single-node host`bridge`Drive, while`swarm mode`Use in`overlay`Drive. 1872 | 1873 | If the driver is not available, Docker Engine will return an error. 1874 | 1875 | ``` 1876 | driver: overlay 1877 | ``` 1878 | 1879 | #### bridge 1880 | 1881 | By default, Docker is used on each host node`bridge`Drive. For information on how bridging networks work, you can refer to Docker Labs’network-related tutorial case: Bridge networking. 1882 | 1883 | #### overlay 1884 | 1885 | `overlay`Driver in multiple`swarm mode`A named subnet is established between nodes, which is a virtual network across hosts. 1886 | 1887 | - stay`swarm mode`How to Establish in China`overlay`In order to make the service work correctly across hosts, please refer to Docker Labs’tutorial case: Overlay networking and service discovery. 1888 | - If you want to go deep into it`overlay`How to build a virtual network across hosts and how to transfer messages can be referred to Overlay Driver Network Architecture. 1889 | 1890 | #### host or none 1891 | 1892 | Use the host network stack or not use the network. 1893 | 1894 | And command line parameters`--net=host`as well as`--net=none`It’s equivalent. 1895 | 1896 | These two drivers and network models can only be used`docker stack`In If you are using it`docker compose`Relevant instructions, please use`network_mode`To specify them. 1897 | 1898 | If you want to use a particular network on a common build, use [network] as mentioned in the second yaml file example. 1899 | 1900 | Use built-in network models, such as`host`and`none`There’s a little grammatical point to pay attention to: if you use`host`or`none`Such names define an external network (note that you don’t really need to create them, both of which belong to Docker’s built-in network model), so you need to use them when referring to them in Compose orchestration files`hostnet`or`nonet`Like this: 1901 | 1902 | ``` 1903 | version: "3.7" 1904 | services: 1905 | web: 1906 | networks: 1907 | hostnet: {} 1908 | 1909 | networks: 1910 | hostnet: 1911 | external: true 1912 | name: host 1913 | 1914 | --- 1915 | services: 1916 | web: 1917 | ... 1918 | build: 1919 | ... 1920 | network: host 1921 | context: . 1922 | ... 1923 | services: 1924 | web: 1925 | ... 1926 | networks: 1927 | nonet: {} 1928 | 1929 | networks: 1930 | nonet: 1931 | external: true 1932 | name: none 1933 | ``` 1934 | 1935 | ### `driver_opts` 1936 | 1937 | Specifies the set of options represented by a set of key-value pairs to be passed to the network driver. They are closely related to drivers, so specific available parameters should refer to the corresponding driver documentation. 1938 | 1939 | ``` 1940 | driver_opts: 1941 | foo: "bar" 1942 | baz: 1 1943 | ``` 1944 | 1945 | ### `attachable` 1946 | 1947 | > since v3.2+ 1948 | 1949 | Can only be used`driver: overlay`Scene. 1950 | 1951 | If set to`true`Independently running containers can also be attached to the network. If a container instance running independently is attached to an overlay network, services in the container can communicate with individual container instances. Note that you can even attach container instances from other Docker daemons to this overlay network. 1952 | 1953 | ``` 1954 | networks: 1955 | mynet1: 1956 | driver: overlay 1957 | attachable: true 1958 | ``` 1959 | 1960 | ### `enable_ipv6` 1961 | 1962 | IPv6 is enabled in this network/subnet. 1963 | 1964 | > Not supported in V3 +. 1965 | > 1966 | > `enable_ipv6`You need to use the V2 format, and it can’t be used in swarm mode. 1967 | 1968 | ### `ipam` 1969 | 1970 | Customize IPAM configuration. Each subconfiguration is an optional parameter. 1971 | 1972 | - `driver`Customize IPAM drivers without using default values 1973 | - `config`A list containing one or more configuration blocks. Each configuration block has the following sub-parameters: 1974 | - `subnet`Subnet definition in CIDR format to delimit a segment. 1975 | 1976 | A complete example: 1977 | 1978 | ``` 1979 | ipam: 1980 | driver: default 1981 | config: 1982 | - subnet: 172.28.0.0/16 1983 | ``` 1984 | 1985 | > **NOTE**Additional IPAM such as`gateway`Only available in v2. 1986 | 1987 | ### `internal` 1988 | 1989 | By default, Docker will also connect to a bridged network to provide external connectivity. If you want to build an external isolated overlay network, set this option to`true`。 1990 | 1991 | ### `labels` 1992 | 1993 | Use Docker labels to add metadata to the container. It can be in array format or dictionary format. 1994 | 1995 | We recommend that you use reverse DNS annotation to add reverse domain name prefixes to your metadata table keys to avoid potential conflicts with table keys with the same name as other applications: 1996 | 1997 | ``` 1998 | labels: 1999 | com.example.description: "Financial transaction network" 2000 | com.example.department: "Finance" 2001 | com.example.label-with-empty-value: "" 2002 | labels: 2003 | - "com.example.description=Financial transaction network" 2004 | - "com.example.department=Finance" 2005 | - "com.example.label-with-empty-value" 2006 | ``` 2007 | 2008 | ### `external` 2009 | 2010 | If set to`true`Then the network is created and managed outside of Compose choreography files. here`dockercompose up`No attempt will be made to create it, and an error will be returned if the network does not exist. 2011 | 2012 | For v3.3 and lower versions,`external`Not to be associated with`driver`, `driver_opts`, `ipam`, `internal`And so on. This restriction was removed after v3.4 +. 2013 | 2014 | In the following example,`proxy`It’s a gateway in the outside world, and Compose will find its way through it.`docker network create outside`Established`outside`External networks, rather than trying to automatically create a name`[projectname]_outside`New networks: 2015 | 2016 | ``` 2017 | version: "3.7" 2018 | 2019 | services: 2020 | proxy: 2021 | build: ./proxy 2022 | networks: 2023 | - outside 2024 | - default 2025 | app: 2026 | build: ./app 2027 | networks: 2028 | - default 2029 | 2030 | networks: 2031 | outside: 2032 | external: true 2033 | ``` 2034 | 2035 | > `external.name`It has been discarded since v3.5. Please use it instead.`name`。 2036 | 2037 | You can also specify a separate network name to be referenced in the Compose orchestration file. 2038 | 2039 | ### `name` 2040 | 2041 | > since v3.5 2042 | 2043 | Set a custom name for the network. The value of a name can be used to solve volumes with special character names. Note that the value is used as it is, quotation marks will not be ignored, nor will they be prefixed with the name of the upper stack. 2044 | 2045 | ``` 2046 | version: "3.7" 2047 | networks: 2048 | network1: 2049 | name: my-app-net 2050 | ``` 2051 | 2052 | `name`Can and`external`Use it together: 2053 | 2054 | ``` 2055 | version: "3.7" 2056 | networks: 2057 | network1: 2058 | external: true 2059 | name: my-app-net 2060 | ``` 2061 | 2062 | ## Configuration Item Arrangement Format Manual-`configs` 2063 | 2064 | Top-level`configs`Chapter Statement defines a configuration item or its reference that can be authorized for use by in-stack services. The source of the configuration item can be`file`or`external`。 2065 | 2066 | - `file`The content of the configuration item is in a host file. 2067 | - `external`If set to`true`Represents that the configuration item is ready to be created. Docker will not attempt to build it, but will generate one when it does not exist.`config not found`Mistake. 2068 | - `name`The name of the configuration item in Docker. The value of a name can be used to solve volumes with special character names. Note that the value is used as it is, quotation marks will not be ignored, nor will they be prefixed with the name of the upper stack. 2069 | 2070 | In the following example, when deployed as part of the stack,`my_first_config`It will be automatically created and named`_my_first_config`As for`my_second_config`It already exists. 2071 | 2072 | ``` 2073 | configs: 2074 | my_first_config: 2075 | file: ./config_data 2076 | my_second_config: 2077 | external: true 2078 | ``` 2079 | 2080 | Another change is that external configuration items have`name`In the case defined, the configuration item can be used in Compose as`redis_config`Reference and use for name: 2081 | 2082 | ``` 2083 | configs: 2084 | my_first_config: 2085 | file: ./config_data 2086 | my_second_config: 2087 | external: 2088 | name: redis_config 2089 | ``` 2090 | 2091 | You still need to declare each service on the stack`configs`Chapter to gain access to configuration items, refer to grant access to the config. 2092 | 2093 | ## Handbook for Formatting Sensitive Information Items-`secrets` 2094 | 2095 | Top-level`secrets`Chapter declaration defines a sensitive information item or its reference, which can be authorized for use by in-stack services. The source of sensitive information items can be`file`or`external`。 2096 | 2097 | - `file`The contents of sensitive information items are in a host file. 2098 | - `external`If set to`true`Indicates that the sensitive information item is ready to be created. Docker will not attempt to build it, but will generate one when it does not exist.`secret not found`Mistake. 2099 | - `name`The name of the sensitive information item in Docker. The value of a name can be used to solve volumes with special character names. Note that the value is used as it is, quotation marks will not be ignored, nor will they be prefixed with the name of the upper stack. 2100 | 2101 | In the following example, when deployed as part of the stack,`my_first_secret`It will be automatically created and named`_my_first_secret`As for`my_second_secret`It already exists. 2102 | 2103 | ``` 2104 | secrets: 2105 | my_first_secret: 2106 | file: ./secret_data 2107 | my_second_secret: 2108 | external: true 2109 | ``` 2110 | 2111 | Another change is that external configuration items have`name`In the case defined, the configuration item can be used in Compose as`redis_secret`Reference and use for name. 2112 | 2113 | #### Compose File v3.5 and later 2114 | 2115 | ``` 2116 | secrets: 2117 | my_first_secret: 2118 | file: ./secret_data 2119 | my_second_secret: 2120 | external: true 2121 | name: redis_secret 2122 | ``` 2123 | 2124 | ### Compose File v3.4 and lower 2125 | 2126 | ``` 2127 | my_second_secret: 2128 | external: 2129 | name: redis_secret 2130 | ``` 2131 | 2132 | You still need to declare each service on the stack`secret`Chapter to gain access to sensitive information items, refer to grant access to the secret. 2133 | 2134 | ## Variable substitution 2135 | 2136 | Environment variables can be used in Compose orchestration files. When`docker-compose`At runtime, Compose extracts variable values from shell environment variables. For example, suppose that the operating system environment variables contain`POSTGRES_VERSION=9.3`Definition, then the following definition 2137 | 2138 | ``` 2139 | db: 2140 | image: "postgres:${POSTGRES_VERSION}" 2141 | ``` 2142 | 2143 | Equivalent to 2144 | 2145 | ``` 2146 | db: 2147 | image: "postgres:9.3" 2148 | ``` 2149 | 2150 | If the environment variable does not exist or is an empty string, it is treated as an empty string. 2151 | 2152 | You can go through it.`.env`The file sets default values for environment variables. Compose will automatically find the current folder`.env`File to get the value of the environment variable. 2153 | 2154 | > **IMPORTANT**Attention`.env`File only`docker-compose up`It works in the scenario, but it works in the scenario.`docker stack deploy`It will not be used. 2155 | 2156 | Two kinds of grammar`$VARIABLE`and`${VARIABLE}`All are available. In addition, in v2.1 format, the following forms similar to shell grammar can also be used: 2157 | 2158 | - `${VARIABLE:-default}`Will return`default`If the environment variable`VARIABLE`If it is an empty string or not set. 2159 | - `${VARIABLE-default}`Will return`default`If the environment variable`VARIABLE`If not set. 2160 | 2161 | Similarly, the following syntax helps to specify a clear value: 2162 | 2163 | - `${VARIABLE:?err}`Error messages will be generated`err`If the environment variable`VARIABLE`If it is empty or not set. 2164 | - `${VARIABLE?err}`Error messages will be generated`err`If the environment variable`VARIABLE`If not set. 2165 | 2166 | Other shell syntax features are not supported, such as`${VARIABLE/foo/bar}`。 2167 | 2168 | If you need a dollar sign, use`$`. At this time, $$`No longer participate in the interpretation of environmental variable substitution. The following example: 2169 | 2170 | ``` 2171 | web: 2172 | build: . 2173 | command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE" 2174 | ``` 2175 | 2176 | If you forget this rule and use one`$`Compose warns you if it’s a single character: 2177 | 2178 | ``` 2179 | The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string. 2180 | ``` 2181 | 2182 | ## Extended field 2183 | 2184 | > since v3.4 2185 | 2186 | By extending fields, you can reuse the orchestration configuration fragments. They can be in a free format, provided you define them at the top level of the yaml document, and the chapter names are as follows`x-`Start: 2187 | 2188 | ``` 2189 | version: '3.4' 2190 | x-custom: 2191 | items: 2192 | - a 2193 | - b 2194 | options: 2195 | max-size: '12m' 2196 | name: "custom" 2197 | ``` 2198 | 2199 | > **NOTE** 2200 | > 2201 | > Starting with V3.7 (for 3.x series), or starting with V2.4 (for 2.x series), extended fields can also be placed at the first level under the top chapters of services, volumes, networks, configuration items, and sensitive information items. 2202 | > 2203 | > As such: 2204 | > 2205 | > ``` 2206 | > version: '3.7' 2207 | > services: 2208 | > redis: 2209 | > # ... 2210 | > x-custom: 2211 | > items: 2212 | > - a 2213 | > - b 2214 | > options: 2215 | > max-size: '12m' 2216 | > name: "custom" 2217 | > ``` 2218 | 2219 | The so-called free format means that these definitions are not interpreted by Compose. However, when you insert their references somewhere, they are expanded to the insertion point and then interpreted by Compose in terms of context. This uses the YAML anchors grammar. 2220 | 2221 | For example, if you use the same logging option for multiple services: 2222 | 2223 | ``` 2224 | logging: 2225 | options: 2226 | max-size: '12m' 2227 | max-file: '5' 2228 | driver: json-file 2229 | ``` 2230 | 2231 | You can define it as follows: 2232 | 2233 | ``` 2234 | x-logging: 2235 | &default-logging 2236 | options: 2237 | max-size: '12m' 2238 | max-file: '5' 2239 | driver: json-file 2240 | 2241 | services: 2242 | web: 2243 | image: myapp/web:latest 2244 | logging: *default-logging 2245 | db: 2246 | image: mysql:latest 2247 | logging: *default-logging 2248 | ``` 2249 | 2250 | With the YAML merge type grammar, you can also insert extended field definitions that override certain sub-options. For example: 2251 | 2252 | ``` 2253 | version: '3.4' 2254 | x-volumes: 2255 | &default-volume 2256 | driver: foobar-storage 2257 | 2258 | services: 2259 | web: 2260 | image: myapp/web:latest 2261 | volumes: ["vol1", "vol2", "vol3"] 2262 | volumes: 2263 | vol1: *default-volume 2264 | vol2: 2265 | << : *default-volume 2266 | name: volume02 2267 | vol3: 2268 | << : *default-volume 2269 | driver: default 2270 | name: volume-local 2271 | ``` 2272 | 2273 | ## Compose Document Reference 2274 | 2275 | - User guide 2276 | - Installing Compose 2277 | - Compose file versions and upgrading 2278 | - Get started with Docker 2279 | - Samples 2280 | - Command line reference 2281 | 2282 | ## End 2283 | 2284 | - Original: https://docs.docker.com/compo… 2285 | - Https://github.com/hedzr/docker-compose-file-format. 2286 | 2287 | --------------------------------------------------------------------------------