├── 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 |
--------------------------------------------------------------------------------