docker_practice/compose/yaml_file.md

516 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

## Compose 模板文件
模板文件是使用 `Compose` 的核心,涉及到的指令关键字也比较多。但大家不用担心,这里面大部分指令跟 `docker run` 相关参数的含义都是类似的。
默认的模板文件名称为 `docker-compose.yml`,格式为 YAML 格式。
```yaml
version: "3"
services:
webapp:
image: examples/web
ports:
- "80:80"
volumes:
- "/data"
```
注意每个服务都必须通过 `image` 指令指定镜像或 `build` 指令(需要 Dockerfile等来自动构建生成镜像。
如果使用 `build` 指令,在 `Dockerfile` 中设置的选项(例如:`CMD`, `EXPOSE`, `VOLUME`, `ENV` 等) 将会自动被获取,无需在 `docker-compose.yml` 中再次设置。
下面分别介绍各个指令的用法。
### `build`
指定 `Dockerfile` 所在文件夹的路径(可以是绝对路径,或者相对 docker-compose.yml 文件的路径)。 `Compose` 将会利用它自动构建这个镜像,然后使用这个镜像。
```yaml
build: /path/to/build/dir
```
### `cap_add, cap_drop`
指定容器的内核能力capacity分配。
例如,让容器拥有所有能力可以指定为:
```yaml
cap_add:
- ALL
```
去掉 NET_ADMIN 能力可以指定为:
```yaml
cap_drop:
- NET_ADMIN
```
### `command`
覆盖容器启动后默认执行的命令。
```yaml
command: echo "hello world"
```
### `configs`
仅用于 `Swarm mode`,详细内容请查看 [`Swarm mode`](../swarm_mode/) 一节。
### `cgroup_parent`
指定父 `cgroup` 组,意味着将继承该组的资源限制。
例如,创建了一个 cgroup 组名称为 `cgroups_1`
```yaml
cgroup_parent: cgroups_1
```
### `container_name`
指定容器名称。默认将会使用 `项目名称_服务名称_序号` 这样的格式。
```yaml
container_name: docker-web-container
```
需要注意指定容器名称后该服务将无法进行扩展scale因为 Docker 不允许多个容器具有相同的名称。
### `deploy`
仅用于 `Swarm mode`,详细内容请查看 [`Swarm mode`](../swarm_mode/) 一节
### `devices`
指定设备映射关系。
```yaml
devices:
- "/dev/ttyUSB1:/dev/ttyUSB0"
```
### `depends_on`
解决容器的依赖、启动先后的问题。以下例子中会先启动 `redis` `db` 再启动 `web`
```yaml
version: '3'
services:
web:
build: .
depends_on:
- db
- redis
redis:
image: redis
db:
image: postgres
```
### `dns`
自定义 `DNS` 服务器。可以是一个值,也可以是一个列表。
```yaml
dns: 8.8.8.8
dns:
- 8.8.8.8
- 114.114.114.114
```
### `dns_search`
配置 `DNS` 搜索域。可以是一个值,也可以是一个列表。
```yaml
dns_search: example.com
dns_search:
- domain1.example.com
- domain2.example.com
```
### `tmpfs`
挂载一个 tmpfs 文件系统到容器。
```yaml
tmpfs: /run
tmpfs:
- /run
- /tmp
```
### `env_file`
从文件中获取环境变量,可以为单独的文件路径或列表。
如果通过 `docker-compose -f FILE` 方式来指定 Compose 模板文件,则 `env_file` 中变量的路径会基于模板文件路径。
如果有变量名称与 `environment` 指令冲突,则按照惯例,以后者为准。
```bash
env_file: .env
env_file:
- ./common.env
- ./apps/web.env
- /opt/secrets.env
```
环境变量文件中每一行必须符合格式,支持 `#` 开头的注释行。
```bash
# common.env: Set development environment
PROG_ENV=development
```
### `environment`
设置环境变量。你可以使用数组或字典两种格式。
只给定名称的变量会自动获取运行 Compose 主机上对应变量的值,可以用来防止泄露不必要的数据。
```yaml
environment:
RACK_ENV: development
SESSION_SECRET:
environment:
- RACK_ENV=development
- SESSION_SECRET
```
注意,如果变量名称或者值中用到 `true|falseyes|no` 等表达布尔含义的词汇,最好放到引号里,避免 YAML 自动解析某些内容为对应的布尔语义。
`http://yaml.org/type/bool.html` 中给出了这些特定词汇,包括
```bash
y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF
```
### `expose`
暴露端口,但不映射到宿主机,只被连接的服务访问。
仅可以指定内部端口为参数
```yaml
expose:
- "3000"
- "8000"
```
### `external_links`
链接到 docker-compose.yml 外部的容器,甚至并非 `Compose` 管理的外部容器。参数格式跟 `links` 类似。
```yaml
external_links:
- redis_1
- project_db_1:mysql
- project_db_1:postgresql
```
### `extra_hosts`
类似 Docker 中的 `--add-host` 参数,指定额外的 host 名称映射信息。
```yaml
extra_hosts:
- "googledns:8.8.8.8"
- "dockerhub:52.1.157.61"
```
会在启动后的服务容器中 `/etc/hosts` 文件中添加如下两条条目。
```bash
8.8.8.8 googledns
52.1.157.61 dockerhub
```
### `healthcheck`
通过命令检查容器是否健康运行。
```yaml
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 1m30s
timeout: 10s
retries: 3
```
### `image`
指定为镜像名称或镜像 ID。如果镜像在本地不存在`Compose` 将会尝试拉去这个镜像。
```yaml
image: ubuntu
image: orchardup/postgresql
image: a4bc65fd
```
### `labels`
为容器添加 Docker 元数据metadata信息。例如可以为容器添加辅助说明信息。
```yaml
labels:
com.startupteam.description: "webapp for a startup team"
com.startupteam.department: "devops department"
com.startupteam.release: "rc3 for v1.0"
```
### `links`
链接到其它服务中的容器。使用服务名称(同时作为别名)或服务名称:服务别名 `SERVICE:ALIAS` 格式都可以。
```bash
links:
- db
- db:database
- redis
```
使用的别名将会自动在服务容器中的 `/etc/hosts` 里创建。例如:
```bash
172.17.2.186 db
172.17.2.186 database
172.17.2.187 redis
```
被链接容器中相应的环境变量也将被创建。
### `logging`
配置日志选项。
```yaml
logging:
driver: syslog
options:
syslog-address: "tcp://192.168.0.42:123"
```
目前支持三种日志驱动类型。
```yaml
driver: "json-file"
driver: "syslog"
driver: "none"
```
`options` 配置日志驱动的相关参数。
```yaml
options:
max-size: "200k"
max-file: "10"
```
### `network_mode`
设置网络模式。使用和 `docker run``--net` 参数一样的值。
```yaml
network_mode: "bridge"
network_mode: "host"
network_mode: "none"
network_mode: "service:[service name]"
network_mode: "container:[container name/id]"
```
### `networks`
配置容器连接的网络。
```yaml
version: "3"
services:
some-service:
networks:
- some-network
- other-network
networks:
some-network:
other-network:
```
### `pid`
跟主机系统共享进程命名空间。打开该选项的容器之间,以及容器和宿主机系统之间可以通过进程 ID 来相互访问和操作。
```yaml
pid: "host"
```
### `ports`
暴露端口信息。
使用宿主:容器 `HOST:CONTAINER`格式,或者仅仅指定容器的端口(宿主将会随机选择端口)都可以。
```yaml
ports:
- "3000"
- "8000:8000"
- "49100:22"
- "127.0.0.1:8001:8001"
```
*注意:当使用 `HOST:CONTAINER` 格式来映射端口时,如果你使用的容器端口小于 60 并且没放到引号里,可能会得到错误结果,因为 `YAML` 会自动解析 `xx:yy` 这种数字格式为 60 进制。为避免出现这种问题,建议数字串都采用引号包括起来的字符串格式。*
### `secrets`
仅用于 `Swarm mode`,详细内容请查看 [`Swarm mode`](../swarm_mode/) 一节。
### `security_opt`
指定容器模板标签label机制的默认属性用户、角色、类型、级别等。例如配置标签的用户名和角色名。
```yaml
security_opt:
- label:user:USER
- label:role:ROLE
```
### `stop_signal`
设置另一个信号来停止容器。在默认情况下使用的是 SIGTERM 停止容器。
```yaml
stop_signal: SIGUSR1
```
### `sysctls`
配置容器内核参数。
```yaml
sysctls:
net.core.somaxconn: 1024
net.ipv4.tcp_syncookies: 0
sysctls:
- net.core.somaxconn=1024
- net.ipv4.tcp_syncookies=0
```
### `ulimits`
指定容器的 ulimits 限制值。
例如,指定最大进程数为 65535指定文件句柄数为 20000软限制应用可以随时修改不能超过硬限制 和 40000系统硬限制只能 root 用户提高)。
```yaml
ulimits:
nproc: 65535
nofile:
soft: 20000
hard: 40000
```
### `volumes`
数据卷所挂载路径设置。可以设置宿主机路径 `HOST:CONTAINER` 或加上访问模式 `HOST:CONTAINER:ro`)。
该指令中路径支持相对路径。
```yaml
volumes:
- /var/lib/mysql
- cache/:/tmp/cache
- ~/configs:/etc/configs/:ro
```
### 其它指令
此外,还有包括 `domainname, entrypoint, hostname, ipc, mac_address, privileged, read_only, shm_size, restart, stdin_open, tty, user, working_dir` 等指令,基本跟 `docker run` 中对应参数的功能一致。
指定服务容器启动后执行的入口文件。
```yaml
entrypoint: /code/entrypoint.sh
```
指定容器中运行应用的用户名。
```yaml
user: nginx
```
指定容器中工作目录。
```yaml
working_dir: /code
```
指定容器中搜索域名、主机名、mac 地址等。
```yaml
domainname: your_website.com
hostname: test
mac_address: 08-00-27-00-0C-0A
```
指定容器中
```yaml
ipc: host
```
允许容器中运行一些特权命令。
```yaml
privileged: true
```
指定容器退出后的重启策略为始终重启。该命令对保持服务始终运行十分有效,在生产环境中推荐配置为 `always` 或者 `unless-stopped`
```yaml
restart: always
```
以只读模式挂载容器的 root 文件系统,意味着不能对容器内容进行修改。
```yaml
read_only: true
```
打开标准输入,可以接受外部输入。
```yaml
stdin_open: true
```
模拟一个假的远程控制台。
```yaml
tty: true
```
### 读取环境变量
Compose 模板文件支持动态读取主机的系统环境变量。
例如,下面的 Compose 文件将从运行它的环境中读取变量 ${MONGO_VERSION} 的值,并写入执行的指令中。
```yaml
db:
image: "mongo:${MONGO_VERSION}"
```
如果执行 `MONGO_VERSION=3.2 docker-compose up` 则会启动一个 `mongo:3.2` 镜像的容器;如果执行 `MONGO_VERSION=2.8 docker-compose up` 则会启动一个 `mongo:2.8` 镜像的容器。