Справочник по Compose-файлу версии 2

Справочные материалы и рекомендации

В данных разделах описывается версия 2 формата файла Compose.

Матрица совместимости Compose и Docker

Существует несколько версий формата файла Compose — 1, 2, 2.x и 3.x. В таблице далее приведён краткий обзор. Для получения полной информации о том, что включает каждая версия и как обновить, см. О версиях и обновлении.

В этой таблице показано, какие версии файлов Compose поддерживают определённые релизы Docker.

Формат файла Compose

Релиз Docker Engine

Спецификация Compose

19.03.0+

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+

В дополнение к версиям форматов файлов Compose, показанным в таблице, сам Compose находится в расписании релизов, как показано в Создании релизов, но версии форматов файлов не обязательно увеличиваются с каждым выпуском. Например, формат файла Compose 3.0 был впервые представлен в выпуске Compose 1.10.0, и в последующих выпусках его версии постепенно изменялись.

Последний формат файла Compose определяется спецификацией Compose и реализуется Docker Compose 1.27.0+.

Справочник по конфигурации службы

Файл Compose — это файл YAML, определяющий сервисы (services), сети (networks) и тома (volumes). Путь по умолчанию для файла Compose — ./docker-compose.yml.

Примечание

Для этого файла можно использовать расширение .yml или .yaml. Они оба работают.

Определение службы содержит конфигурацию, которая применяется к каждому контейнеру, запущенному для этой службы, подобно передаче параметров командной строки в docker run. Точно так же определения сети и тома аналогичны docker network create и docker volume create.

Как и в случае с docker run, параметры, указанные в Dockerfile, такие как CMD, EXPOSE, VOLUME, ENV, учитываются по умолчанию — вам не нужно указывать их снова в docker-compose.yml.

Вы можете использовать переменные окружения в значениях конфигурации с помощью синтаксиса ${VARIABLE}, подобного синтаксису Bash - более подробную информацию смотрите в разделе Подстановка переменных.

Данный раздел содержит список всех параметров конфигурации, поддерживаемых определением службы в версии 2.

blkio_config

Множество параметров конфигурации для установки ограничений блока ввода-вывода для этой службы.

version: "{{ site.compose_file_v2 }}"
services:
  foo:
    image: busybox
    blkio_config:
      weight: 300
      weight_device:
        - path: /dev/sda
          weight: 400
      device_read_bps:
        - path: /dev/sdb
          rate: '12mb'
      device_read_iops:
        - path: /dev/sdb
          rate: 120
      device_write_bps:
        - path: /dev/sdb
          rate: '1024k'
      device_write_iops:
        - path: /dev/sdb
          rate: 30

device_read_bps, device_write_bps

Устанавливает ограничение в байтах в секунду для операций чтения/записи на данном устройстве. Каждый элемент в списке должен иметь два ключа:

  • path, определяющий символический путь к затронутому устройству

  • rate либо в виде целого числа, представляющего количество байтов, либо в виде строки, выражающей значение байта.

device_read_iops, device_write_iops

Устанавливает лимит операций в секунду для операций чтения/записи на данном устройстве. Каждый элемент в списке должен иметь два ключа:

  • path, определяющий символический путь к затронутому устройству

  • rate, как целочисленное значение, представляющее разрешенное количество операций в секунду.

weight

Изменяет пропорцию пропускной способности, выделенной для этой службы, по сравнению с другими службами. Принимает целое число от 10 до 1000, по умолчанию 500.

weight_device

Точная настройка распределения полосы пропускания по устройствам. Каждый элемент в списке должен иметь два ключа:

  • path, определяющий символический путь к затронутому устройству

  • weight, целое число от 10 до 1000

build

Параметры конфигурации, которые применяются во время сборки.

build можно указывает как строку, содержащую путь к контексту сборки:

version: "{{ site.compose_file_v2 }}"
services:
  webapp:
    build: ./dir

Или как объект с путём, указанным в контекст и, возможно, Dockerfile и аргументы:

version: "{{ site.compose_file_v2 }}"
services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1

Если вы укажете image, а также build, то Compose назовет построенный образ с webapp и необязательным tag, указанным в image:

build: ./dir
image: webapp:tag

В результате получается образ с именем webapp и тегом tag, построенное из ./dir.

context

Добавлено в формате файла версия 2.0.

Либо путь к каталогу, содержащему Dockerfile, либо URL-адрес репозитория git.

Когда предоставленное значение является относительным путём, оно интерпретируется как относительное расположение файла Compose. Данный каталог также является контекстом сборки, который отправляется демону Docker.

Compose создаёт и помечает его сгенерированным именем, а затем использует это образ.

build:
  context: ./dir

dockerfile

Альтернативный Dockerfile.

Compose использует альтернативный файл для сборки. Также необходимо указывает путь сборки.

build:
  context: .
  dockerfile: Dockerfile-alternate

args

Добавлено в формате файла версия 2.0.

Добавляет аргументы сборки, которые являются переменными среды, доступными только во время процесса сборки.

Сначала указывает аргументы в вашем Dockerfile:

# syntax=docker/dockerfile:1

ARG buildno
ARG gitcommithash

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

Затем указывает аргументы под ключом build. Вы можете передать сопоставление или список:

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

Примечание

Объём аргументов сборки

В вашем Dockerfile, если вы укажете ARG перед инструкцией FROM, ARG недоступен в инструкциях по сборке под FROM. Если вам нужно, чтобы аргумент был доступен в обоих местах, также указывает его в инструкции FROM. Обратитесь к разделу понять, как взаимодействуют ARGS и FROM в документации для получения подробной информации об использовании.

Вы можете пропустить значение при указании аргумента сборки, и в этом случае его значение во время сборки будет значением в среде, в которой работает Compose.

args:
  - buildno
  - gitcommithash

Примечание

Совет при использовании логических значений

Логические значения YAML ("истина", "ложь", "yes", "no", "on", "off") должны быть заключены в кавычки, чтобы парсер интерпретировал их как строки.

cache_from

Добавлено в формате файла версия 2.2

Список образов, которые движок использует для разрешения кеша.

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

extra_hosts

Добавляет сопоставления имён хостов во время сборки. Используйте те же значения, что и для параметра клиента Docker --add-host.

extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"

Запись с IP-адресом и именем хоста создаётся в /etc/hosts внутри контейнеров для этой сборки, например:

162.242.195.82  somehost
50.31.209.229   otherhost

isolation

Примечание

Добавлено в формате файла версия 2.1.

Указывает технологию изоляции контейнера сборки. В Linux поддерживается только значение default. В Windows допустимы значения default, process и hyperv. Подробности см. в Docker Engine docs.

Если не указано, Compose будет использовать значение isolation, найденное в определении службы, чтобы определить значение, используемое для сборок.

labels

Добавлено в формате файла версия 2.1

Добавляет метаданные к полученному образу с помощью Докерлейблы. Вы можете использовать либо массив, либо словарь.

Рекомендуется использовать обратную DNS-нотацию, чтобы ваши метки не конфликтовали с метками, используемыми другим программным обеспечением.

build:
  context: .
  labels:
    com.example.description: "Accounting webapp"
    com.example.department: "Finance"
    com.example.label-with-empty-value: ""
build:
  context: .
  labels:
    - "com.example.description=Accounting webapp"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"

network

Добавлено в формате файла версия 2.2

Задаёт сетевые контейнеры, к которым подключаются инструкции RUN во время сборки.

build:
  context: .
  network: host
build:
  context: .
  network: custom_network_1

Используйте none, чтобы отключить сеть во время сборки:

build:
  context: .
  network: none

shm_size

Добавлено в формате файла версия 2.3

Устанавливает размер раздела /dev/shm для контейнеров этой сборки. Указывает как целочисленное значение, представляющее количество байтов, или как строку, выражающую значение байта.

build:
  context: .
  shm_size: '2gb'
build:
  context: .
  shm_size: 10000000

target

Добавлено в формате файла версия 2.3

Создаёт указанный этап, как определено в файле Dockerfile. Подробнее см. документы многоэтапной сборки.

build:
  context: .
  target: prod

cap_add, cap_drop

Добавляет или удаляет возможности контейнера. Полный список см. в man 7 capabilities.

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup_parent

Указывает необязательную родительскую контрольную группу для контейнера.

cgroup_parent: m-executor-abcd

command

Переопределить команду по умолчанию.

command: bundle exec thin -p 3000

Команда также может быть списком, аналогично докерфайл:

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

container_name

Указывает собственное имя контейнера, а не сгенерированное имя по умолчанию.

container_name: my-web-container

Поскольку имена контейнеров Docker должны быть уникальными, вы не можете масштабировать службу за пределы одного контейнера, если вы указали пользовательское имя. Попытка сделать это приводит к ошибке.

cpu_rt_runtime, cpu_rt_period

Добавлено в формате файла версия 2.2

Настраивает параметры выделения ЦП с помощью планировщика реального времени демона Docker.

cpu_rt_runtime: '400ms'
cpu_rt_period: '1400us'

Целочисленные значения будут использовать микросекунды в качестве единиц измерения:

cpu_rt_runtime: 95000
cpu_rt_period: 11000

device_cgroup_rules

Добавлено в формате файла версия 2.3.

Добавляет правила в список разрешенных устройств cgroup.

device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'

devices

Список сопоставлений устройств. Использует тот же формат, что и параметр создания док-клиента --device.

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"

depends_on

Добавлено в формате файла версия 2.0.

Экспресс-зависимость между сервисами. Зависимости службы вызывают следующее поведение:

  • docker-compose up запускает службы в порядке зависимости. В следующем примере db и redis запускаются до web.

  • docker-compose up SERVICE автоматически включает зависимости SERVICE. В приведённом далее примере docker-compose up web также создаёт и запускает db и redis.

  • docker-compose stop останавливает службы в порядке зависимости. В следующем примере web останавливается перед db и redis.

Простой пример:

version: "{{ site.compose_file_v2 }}"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

Примечание

depends_on не ждет, пока db и redis будут «готовы» перед запуском web — только до тех пор, пока они не будут запущены. Если вам нужно дождаться готовности службы, см. Контроль порядка запуска для получения дополнительной информации об этой проблеме и стратегиях её решения.

Добавлено в формате файла версия 2.1.

Проверка работоспособности указывает на то, что вы хотите, чтобы зависимость перед запуском ждала, пока другой контейнер станет «работоспособным» (на что указывает успешное состояние проверки работоспособности).

Пример:

version: "{{ site.compose_file_v2 }}"
services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres
    healthcheck:
      test: "exit 0"

В приведённом выше примере Compose ожидает запуска службы redis (устаревшее поведение) и работоспособности службы db перед запуском web.

См. раздел проверки здоровья для получения дополнительной информации.

dns

Пользовательские DNS-серверы. Может быть одним значением или списком.

dns: 8.8.8.8
dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

Список настраиваемых параметров DNS для добавления в файл контейнера resolv.conf.

dns_opt:
  - use-vc
  - no-tld-query

entrypoint

Переопределить точку входа по умолчанию.

entrypoint: /code/entrypoint.sh

Точка входа также может быть списком, аналогично докерфайл:

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

Примечание

Параметр entrypoint переопределяет любую точку входа по умолчанию, установленную в образе службы с помощью инструкции Dockerfile ENTRYPOINT, и очищает любую команду по умолчанию в образе — это означает, что если в Dockerfile есть оператор CMD, она игнорируется.

env_file

Добавляет переменные среды из файла. Может быть одним значением или списком.

Если вы указали файл Compose с docker-compose -f FILE, пути в env_file относятся к каталогу, в котором находится файл.

Переменные среды, объявленные в разделе среда, переопределяют данные значения — это справедливо, даже если данные значения пусты или не определены.

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

Compose ожидает, что каждая строка в файле env будет иметь формат VAR=VAL. Строки, начинающиеся с #, считаются комментариями и игнорируются. Пустые строки также игнорируются.

# Set Rails/Rack environment
RACK_ENV=development

Примечание

Если в вашей службе указана опция build, переменные, определённые в файлах среды, не автоматически отображаются во время сборки. Используйте подпараметр args build для определения переменных среды времени сборки.

Значение VAL используется как есть и не изменяется вообще. Например, если значение заключено в кавычки (как это часто бывает с переменными оболочки), кавычки включаются в значение, передаваемое в Compose.

Имейте в виду, что порядок файлов в списке важен для определения значения, присвоенного переменной, которая появляется более одного раза. Файлы в списке обрабатываются сверху вниз. Для одной и той же переменной, указанной в файле a.env и присвоенной другому значению в файле b.env, если b.env указан далее (после), то стоит значение из b.env. Например, учитывая следующее объявление в docker-compose.yml:

services:
  some-service:
    env_file:
      - a.env
      - b.env

И следующие файлы:

# a.env
VAR=1

и

# b.env
VAR=hello

$VAR — это hello.

environment

Добавляет переменные среды. Вы можете использовать либо массив, либо словарь. Любые логические значения (true, false, yes, no) необходимо заключать в кавычки, чтобы парсер YML не преобразовывал их в Истина или Ложь.

Переменные среды только с ключом преобразуются в свои значения на компьютере, на котором работает Compose, что может быть полезно для секретных или специфичных для хоста значений.

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

Примечание

Если в вашей службе указана опция строить, переменные, определённые в environment, не автоматически отображаются во время сборки. Используйте подпараметр аргументы build для определения переменных среды времени сборки.

expose

Выставляйте порты, не публикуя их на хост-компьютере — они будут доступны только связанным службам. Можно указывает только внутренний порт.

expose:
  - "3000"
  - "8000"

extends

Расширить другой сервис в текущем файле или другом, при необходимости переопределяя конфигурацию.

Вы можете использовать extends в любой службе вместе с другими ключами конфигурации. Значение extends должно быть словарем, определенным с обязательным ключом service и необязательным ключом file.

extends:
  file: common.yml
  service: webapp

service — это имя расширяемой службы, например, web или database. file — это расположение файла конфигурации Compose, определяющего эту службу.

Если вы опустите file, Compose ищет конфигурацию службы в текущем файле. Значение file может быть абсолютным или относительным путём. Если вы укажете относительный путь, Compose рассматривает его как относительный путь к текущему файлу.

Вы можете расширить службу, которая сама расширяет другую. Вы можете продлевать на неопределенный срок. Compose не поддерживает циклические ссылки, и docker-compose возвращает ошибку, если она встречается.

Подробнее о extends см. в документации по расширениям.

extra_hosts

Добавляет сопоставления имён хостов. Используйте те же значения, что и для параметра клиента Docker --add-host.

extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"

Запись с IP-адресом и именем хоста создаётся в /etc/hosts внутри контейнеров для этой службы, например:

162.242.195.82  somehost
50.31.209.229   otherhost

group_add

Указывает дополнительные группы (по имени или номеру), членом которых должен быть пользователь внутри контейнера. Группы должны существовать как в контейнере, так и в хост-системе, которую нужно добавить. Примером того, где это полезно, является ситуация, когда несколько контейнеров (работающих от имени разных пользователей) должны читать или записывать один и тот же файл в хост-системе. Данный файл может принадлежать группе, совместно используемой всеми контейнерами, и указан в group_add. См. Документация по докеру для более подробной информации.

Полный пример:

version: "{{ site.compose_file_v2 }}"
services:
  myservice:
    image: alpine
    group_add:
      - mail

Запуск id внутри созданного контейнера показывает, что пользователь принадлежит к группе mail, чего не было бы, если бы group_add не использовался.

healthcheck

Примечание

Добавлено в формате файла версия 2.1.

Настраивает проверку, которая запускается, чтобы определить, являются ли контейнеры для этой службы «работоспособными». См. документы для Оператор HEALTHCHECK Dockerfile для получения подробной информации о том, как работают проверки работоспособности.

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

interval, timeout и start_period указаны как продолжительность.

Добавлено в формате файла версия 2.3.

Параметр start_period был добавлен в формат файла 2.3.

test должен быть либо строкой, либо списком. Если это список, первым элементом должен быть NONE, CMD или CMD-SHELL. Если это строка, это эквивалентно указанию CMD-SHELL, за которым следует эта строка.

# Hit the local web app
test: ["CMD", "curl", "-f", "http://localhost"]

То же, что и выше, но в /bin/sh. Обе приведенные далее формы эквивалентны.

test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
test: curl -f https://localhost || exit 1

Чтобы отключить любую проверку работоспособности по умолчанию, установленную образом, вы можете использовать disable: true. Это эквивалентно указанию test: ["NONE"].

healthcheck:
  disable: true

image

Указывает образ, с которого будет запускаться контейнер. Может быть репозиторием/тегом или частичным идентификатором образа.

image: redis
image: ubuntu:18.04
image: tutum/influxdb
image: example-registry.com:4000/postgresql
image: a4bc65fd

Если образ не существует, Compose пытается извлечь его, если только вы не указали также строить, и в этом случае он создаёт его с использованием указанных параметров и помечает его указанным тегом.

init

Добавлено в формате файла версия 2.2.

Запускает init внутри контейнера, который пересылает сигналы и собирает процессы. Устанавливает для этого параметра значение true, чтобы включить эту функцию для службы.

version: "{{ site.compose_file_v2 }}"
services:
  web:
    image: alpine:latest
    init: true

Используемый по умолчанию двоичный файл инициализации имеет значение Tini и устанавливается в /usr/libexec/docker-init на хосте демона. Вы можете настроить демон для использования пользовательского двоичного файла инициализации через опция конфигурации init-path.

isolation

Добавлено в формате файла версия 2.1.

Указывает технологию изоляции контейнера. В Linux поддерживается только значение default. В Windows допустимы значения default, process и hyperv. Подробности см. в документации по Docker Engine.

labels

Добавляет метаданные в контейнеры с помощью Ярлыки Docker. Вы можете использовать либо массив, либо словарь.

Рекомендуется использовать обратную DNS-нотацию, чтобы ваши метки не конфликтовали с метками, используемыми другим программным обеспечением.

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""
labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

logging

Настройка ведения журнала для службы.

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

Имя driver указывает драйвер ведения журнала для контейнеров службы, как и параметр --log-driver для запуска Docker (задокументировано здесь).

Значение по умолчанию — json-файл.

driver: "json-file"
driver: "syslog"
driver: "none"

Примечание

Только драйверы json-file и journald делают журналы доступными непосредственно из docker-compose up и docker-compose logs. При использовании любого другого драйвера журналы не печатаются.

Указывает параметры ведения журнала для драйвера ведения журнала с помощью ключа options, как с параметром --log-opt для docker run.

Параметры ведения журнала представляют собой пары ключ-значение. Пример опций syslog:

driver: "syslog"
options:
  syslog-address: "tcp://192.168.0.42:123"

network_mode

Изменено в формате файла версия 2.

Сетевой режим. Используйте те же значения, что и параметр клиента Docker --network, плюс специальную форму service:[service name].

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

networks

Примечание

Изменено в формате файла версия 2.

Сети, к которым нужно присоединиться, ссылаясь на записи под ключом верхнего уровня сети.

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

aliases

Псевдонимы (альтернативные имена хостов) для этой службы в сети. Другие контейнеры в той же сети могут использовать либо имя службы, либо данный псевдоним для подключения к одному из контейнеров службы.

Поскольку aliases относится к сети, одна и та же служба может иметь разные псевдонимы в разных сетях.

Примечание

Общесетевой псевдоним может совместно использоваться несколькими контейнерами и даже несколькими службами. Если это так, то точно не гарантируется, в какой именно контейнер разрешается имя.

Общий формат показан здесь.

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

В приведённом далее примере предоставляются три службы (web, worker и db), а также две сети (new и legacy). Служба db доступна по имени хоста db или database в сети new и по db или mysql в сети legacy.

version: "{{ site.compose_file_v2 }}"

services:
  web:
    image: "nginx:alpine"
    networks:
      - new

  worker:
    image: "my-worker-image:latest"
    networks:
      - legacy

  db:
    image: mysql
    networks:
      new:
        aliases:
          - database
      legacy:
        aliases:
          - mysql

networks:
  new:
  legacy:

ipv4_address, ipv6_address

Указывает статический IP-адрес для контейнеров для этой службы при подключении к сети.

Соответствующая сетевая конфигурация в раздел сетей верхнего уровня должна иметь блок ipam с конфигурациями подсети и шлюза, охватывающими каждый статический адрес.

Если требуется адресация IPv6, необходимо установить параметр enable_ipv6 enable\_ipv6.

Пример:

version: "{{ site.compose_file_v2 }}"

services:
  app:
    image: busybox
    command: ifconfig
    networks:
      app_net:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  app_net:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 172.16.238.0/24
          gateway: 172.16.238.1
        - subnet: 2001:3984:3989::/64
          gateway: 2001:3984:3989::1

priority

Указывает приоритет, чтобы указывает, в каком порядке Compose должен подключать контейнеры службы к своим сетям. Если не указано, значение по умолчанию — 0.

В следующем примере служба app сначала подключается к app_net_1, поскольку она имеет наивысший приоритет. Затем он подключается к app_net_3, затем app_net_2, который использует значение приоритета по умолчанию 0.

version: "{{ site.compose_file_v2 }}"
services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

Примечание

Если несколько сетей имеют одинаковый приоритет, порядок подключения не определён.

pid

pid: "host"
pid: "container:custom_container_1"
pid: "service:foobar"

Если задана одна из следующих форм: container:<container_name>, service:<service_name>, служба совместно использует адресное пространство PID назначенного контейнера или службы.

Если установлено значение «хост», режим PID службы является режимом PID хоста. Это включает совместное использование контейнером и операционной системой хоста адресного пространства PID. Контейнеры, запущенные с этим флагом, могут получать доступ и манипулировать другими контейнерами в пространстве имён «голого» компьютера и наоборот.

Добавлено в формате файла версия 2.1.

Для форм service: и container: требуется версия 2.1 или выше

pids_limit

Добавлено в формате файла версия 2.1.

Настраивает ограничение PID контейнера. Устанавливает -1 для неограниченного количества PID.

pids_limit: 10

platform

Добавлено в формате файла версия 2.4.

Контейнеры целевой платформы для этой службы будут работать с использованием синтаксиса os[/arch[/variant]], например.

platform: osx
platform: windows/amd64
platform: linux/arm64/v8

Данный параметр определяет, какая версия образа будет извлечена и/или на какой платформе будет выполняться сборка службы.

ports

Выставить порты. Либо указывает оба порта (HOST:CONTAINER), либо только порт контейнера (выбирается эфемерный порт хоста).

Примечание

При сопоставлении портов в формате HOST:CONTAINER вы можете получает ошибочные результаты при использовании порта контейнера далее 60, поскольку YAML анализирует числа в формате xx:yy как значение с основанием 60. По этой причине мы рекомендуем всегда явно указывать сопоставления портов в виде строк.

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"

runtime

Добавлено в формате файла версия 2.3.

Указывает, какую среду выполнения следует использовать для контейнеров службы. Среда выполнения по умолчанию и доступные среды выполнения перечислены в выходных данных docker info.

web:
  image: busybox:latest
  command: true
  runtime: runc

scale

Добавлено в формате файла версия 2.2.

Указывает количество контейнеров по умолчанию для развертывания для этой службы. Всякий раз, когда вы запускаете docker-compose up, Compose создаёт или удаляет контейнеры в соответствии с указанным номером. Это значение можно переопределить с помощью –scale

web:
  image: busybox:latest
  command: echo 'scaled'
  scale: 3

security_opt

Переопределите схему маркировки по умолчанию для каждого контейнера.

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

stop_grace_period

Указывает, как долго ждать при попытке останавливает контейнер, если он не обрабатывает SIGTERM (или любой другой сигнал остановки, указанный с помощью stop_signal), перед отправкой SIGKILL. Указывается как продолжительность.

stop_grace_period: 1s
stop_grace_period: 1m30s

По умолчанию stop ждет 10 секунд, пока контейнер не выйдет, прежде чем отправить SIGKILL.

stop_signal

Устанавливает альтернативный сигнал для остановки контейнера. По умолчанию stop использует SIGTERM. Установка альтернативного сигнала с использованием stop_signal приводит к тому, что stop вместо этого отправляет данный сигнал.

stop_signal: SIGUSR1

storage_opt

Добавлено в формате файла версия 2.1.

Задаёт параметры драйвера хранилища для этой службы.

storage_opt:
  size: '1G'

sysctls

Добавлено в формате файла версия 2.1.

Параметры ядра для установки в контейнере. Вы можете использовать либо массив, либо словарь.

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0
sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

tmpfs

Смонтировать временную файловую систему внутри контейнера. Может быть одним значением или списком.

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

ulimits

Переопределите ulimits по умолчанию для контейнера. Вы можете указывает одно ограничение в виде целого числа или мягкие/жесткие ограничения в виде сопоставления.

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

userns_mode

Добавлено в формате файла версия 2.1.

userns_mode: "host"

Отключает пространство имён пользователей для этой службы, если демон Docker настроен с пространствами имён пользователей. См. dockerd для получения дополнительной информации.

volumes

Монтирует пути хоста или именованные тома. Именованные тома необходимо указывать с помощью ключа верхнего уровня volumes.

Краткий синтаксис

В коротком синтаксисе используется общий формат [SOURCE:]TARGET[:MODE], где SOURCE может быть либо путём к хосту, либо именем тома. TARGET — это путь к контейнеру, в котором смонтирован том. Стандартные режимы: ro только для чтения и rw для чтения-записи (по умолчанию).

Вы можете смонтировать относительный путь на хосте, который расширяется относительно каталога используемого файла конфигурации Compose. Относительные пути всегда должны начинаться с . или ...

volumes:
  # Just specify a path and let the Engine create a volume
  - /var/lib/mysql

  # Specify an absolute path mapping
  - /opt/data:/var/lib/mysql

  # Path on the host, relative to the Compose file
  - ./cache:/tmp/cache

  # User-relative path
  - ~/configs:/etc/configs/:ro

  # Named volume
  - datavolume:/var/lib/mysql

Длинный синтаксис

Добавлено в формате файла версия 2.3.

Синтаксис длинной формы позволяет настраивать дополнительные поля, которые не могут быть выражены в краткой форме.

  • type: тип монтирования volume, bind, tmpfs или npipe

  • source: источник монтирования, путь на хосте для монтирования с привязкой или имя тома, определённое в ключе volumes верхнего уровня. Неприменимо для монтирования tmpfs.

  • target: путь в контейнере, куда смонтирован том

  • read_only: флаг, чтобы сделать том доступным только для чтения

  • bind: настроить дополнительные параметры привязки

  • propagation: режим распространения, используемый для привязки

  • volume: настроить дополнительные параметры тома

  • nocopy: флаг для отключения копирования данных из контейнера при создании тома

  • tmpfs: настроить дополнительные параметры tmpfs

  • size: размер монтирования tmpfs в байтах

version: "{{ site.compose_file_v2 }}"
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - type: volume
        source: mydata
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: ./static
        target: /opt/app/static

networks:
  webnet:

volumes:
  mydata:

Примечание

При создании привязанных монтирований использование длинного синтаксиса требует, чтобы папка, на которую делается ссылка, была создана заранее. Использование короткого синтаксиса создаёт папку на лету, если она не существует. См. привязать документацию по монтированию для получения дополнительной информации.

volume_driver

Указывает драйвер тома по умолчанию, который будет использоваться для всех объявленных томов в этой службе.

volume_driver: mydriver

Примечание

В файлы версии 2 данный параметр применяется только к анонимным томам (указанным в образе или указанным в volumes без явного именованного тома или пути к хосту). Чтобы настроить драйвер для именованного тома, используйте ключ driver под записью в опции верхнего уровня volumes справочник по настройке тома.

См. Docker тома и Плагины тома для получения дополнительной информации.

volumes_from

Смонтировать все тома из другой службы или контейнера, при необходимости указав доступ только для чтения (ro) или для чтения и записи (rw). Если уровень доступа не указан, то используется чтение-запись.

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

Примечание

Изменено в формате файла версия 2.

restart

no — это политика перезапуска по умолчанию, и она не перезапускает контейнер ни при каких обстоятельствах. Когда указан always, контейнер всегда перезапускается. Политика on-failure перезапускает контейнер, если код выхода указывает на ошибку при сбое.

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

cpu_count, cpu_percent, cpu_shares, cpu_period, cpu_quota, cpus, cpuset, domainname, hostname, ipc, mac_address, mem_limit, memswap_limit, mem_swappiness, mem_reservation, oom_kill_disable, oom_score_adj, privileged, read_only, shm_size, stdin_open, tty, user, working_dir

Каждое из них представляет собой отдельное значение, аналогичное его аналогу запуск Docker.

Добавлено в формате файла версия 2.2.

Параметры cpu_count, cpu_percent и cpus были добавлены в версия 2.2.

Добавлено в формате файла версия 2.1.

Параметры oom_kill_disable и cpu_period были добавлены в версия 2.1.

cpu_count: 2
cpu_percent: 50
cpus: 0.5
cpu_shares: 73
cpu_quota: 50000
cpu_period: 20ms
cpuset: 0,1

user: postgresql
working_dir: /code

domainname: foo.com
hostname: foo
ipc: host
mac_address: 02:42:ac:11:65:43

mem_limit: 1000000000
memswap_limit: 2000000000
mem_reservation: 512m
privileged: true

oom_score_adj: 500
oom_kill_disable: true

read_only: true
shm_size: 64M
stdin_open: true
tty: true

Указание длительности

Некоторые параметры конфигурации, такие как подпараметры interval и timeout для healthcheck, принимают продолжительность в виде строки в формате, который выглядит следующим образом:

2.5s
10s
1m30s
2h32m
5h34m56s

Поддерживаемые единицы: us, ms, s, m и h.

Указание значений байтов

Некоторые параметры конфигурации, такие как подпараметр device_read_bps для blkio\_config, принимают значение байта в виде строки в формате, который выглядит следующим образом:

2b
1024kb
2048k
300m
1gb

Поддерживаемые единицы измерения: b, k, m и g, а также их альтернативные обозначения kb, mb и gb. Десятичные значения в настоящее время не поддерживаются.

Справочник по конфигурации тома

Хотя тома можно объявить на лету как часть объявления службы, данный раздел позволяет создавать именованные тома, которые можно повторно использовать в нескольких службах (не полагаясь на volumes_from), и которые легко извлекаются и проверяются с помощью команды docker. линия или API. Дополнительные сведения см. в документации по подкоманде объём Docker.

См. объёмы использования и плагины тома для получения общей информации о томах.

Вот пример установки с двумя службами, в которой каталог данных базы данных используется совместно с другой службой в виде тома, чтобы можно было периодически создавать резервные копии:

version: "{{ site.compose_file_v2 }}"

services:
  db:
    image: db
    volumes:
      - data-volume:/var/lib/db
  backup:
    image: backup-service
    volumes:
      - data-volume:/var/lib/backup/data

volumes:
  data-volume:

Запись под ключом верхнего уровня volumes может быть пустой, и в этом случае используется драйвер по умолчанию, настроенный Engine (в большинстве случаев это драйвер local). При желании вы можете настроить его с помощью следующих ключей:

driver

Указывает, какой драйвер тома следует использовать для этого тома. По умолчанию используется любой драйвер, который был настроен для использования Docker Engine, в большинстве случаев это local. Если драйвер недоступен, Engine возвращает ошибку, когда docker-compose up пытается создать том.

driver: foobar

driver_opts

Указывает список параметров в виде пар ключ-значение для передачи драйверу для этого тома. Данные параметры зависят от драйвера — для получения дополнительной информации обратитесь к документации драйвера. Необязательный.

volumes:
  example:
    driver_opts:
      type: "nfs"
      o: "addr=10.40.0.199,nolock,soft,rw"
      device: ":/docker/example"

external

Если установлено значение true, указывает, что данный том был создан вне Compose. docker-compose up не пытается его создать и вызывает ошибку, если он не существует.

Для версии 2.0 формата external нельзя использовать вместе с другими ключами конфигурации тома (driver, driver_opts, labels). Это ограничение больше не существует для версия 2.1 и выше.

В приведённом далее примере вместо попытки создать том с именем [projectname]_data Compose ищет существующий том с простым названием data и монтирует его в контейнеры службы db.

version: "{{ site.compose_file_v2 }}"

services:
  db:
    image: postgres
    volumes:
      - data:/var/lib/postgresql/data

volumes:
  data:
    external: true

Вы также можете указывает имя тома отдельно от имени, используемого для ссылки на него в файле Compose:

volumes:
  data:
    external:
      name: actual-name-of-volume

Примечание

Добавлено в формате файла версия 2.1.

external.name устарел в формате файла версии 2.1, вместо него используйте name.

labels

Примечание

Добавлено в формате файла версия 2.1.

Добавляет метаданные в контейнеры с помощью Ярлыки Docker. Вы можете использовать либо массив, либо словарь.

Рекомендуется использовать обратную DNS-нотацию, чтобы ваши метки не конфликтовали с метками, используемыми другим программным обеспечением.

labels:
  com.example.description: "Database volume"
  com.example.department: "IT/Ops"
  com.example.label-with-empty-value: ""
labels:
  - "com.example.description=Database volume"
  - "com.example.department=IT/Ops"
  - "com.example.label-with-empty-value"

name

Добавлено в формате файла версия 2.1.

Задаёт собственное имя для этого тома. Поле имени можно использовать для ссылки на тома, содержащие специальные символы. Имя используется как есть и не ограничивается именем стека.

version: "{{ site.compose_file_v2 }}"
volumes:
  data:
    name: my-app-data

Его также можно использовать в сочетании со свойством external:

version: "{{ site.compose_file_v2 }}"
volumes:
  data:
    external: true
    name: my-app-data

Справочник по конфигурации сети

Ключ верхнего уровня networks позволяет указывает создаваемые сети. Полное объяснение того, как Compose использует сетевые функции Docker, см. в документе Руководство по сети.

driver

Указывает, какой драйвер следует использовать для этой сети.

Драйвер по умолчанию зависит от того, как настроен используемый вами Docker Engine, но в большинстве случаев это bridge на одном хосте и overlay на Swarm.

Docker Engine возвращает ошибку, если драйвер недоступен.

driver: overlay

Примечание

Изменено в формате файла версия 2.1.

Начиная с формата файла Compose 2.1, оверлейные сети всегда создаются как attachable, и это невозможно настроить. Это означает, что автономные контейнеры могут подключаться к оверлейным сетям.

driver_opts

Указывает список параметров в виде пар ключ-значение для передачи драйверу для этой сети. Данные параметры зависят от драйвера — для получения дополнительной информации обратитесь к документации драйвера. Необязательный.

driver_opts:
  foo: "bar"
  baz: 1

enable_ipv6

Добавлено в формате файла версия 2.1.

Включает сеть IPv6 в этой сети.

ipam

Указывает пользовательскую конфигурацию IPAM. Это объект с несколькими свойствами, каждое из которых является необязательным:

  • driver: собственный драйвер IPAM вместо используемого по умолчанию.

  • config: список с нулем или более блоков конфигурации, каждый из которых содержит любой из следующих ключей:

    • subnet: подсеть в формате CIDR, представляющая сегмент сети

    • ip_range: диапазон IP-адресов, из которых можно выделяет IP-адреса контейнера

    • gateway: шлюз IPv4 или IPv6 для главной подсети

    • aux_addresses: вспомогательные адреса IPv4 или IPv6, используемые сетевым драйвером, как сопоставление имени хоста с IP-адресом

  • options: параметры драйвера в виде сопоставления ключ-значение.

Полный пример:

ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16
      ip_range: 172.28.5.0/24
      gateway: 172.28.5.254
      aux_addresses:
        host1: 172.28.1.5
        host2: 172.28.1.6
        host3: 172.28.1.7
  options:
    foo: bar
    baz: "0"

internal

По умолчанию Docker также подключает к нему мостовую сеть для обеспечения внешнего подключения. Если вы хотите создать внешне изолированную оверлейную сеть, вы можете установить для этого параметра значение true.

labels

Добавлено в формате файла версия 2.1.

Добавляет метаданные в контейнеры с помощью Докерлейблы. Вы можете использовать либо массив, либо словарь.

Рекомендуется использовать обратную DNS-нотацию, чтобы ваши метки не конфликтовали с метками, используемыми другим программным обеспечением.

labels:
  com.example.description: "Financial transaction network"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""
labels:
  - "com.example.description=Financial transaction network"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

external

Если установлено значение true, это означает, что эта сеть была создана вне Compose. docker-compose up не пытается его создать и вызывает ошибку, если он не существует.

Для версии 2.0 формата external нельзя использовать вместе с другими ключами конфигурации сети (driver, driver_opts, ipam, internal). Это ограничение больше не существует для версия 2.1 и выше.

В приведённом далее примере proxy — это ворота во внешний мир. Вместо попытки создать сеть с именем [projectname]_outside Compose ищет существующую сеть с простым названием outside и подключает к ней контейнеры службы proxy.

version: "{{ site.compose_file_v2 }}"

services:
  proxy:
    build: ./proxy
    networks:
      - outside
      - default
  app:
    build: ./app
    networks:
      - default

networks:
  outside:
    external: true

Вы также можете указывает имя сети отдельно от имени, используемого для ссылки на нее в файле Compose:

version: "{{ site.compose_file_v2 }}"
networks:
  outside:
    external:
      name: actual-name-of-network

Не поддерживается для файлов docker-compose версии 2. Вместо этого используйте network_mode.

name

Добавлено в формате файла версия 2.1.

Задаёт собственное имя для этой сети. Поле имени можно использовать для ссылок на сети, содержащие специальные символы. Имя используется как есть и не ограничивается именем стека.

version: "{{ site.compose_file_v2 }}"
networks:
  network1:
    name: my-app-net

Его также можно использовать в сочетании со свойством external:

version: "{{ site.compose_file_v2 }}"
networks:
  network1:
    external: true
    name: my-app-net

Замена переменной

Ваши параметры конфигурации могут содержать переменные среды. Compose использует значения переменных из среды оболочки, в которой запускается docker-compose. Например, предположим, что оболочка содержит POSTGRES_VERSION=9.3, и вы предоставляете следующую конфигурацию:

db:
  image: "postgres:${POSTGRES_VERSION}"

Когда вы запускаете docker-compose up с этой конфигурацией, Compose ищет переменную среды POSTGRES_VERSION в оболочке и подставляет её значение. В этом примере Compose преобразует image в postgres:9.3 перед запуском конфигурации.

Если переменная среды не задана, Compose заменяет её пустой строкой. В приведённом выше примере, если POSTGRES_VERSION не задан, значение параметра image равно postgres:.

Вы можете установить значения по умолчанию для переменных среды, используя .env-файл, который Compose автоматически ищет в каталоге проекта (родительская папка вашего файла Compose). Значения, установленные в среде оболочки, переопределяют значения, установленные в файле .env.

Примечание

Примечание при использовании развертывания стека докеров

Функция .env file работает только при использовании команды docker-compose up и не работает с docker stack deploy.

Поддерживаются синтаксис $VARIABLE и ${VARIABLE}. Кроме того, при использовании 2.1 формат файла можно указывает встроенные значения по умолчанию, используя типичный синтаксис оболочки:

  • ${VARIABLE:-default} оценивается как default, если VARIABLE не установлен или пуст в среде.

  • ${VARIABLE-default} оценивается как default, только если VARIABLE не установлен в среде.

Точно так же следующий синтаксис позволяет указывать обязательные переменные:

  • ${VARIABLE:?err} завершается с сообщением об ошибке, содержащим err, если VARIABLE не установлен или пуст в среде.

  • ${VARIABLE?err} завершается с сообщением об ошибке, содержащим err, если VARIABLE не установлен в среде.

Другие расширенные функции оболочки, такие как ${VARIABLE/foo/bar}, не поддерживаются.

Вы можете использовать $$ (знак двойного доллара), когда вашей конфигурации требуется буквальный знак доллара. Это также не позволяет Compose интерполировать значение, поэтому $$ позволяет вам ссылаться на переменные среды, которые вы не хотите обрабатывать в Compose.

web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"

Если вы забудете и используете один знак доллара ($), Compose интерпретирует значение как переменную среды и предупреждает вас:

The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.

Поля расширения

Добавлено в формате файла версия 2.1.

Можно повторно использовать фрагменты конфигурации, используя поля расширения. Данные специальные поля могут иметь любой формат, если они расположены в корне файла Compose и их имена начинаются с последовательности символов x-.

Примечание

Начиная с формата 3.7 (для серии 3.x) и формата 2.4 (для серии 2.x), поля расширения также разрешены в корне определений службы, тома, сети, конфигурации и секрета.

version: "{{ site.compose_file_v3 }}"
x-custom:
  items:
    - a
    - b
  options:
    max-size: '12m'
  name: "custom"

Содержимое данных полей игнорируется Compose, но их можно вставляет в определения ваших ресурсов с помощью YAML якоря. Например, если вы хотите, чтобы несколько ваших служб использовали одну и ту же конфигурацию ведения журнала:

logging:
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

Вы можете написать файл Compose следующим образом:

version: "{{ site.compose_file_v3 }}"
x-logging:
  &default-logging
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

services:
  web:
    image: myapp/web:latest
    logging: *default-logging
  db:
    image: mysql:latest
    logging: *default-logging

Также можно частично переопределить значения в полях расширения, используя Тип слияния YAML. Например:

version: "{{ site.compose_file_v3 }}"
x-volumes:
  &default-volume
  driver: foobar-storage

services:
  web:
    image: myapp/web:latest
    volumes: ["vol1", "vol2", "vol3"]
volumes:
  vol1: *default-volume
  vol2:
    << : *default-volume
    name: volume02
  vol3:
    << : *default-volume
    driver: default
    name: volume-local

Документация по Compose