[Docker] Compose file version 3 reference

Chúng ta cùng xem các tham số cấu hình trong docker compose nhé.

Reference and guidelines

Compose file hiện đang có 3 version khi format. Phiên bản mới nhất tính đến ngày 30/4/2020 là 3.8

Ma trận tương thích Compose và Docker

Có 1 vài version của Composer file format - 1,2,2.x và 3.x. Bảng dưới đây sẽ chỉ ra sự tương thích version Docker và Compose, nếu bạn dùng phiên bản Docker đã quá cũ nhưng muốn dùng file format cho Compose phiên bản mới, hãy nâng cấp Docker

Compose file format	Docker Engine release
3.8	19.03.0+
3.7	18.06.0+
3.6	18.02.0+
3.5	17.12.0+
3.4	17.09.0+
3.3	17.06.0+
3.2	17.04.0+
3.1	1.13.1+
3.0	1.13.0+
2.4	17.12.0+
2.3	17.06.0+
2.2	1.13.0+
2.1	1.12.0+
2.0	1.10.0+
1.0	1.9.1.+

Compose file structure and examples

Đây là 1 ví dụ về Composer file format

Example Compose file version 3

version: "3.8"
services:

  redis:
    image: redis:alpine
    ports:
      - "6379"
    networks:
      - frontend
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

  db:
    image: postgres:9.4
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend
    deploy:
      placement:
        constraints:
          - "node.role==manager"

  vote:
    image: dockersamples/examplevotingapp_vote:before
    ports:
      - "5000:80"
    networks:
      - frontend
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
      restart_policy:
        condition: on-failure

  result:
    image: dockersamples/examplevotingapp_result:before
    ports:
      - "5001:80"
    networks:
      - backend
    depends_on:
      - db
    deploy:
      replicas: 1
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 1
      labels: [APP=VOTING]
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 3
        window: 120s
      placement:
        constraints:
          - "node.role==manager"

  visualizer:
    image: dockersamples/visualizer:stable
    ports:
      - "8080:8080"
    stop_grace_period: 1m30s
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
    deploy:
      placement:
        constraints:
          - "node.role==manager"

networks:
  frontend:
  backend:

volumes:
  db-data:

Service configuration reference

Compose file định nghĩa services, networks và volumes. Bạn có thể sử dụng cả phần mở rộng .yml hoặc .yaml đều được

Mỗi service được định nghĩa chứa 1 cấu hình được áp dụng cho từng container trong service, giống như truyền tham số tới lệnh docker run. Tương tự, các định nghĩa volume và network tương tự như các lệnh docker network create và docker volume create.

Cũng như với docker run, các tùy chọn được xác định trong Dockerfile, như CMD, EXPOSE, VOLUME, ENV được sử dụng mặc định - bạn không cần truyền chúng lại trong file docker-compose.yml.

Phần tiếp theo sẽ trình bày tất cả các cấu hình được hỗ trợ trong version 3.

build:

• Các tùy chọn cấu hình được áp dụng khi build

• context: Đường dẫn thư mục chứa 1 Dockerfile hoặc url tới git repository

• dockerfile: Thay đổi Dockerfile
• args: Thêm các đối số khi build cái mà được biến môi trường có thể truy cập chỉ trong quá trình build

Đầu tiên, xác định các đối số của bạn trong Dockerfile

ARG buildno
ARG gitcommithash

RUN echo "Build number: $buildno"
RUN echo "Based on commit: $gitcommithash"

Chỉ định các đối số này dưới từ khóa build. Bạn có thể map hoặc sử dụng list

build:
  context: .
  args:
    buildno: 1
    gitcommithash: cdc3b19

Or

build:
  context: .
  args:
    - buildno=1
    - gitcommithash=cdc3b19

Scope of build-args

In your Dockerfile, if you specify ARG before the FROM instruction, ARG is not available in the build instructions under FROM. If you need an argument to be available in both places, also specify it under the FROM instruction. Refer to the understand how ARGS and FROM interact section in the documentation for usage details.

Bạn cũng có thể bỏ qua các giá trị này khi build, trong trường hợp đó, giá trị của nó sẽ là trong môi trường nơi mà Compose đang chạy.

args:
  - buildno
  - gitcommithash

• cache_from
  Mới được thêm từ version 3.2
  Danh sách images có thể sử dụng cache

  build:
    context: .
    cache_from:
      - alpine:latest
      - corp/web_app:3.14

• label
  Mới được thêm từ version 3.3
  Thêm metdata vào kết quả image sử dụng Docker label
  Nó khuyên bạn nên sử dụng ký hiệu DNS ngược để ngăn label của bạn xung đột với các nhãn được sử dụng bởi phần mềm khác.

• shm-size
• target

cap_add, cap_drop

cgroup_parent

command

Ghi đè command mặc định

command: bundle exec thin -p 3000

Command cũng có thể là 1 danh sách, tương tự như dockerfile

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

configs

container_name

Định nghĩa 1 custom container name thay vì sinh ra mặc định

credential_spec

Được thêm từ phiên bản 3.3. Chỉ được sử dụng trên windows quản lý tài khoản group Managed Service Account (gMSA)

depends_on

Mô tả sự phụ thuộc giữa các service. Sự phụ thuộc các dịch vụ gây ra các hành vi sau:

• docker-compose up: start service theo thứ tự sự phụ thuộc. Như ví dụ dưới, db và redis được start trước web
• docker-compose up SERVICE: tự động bao gồm các SERVICE phụ thuộc. Như ví dụ dưới, docker-compose up web cũng sẽ tạo và start db và redis
• docker-compose stop: stop service theo thứ tự sự phụ thuộc. Như ví dụ dưới đây, web sẽ bị stop trước db và redis

  version: "3.7"
  services:
    web:
      build: .
      depends_on:
        - db
        - redis
    redis:
      image: redis
    db:
      image: postgres

There are several things to be aware of when using depends_on:

depends_on does not wait for db and redis to be “ready” before starting web - only until they have been started. If you need to wait for a service to be ready, see Controlling startup order for more on this problem and strategies for solving it.
Version 3 no longer supports the condition form of depends_on.
The depends_on option is ignored when deploying a stack in swarm mode with a version 3 Compose file.

deploy

Các cấu hình để cho quá trình deploy và chạy các services. Nó chỉ ảnh hưởng khi deploying tới 1 swarm với docker stack deploy và nó bị bỏ qua bởi docker-compose up và docker-compose run
(Chính vì bỏ qua nên khi nào cần sẽ đọc lại)

devices

List of device mappings. Uses the same format as the –device docker client create option.

dns

dns_search

entrypoint

Ghi đè entrypoint mặc định

entrypoint: /code/entrypoint.sh

entrypoint cũng có thể là 1 danh sách, tương tự dockerfile

entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]

env_file

Thêm biến môi trường từ 1 file. Bạn có thể sử dụng giá trị đơn hoặc 1 danh sách

env_file: .env

Hoặc

env_file:
  - ./common.env
  - ./apps/web.env
  - /opt/runtime_opts.env

Và cấu trúc file .env sẽ như sau:

# Set Rails/Rack environment
RACK_ENV=development

environment

Thêm biến môi trường. Cái trên là thêm dựa vào file nhé :D

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

Hoặc

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

expose

Expose ra cổng mà không truy xuất được xử host machine, chúng sẽ chỉ có thể truy cập được sử các link services. Chỉ coongt nội bộ có thể được chỉ định

expose:
  - "3000"
  - "8000"

Ý kiến cá nhân: Docker-compose đã tự expose các cổng của các container, vì vậy tham số này bỏ đi thì cũng không ảnh hưởng lắm. Tuy nhiên bạn cũng nên có tham số này trong docker-compose.yml file để:

• Chú thích cho người đọc dễ hiểu các cổng expose mặc định
• Không expose ra host machine
• Expose các cổng custome, vẫn được (KHÔNG KHUYẾN KHÍCH_, ví dụ mysql:5.7 có thể expose cổng 3307

external_links

extra_hosts

healthcheck

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s

image

Xác định image để bắt đầu container. Bạn có thể sử dụng cả dạng repository/tag hoặc một phần của image ID

init

isolation

labels

links

Warning

The –link flag is a legacy feature of Docker. It may eventually be removed. Unless you absolutely need to continue using it, we recommend that you use user-defined networks to facilitate communication between two containers instead of using –link.

One feature that user-defined networks do not support that you can do with –link is sharing environmental variables between containers. However, you can use other mechanisms such as volumes to share environment variables between containers in a more controlled way.

Liên kết các containers khác service. Nó có thể sử dụng qua service name và link alias (“SERVICE:ALIAS”), hoặc chỉ tên service

web:
  links:
    - "db"
    - "db:database"
    - "redis"

Các containers đối với các service đã được liên kết có thể truy caaoj tới hostname được chỉ định alias hoặc tới service name nếu không có alias nào được chỉ định

Links không bắt buộc để cho phép các dịch vụ giao tiếp - mặc định, 1 vài dịch vụ có thể kết nối với các dịch vụ khác qua tên của service. Xem thêm tại https://docs.docker.com/compose/networking/#links

Links cũng mô tả sự phụ thuộc giữa các service giống như depends_on, bởi vậy chúng xác định thứ tự startup của các service

Warning: Note when using docker stack deploy

The links option is ignored when deploying a stack in swarm mode

logging

Cấu hình phần log cho service

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

network_mode

network

pid

ports

Expose ports

SHORT SYNTAX

Bạn có thể chỉ định cả 2 ports (HOST:CONTAINER) hoặc chỉ container port (một cổng random, không ổn định trên host sẽ được chọn)

ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "6060:6060/udp"
  - "12400-12500:1240"

LONG SYNTAX

Cú pháp này mới được thêm từ phiên bản 3.2
Nó sẽ thêm các trường, cho phép thêm thông tin về các cấu hình

• target: the port inside the container
• published: the publicly exposed port
• protocol: the port protocol (tcp or udp)
• mode: host for publishing a host port on each node, or ingress for a swarm mode port to be load balanced.

  ports:
    - target: 80
      published: 8080
      protocol: tcp
      mode: host

restart

no là chính sách restart mặc định và nó sẽ không restart 1 container trong 1 vài hoàn cảnh. Khi always, container luôn luôn restarts. on-failure sẽ restarts 1 container nếu exit code với 1 lỗi nào đó

restart: "no"
restart: always
restart: on-failure
restart: unless-stopped

(warning) Note when using docker stack deploy

The restart option is ignored when deploying a stack in swarm mode.

secret

security_opt

stop_grace_period

stop_signal

sysctls

tmpfs

ulimits

userns_mode

volumes