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

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

В данных разделах описывается версия 3 формата файла 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 был впервые представлен в Compose релиз 1_10_0, и в последующих выпусках его версии постепенно изменялись.

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

Структура файла Compose и примеры

Вот пример файла Compose из примера приложения для голосования, использованного в теме Лаборатория Docker для начинающих на Развертывание приложения на Swarm:

Пример файла Compose версии 3

version: "{{ site.compose_file_v3 }}"
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:
        max_replicas_per_node: 1
        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:

Темы на этой справочной странице организованы в алфавитном порядке по ключу верхнего уровня, чтобы отразить структуру самого файла Compose. Ключи верхнего уровня, определяющие раздел в файле конфигурации, например build, deploy, depends_on, networks и т.д., перечислены вместе с поддерживающими их параметрами в виде подтем. Это соответствует структуре отступа <key>: <option>: <value> файла Compose.

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

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

Примечание

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

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

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

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

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

build

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

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

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

Или как объект с путём, указанным в контекст и, необязательно, Докерфайл и аргументы:

version: "{{ site.compose_file_v3 }}"
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.

Примечание

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

Параметр build игнорируется, когда команда развертывание стека в режиме swarm docker stack не создаёт образы перед развертыванием.

context

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

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

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

build:
  context: ./dir

dockerfile

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

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

build:
  context: .
  dockerfile: Dockerfile-alternate

args

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

Сначала указывает аргументы в вашем 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 ("true", "false", "yes", "no", "on", "off") должны быть заключены в кавычки, чтобы парсер интерпретировал их как строки.

cache_from

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

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

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

labels

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

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

Рекомендуется использовать обратную 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

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

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

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

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

build:
  context: .
  network: none

shm_size

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

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

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

target

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

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

build:
  context: .
  target: prod

cap_add, cap_drop

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

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

Примечание

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

Параметры cap_add и cap_drop игнорируются, если развертывание стека в режиме swarm

cgroup_parent

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

cgroup_parent: m-executor-abcd

Примечание

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

Параметр cgroup_parent игнорируется, если развертывание стека в режиме swarm

command

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

command: bundle exec thin -p 3000

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

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

configs

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

Примечание

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

Дополнительные сведения о конфигурациях см. в статье configs.

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

Опция с коротким синтаксисом указывает только имя конфигурации. Это предоставляет контейнеру доступ к конфигурации и монтирует её в /<config_name> внутри контейнера. Имя источника и точка монтирования назначения устанавливаются на имя конфигурации.

В следующем примере используется короткий синтаксис для предоставления службе redis доступа к конфигурациям my_config и my_other_config. Значение my_config устанавливается равным содержимому файла ./my_config.txt, а my_other_config определяется как внешний ресурс, что означает, что он уже определён в Docker либо путём выполнения команды docker config create, либо путём другого развертывания стека. Если внешняя конфигурация не существует, развертывание стека завершится ошибкой config not found.

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

Определения config поддерживаются только в версии 3.3 и выше формата файла compose.

version: "{{ site.compose_file_v3 }}"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

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

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

  • source: идентификатор конфигурации, как он определён в этой конфигурации.

  • target: путь и имя файла, который нужно подключить в контейнерах задач службы. По умолчанию /<source>, если не указано иное.

  • uid и gid: числовой UID или GID, которому принадлежит подключенный файл конфигурации в контейнерах задач службы. Оба по умолчанию имеют значение 0 в Linux, если не указано иное. Не поддерживается в Windows.

  • mode: разрешения для файла, смонтированного в контейнерах задач службы, в восьмеричном представлении. Например, 0444 означает доступный для чтения всем. По умолчанию 0444. Конфиги не могут быть доступны для записи, потому что они смонтированы во временной файловой системе, поэтому, если вы устанавливает бит для записи, он будет проигнорирован. Исполняемый бит может быть установлен. Если вы не знакомы с режимами доступа к файлам UNIX, вам может пригодиться данный калькулятор разрешений.

В следующем примере для имени my_config задается значение redis_config в контейнере, для режима устанавливается значение 0440 (доступно для чтения группой), а для пользователя и группы задается значение 103. Служба redis не имеет доступа к конфигурации my_other_config.

version: "{{ site.compose_file_v3 }}"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - source: my_config
        target: /redis_config
        uid: '103'
        gid: '103'
        mode: 0440
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

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

container_name

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

container_name: my-web-container

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

Примечание

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

Параметр container_name игнорируется, когда развертывание стека в режиме swarm

credential_spec

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

Параметр credential_spec был добавлен в v3.3. Использование конфигураций групповой управляемой учетной записи службы (gMSA) с файлами compose поддерживается в формате файла версии 3.8 или выше.

Настраивает спецификацию учетных данных для управляемой учетной записи службы. Данный параметр используется только для служб, использующих контейнеры Windows. credential_spec должен быть в формате file://<filename> или registry://<value-name>.

При использовании file: указанный файл должен находиться в подкаталоге CredentialSpecs в каталоге данных Docker, который по умолчанию имеет значение C:\ProgramData\Docker\ в Windows. В следующем примере спецификация учетных данных загружается из файла с именем C:\ProgramData\Docker\CredentialSpecs\my-credential-spec.json.

credential_spec:
  file: my-credential-spec.json

При использовании registry: спецификация учетных данных считывается из реестра Windows на хосте демона. Значение реестра с заданным именем должно находиться в:

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

В следующем примере спецификация учетных данных загружается из значения с именем my-credential-spec в реестре:

credential_spec:
  registry: my-credential-spec

Пример конфигурации gMSA

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

version: "{{ site.compose_file_v3 }}"
services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json|

depends_on

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

  • 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_v3 }}"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

При использовании depends_on следует помнить о нескольких вещах:

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

  • Параметр depends_on игнорируется при развертывание стека в режиме swarm с файлом Compose версии 3.

deploy

Примечание

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

Указывает конфигурацию, связанную с развертыванием и запуском служб. Следующие подпараметры действуют только при развертывании на swarm с развертывание стека докеров и игнорируются docker-compose up и docker-compose run, за исключением resources.

version: "{{ site.compose_file_v3 }}"
services:
  redis:
    image: redis:alpine
    deploy:
      replicas: 6
      placement:
        max_replicas_per_node: 1
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

Доступны несколько подопций:

endpoint_mode

Примечание

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

Указывает метод обнаружения службы для внешних клиентов, подключающихся к swarm.

  • endpoint_mode: vip — Docker назначает службе виртуальный IP-адрес (VIP), который действует как внешний интерфейс для доступа клиентов к службе в сети. Docker направляет запросы между клиентом и доступными рабочими узлами для службы, не зная клиента о том, сколько узлов участвует в службе или их IP-адресах или портах. (Это значение по умолчанию.)

  • endpoint_mode: dnsrr — Обнаружение службы циклического перебора DNS (DNSRR) не использует один виртуальный IP-адрес. Docker настраивает записи DNS для службы таким образом, что запрос DNS для имени службы возвращает список IP-адресов, и клиент подключается непосредственно к одному из них. Циклический перебор DNS полезен в тех случаях, когда вы хотите использовать собственный балансировщик нагрузки или для гибридных приложений Windows и Linux.

version: "{{ site.compose_file_v3 }}"

services:
  wordpress:
    image: wordpress
    ports:
      - "8080:80"
    networks:
      - overlay
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: vip

  mysql:
    image: mysql
    volumes:
       - db-data:/var/lib/mysql/data
    networks:
       - overlay
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: dnsrr

volumes:
  db-data:

networks:
  overlay:

Параметры для endpoint_mode также работают как флаги в команде CLI режима swarm docker service create. Краткий список всех команд docker, связанных с swarm, см. в Команды CLI режима Swarm.

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

labels

Указывает метки для службы. Данные метки устанавливаются только для службы и не для каких-либо контейнеров службы.

version: "{{ site.compose_file_v3 }}"
services:
  web:
    image: web
    deploy:
      labels:
        com.example.description: "This label will appear on the web service"

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

version: "{{ site.compose_file_v3 }}"
services:
  web:
    image: web
    labels:
      com.example.description: "This label will appear on all containers for the web service"

mode

Либо global (ровно один контейнер на узел swarm), либо replicated (указанное количество контейнеров). По умолчанию replicated. (Чтобы узнать больше, см. Реплицированные и глобальные сервисы в темах swarm.)

version: "{{ site.compose_file_v3 }}"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    deploy:
      mode: global

placement

Указывает размещение ограничений и предпочтений. Полное описание синтаксиса и доступных типов см. в документации docker service create ограничения, настройки, and указание максимального количества реплик на узел

version: "{{ site.compose_file_v3 }}"
services:
  db:
    image: postgres
    deploy:
      placement:
        constraints:
          - "node.role==manager"
          - "engine.labels.operatingsystem==ubuntu 18.04"
        preferences:
          - spread: node.labels.zone

max_replicas_per_node

Примечание

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

Если служба replicated (по умолчанию), ограничить количество реплик может работать на узле в любое время.

Когда запрошено больше задач, чем запущенных узлов, вызывается ошибка no suitable node (max replicas per node limit exceed).

version: "{{ site.compose_file_v3 }}"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6
      placement:
        max_replicas_per_node: 1

replicas

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

version: "{{ site.compose_file_v3 }}"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6

resources

Настраивает ограничения ресурсов.

Примечание

Изменено в файле compose версии 3

Раздел resources заменяет старые варианты ограничения ресурсов в файлах Compose до версии 3 (cpu_shares, cpu_quota, cpuset, mem_limit, memswap_limit, mem_swappiness). Обратитесь к Обновление версии 2.x до 3.x, чтобы узнать о различиях между версиями 2 и 3 формата файла compose.

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

В этом общем примере служба redis ограничена использованием не более 50 МБ памяти и 0.50 (50% одного ядра) доступного времени обработки (ЦП), а также имеет 20M памяти и 0.25 зарезервированного времени ЦП (как всегда доступное). к нему).

version: "{{ site.compose_file_v3 }}"
services:
  redis:
    image: redis:alpine
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
        reservations:
          cpus: '0.25'
          memory: 20M

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

Ищете варианты для установки ресурсов в контейнерах, отличных от режима swarm?

Рассмотренные здесь параметры относятся к ключу deploy и режиму swarm. Если вы хотите установить ограничения ресурсов для развертываний, отличных от swarm, используйте Формат файла Compose версии 2 ЦП, память и другие параметры ресурсов. Если у вас есть дополнительные вопросы, обратитесь к обсуждению проблемы GitHub докер/compose/4513.

Исключения нехватки памяти (OOME)

Если ваши службы или контейнеры пытаются использовать больше памяти, чем доступно системе, вы можете столкнуться с исключением Out Of Memory Exception (OOME), и контейнер или демон Docker могут быть уничтожены убийцей OOM ядра. Чтобы этого не произошло, убедиться, что ваше приложение работает на хостах с достаточным объемом памяти и смотрите Понимание рисков нехватки памяти.

restart_policy

Настраивает, если и как перезапускать контейнеры при выходе. Заменяет перезапуск.

  • condition: один из none, on-failure или any (по умолчанию: any).

  • delay: время ожидания между попытками перезапуска, указанное как продолжительность (по умолчанию: 5 с).

  • max_attempts: сколько раз нужно попытаться перезапустить контейнер, прежде чем сдаться (по умолчанию: никогда не сдаваться). Если перезагрузка не удалась в пределах настроенного window, эта попытка не засчитывается в настроенное значение max_attempts. Например, если для max_attempts установлено значение «2», а перезагрузка не удалась с первой попытки, может быть предпринято более двух попыток перезагрузки.

  • window: время ожидания перед принятием решения об успешном перезапуске, указанное как продолжительность (по умолчанию: принять решение немедленно).

version: "{{ site.compose_file_v3 }}"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

rollback_config

Примечание

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

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

  • parallelism: количество контейнеров для отката за раз. Если установлено значение 0, все контейнеры откатываются одновременно.

  • delay: время ожидания между откатами каждой группы контейнеров (по умолчанию 0 с).

  • failure_action: Что делать, если откат не удался. Один из continue или pause (по умолчанию pause)

  • monitor: продолжительность после каждого обновления задачи для отслеживания сбоя (ns|us|ms|s|m|h) (по умолчанию 5 с) Примечание: при значении 0 будет использоваться значение по умолчанию 5 с.

  • max_failure_ratio: Допустимая частота отказов во время отката (по умолчанию 0).

  • order: Порядок операций при откатах. Один из stop-first (старая задача останавливается перед запуском новой) или start-first (новая задача запускается первой, а запущенные задачи ненадолго перекрываются) (по умолчанию stop-first).

update_config

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

  • parallelism: количество контейнеров для одновременного обновления.

  • delay: время ожидания между обновлением группы контейнеров.

  • failure_action: Что делать, если обновление не удалось. Один из continue, rollback или pause (по умолчанию: pause).

  • monitor: продолжительность после каждого обновления задачи для отслеживания сбоя (ns|us|ms|s|m|h) (по умолчанию 5 с) Примечание: при значении 0 будет использоваться значение по умолчанию 5 с.

  • max_failure_ratio: Допустимая частота сбоев во время обновления.

  • order: Порядок операций при обновлении. Один из stop-first (старая задача останавливается перед запуском новой) или start-first (новая задача запускается первой, а запущенные задачи ненадолго перекрываются) (по умолчанию stop-first) Примечание: поддерживается только для версии 3.4 и выше.

    Примечание

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

    Параметр order поддерживается только версией 3.4 и выше формата файла compose.

version: "{{ site.compose_file_v3 }}"
services:
  vote:
    image: dockersamples/examplevotingapp_vote:before
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s
        order: stop-first

Не поддерживается для docker stack deploy

Следующие подпараметры (поддерживаются для docker-compose up и docker-compose run) не поддерживаются для docker stack deploy или ключа deploy.

Примечание

См. раздел как настроить тома для сервисов, роев и файлов docker-stack.yml. Тома поддерживаются, но для работы с роями и сервисами они должны быть настроены как именованные тома или связаны с сервисами, которые ограничены узлами с доступом к необходимым томам.

devices

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

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

Примечание

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

Параметр devices игнорируется, если развертывание стека в режиме swarm

dns

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

dns: 8.8.8.8
dns:
  - 8.8.8.8
  - 9.9.9.9

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

Compose также распознает встроенные комментарии, например:

MY_VAR = value # this is a comment

Чтобы избежать интерпретации «#» как встроенного комментария, используйте кавычки:

MY_VAR = "All the # inside are taken as part of the value"

Примечание

Если в вашей службе указана опция 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

Примечание

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

expose

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

expose:
  - "3000"
  - "8000"

external_links

Ссылка на контейнеры начинается за пределами этого docker-compose.yml или даже за пределами Compose, особенно для контейнеров, которые предоставляют общие или общие службы. external_links следует семантике, аналогичной устаревшему параметру links, при указании имени контейнера и псевдонима ссылки (CONTAINER:ALIAS).

external_links:
  - redis_1
  - project_db_1:mysql
  - project_db_1:postgresql

Примечание

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

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

Параметр external_links игнорируется, если развертывание стека в режиме swarm

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

healthcheck

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

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

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

Примечание

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

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

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

Примечание

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

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

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

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

isolation

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

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"

links

Предупреждение

Флаг --link — это устаревшая функция Docker. В конечном итоге он может быть удален. Если вам абсолютно не нужно продолжать использовать его, мы рекомендуем вам использовать определяемые пользователем сети для облегчения связи между двумя контейнерами вместо использования --link.

Одна функция, которую не поддерживают определяемые пользователем сети, которую вы можете реализовать с помощью --link, — это совместное использование переменных среды между контейнерами. Однако вы можете использовать другие механизмы, такие как тома, для более контролируемого обмена переменными среды между контейнерами.

Ссылка на контейнеры в другом сервисе. Либо указывает имя службы и псевдоним ссылки ("SERVICE:ALIAS"), либо просто имя службы.

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

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

Ссылки не требуются для обеспечения взаимодействия служб — по умолчанию любая служба может связаться с любой другой службой по имени этой службы. (См. также Тема ссылок в сети в Compose.)

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

Примечание

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

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

Параметр links игнорируется, когда развертывание стека в режиме swarm

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"

Драйвер по умолчанию json-файл имеет параметры для ограничения объема хранимых журналов. Для этого используйте пару ключ-значение для максимального размера хранилища и максимального количества файлов:

options:
  max-size: "200k"
  max-file: "10"

В приведённом выше примере файлы журналов будут храниться до тех пор, пока они не достигнут max-size размером 200 КБ, а затем будут чередоваться. Количество сохраняемых отдельных файлов журнала определяется значением max-file. По мере того, как журналы превышают максимальные пределы, старые файлы журналов удаляются, чтобы можно было хранить новые журналы.

Вот пример файла docker-compose.yml, который ограничивает хранилище журналов:

version: "{{ site.compose_file_v3 }}"
services:
  some-service:
    image: some-service
    logging:
      driver: "json-file"
      options:
        max-size: "200k"
        max-file: "10"

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

В приведённом выше примере для управления файлами журналов и их размерами используются параметры, характерные для файла драйвер json-файла. Данные конкретные параметры недоступны для других драйверов ведения журнала. Полный список поддерживаемых драйверов ведения журналов и их параметров см. в документации логирование драйверов.

network_mode

Сетевой режим. Используйте те же значения, что и параметр клиента 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

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

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_v3 }}"

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, вы должны сначала убедиться, что демон Docker настроен на поддержку IPv6. Подробные инструкции см. в Включить IPv6. Затем вы можете получает доступ к адресации IPv6 в файле версии 3.x Compose, отредактировав /etc/docker/daemon.json, чтобы он содержал: {"ipv6": true, "fixed-cidr-v6": "2001:db8:1::/64"}

Затем перезагрузите демон docker и отредактируйте файл docker-compose.yml, чтобы он содержал следующее в службе:

sysctls:
  - net.ipv6.conf.all.disable_ipv6=0

Примечание

Опция включить_ipv6 доступна только в версия 2.x файл Compose. Параметры IPv6 в настоящее время не работают в режиме swarm.

Пример:

version: "{{ site.compose_file_v3 }}"

services:
  app:
    image: nginx:alpine
    networks:
      app_net:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  app_net:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"

pid

pid: "host"

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

ports

Выставить порты.

Примечание

Сопоставление портов несовместимо с network_mode: host

docker-compose run игнорирует ports, если вы не включает --service-ports.

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

Есть три варианта:

  • Указывает оба порта (HOST:CONTAINER)

  • Указывает только порт контейнера (в качестве порта хоста выбирается эфемерный порт хоста).

  • Указывает IP-адрес хоста для привязки к И обоим портам (по умолчанию 0.0.0.0, что означает все интерфейсы): (IPADDR:HOSTPORT:CONTAINERPORT). Если HOSTPORT пуст (например, 127.0.0.1::80), для привязки к хосту выбирается эфемерный порт.

Примечание

При сопоставлении портов в формате 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"
  - "127.0.0.1::5000"
  - "6060:6060/udp"
  - "12400-12500:1240"

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

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

  • target: порт внутри контейнера

  • published: общедоступный порт

  • protocol: протокол порта (tcp или udp)

  • mode: host для публикации хост-порта на каждом узле или ingress для порта режима swarm для балансировки нагрузки.

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

Примечание

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

Длинный синтаксис является новым в формате файла v3.2.

profiles

profiles: ["frontend", "debug"]
profiles:
  - frontend
  - debug

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

Допустимые имена профилей соответствуют регулярному выражению в формате [a-zA-Z0-9][a-zA-Z0-9_.-]+.

См. также Использование профилей с Compose, чтобы узнать больше о профилях.

restart

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

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

Примечание

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

Параметр restart игнорируется, если развертывание стека в режиме swarm.

secrets

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

Примечание

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

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

Дополнительные сведения о секретах см. в статье секреты.

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

Опция с коротким синтаксисом указывает только секретное имя. Это предоставляет контейнеру доступ к секрету и монтирует его по адресу /run/secrets/<secret_name> внутри контейнера. И исходное имя, и целевая точка монтирования установлены на секретное имя.

В следующем примере используется короткий синтаксис для предоставления службе redis доступа к секретам my_secret и my_other_secret. Значение my_secret устанавливается равным содержимому файла ./my_secret.txt, а my_other_secret определяется как внешний ресурс, что означает, что он уже определён в Docker либо путём выполнения команды docker secret create, либо путём другого развертывания стека. Если внешний секрет не существует, развертывание стека завершается с ошибкой secret not found.

version: "{{ site.compose_file_v3 }}"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - my_secret
      - my_other_secret
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

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

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

  • source: идентификатор секрета, как он определён в этой конфигурации.

  • target: имя файла, который нужно смонтировать в /run/secrets/ в контейнерах задач службы. По умолчанию source, если не указано иное.

  • uid и gid: числовой UID или GID, которому принадлежит файл в /run/secrets/ в контейнерах задач службы. Оба по умолчанию имеют значение 0, если не указано иное.

  • mode: разрешения на монтирование файла в /run/secrets/ в контейнерах задач службы в восьмеричном представлении. Например, 0444 означает доступный для чтения всем. По умолчанию в Docker 1.13.1 используется 0000, но в более новых версиях это 0444. Секреты не могут быть доступны для записи, потому что они смонтированы во временной файловой системе, поэтому, если вы устанавливает бит, доступный для записи, он будет проигнорирован. Исполняемый бит может быть установлен. Если вы не знакомы с режимами доступа к файлам UNIX, вам может пригодиться данный калькулятор разрешений.

В следующем примере для имени my_secret задается значение redis_secret в контейнере, для режима устанавливается значение 0440 (доступно для чтения группой), а для пользователя и группы задается значение 103. Служба redis не имеет доступа к секрету my_other_secret.

version: "{{ site.compose_file_v3 }}"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - source: my_secret
        target: redis_secret
        uid: '103'
        gid: '103'
        mode: 0440
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

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

security_opt

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

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

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

Параметр security_opt игнорируется, если развертывание стека в режиме swarm.

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

sysctls

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

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

Вы можете использовать только те sysctl, пространство имён которых находится в ядре. Docker не поддерживает изменение sysctl внутри контейнера, которое также изменяет хост-систему. Обзор поддерживаемых sysctl см. в статье настроить параметры ядра с пространством имён (sysctls) во время выполнения.

Примечание

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

Для этого параметра требуется Docker Engine 19.03 или более поздней версии, если развертывание стека в режиме swarm.

tmpfs

Примечание

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

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

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

Примечание

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

Данный параметр игнорируется, когда развертывание стека в режиме swarm с файлом Compose (версия 3-3.5).

Смонтировать временную файловую систему внутри контейнера. Параметр Size указывает размер монтирования tmpfs в байтах. Безлимит по умолчанию.

- type: tmpfs
  target: /app
  tmpfs:
    size: 1000

ulimits

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

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

userns_mode

userns_mode: "host"

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

Примечание

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

Параметр userns_mode игнорируется, если развертывание стека в режиме swarm.

volumes

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

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

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

Примечание

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

Ключ верхнего уровня volumes определяет именованный том и ссылается на него из списка volumes каждой службы. Это заменяет volumes_from в более ранних версиях формата файла Compose.

В этом примере показан именованный том (mydata), используемый службой web, и подключение с привязкой, определённое для одной службы (первый путь в службе db volumes). Служба db также использует именованный том с именем dbdata (второй путь в службе db volumes), но определяет его, используя старый строковый формат для подключения именованного тома. Именованные тома должны быть перечислены под ключом верхнего уровня volumes, как показано.

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

  db:
    image: postgres:latest
    volumes:
      - "/var/run/postgres/postgres.sock:/var/run/postgres/postgres.sock"
      - "dbdata:/var/lib/postgresql/data"

volumes:
  mydata:
  dbdata:

Примечание

Общие сведения о томах см. в разделах использовать тома и плагины томов документации.

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

В коротком синтаксисе используется общий формат [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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

version: "{{ site.compose_file_v3 }}"
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:

Примечание

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

Тома для сервисов, роев и файлов стека

Примечание

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

При работе со службами, роями и файлами docker-stack.yml имейте в виду, что задачи (контейнеры), поддерживающие службу, могут быть развернуты на любом узле в swarm, и это может быть другой узел при каждом обновлении службы.

При отсутствии именованных томов с указанными источниками Docker создаёт анонимный том для каждой задачи, поддерживающей службу. Анонимные тома не сохраняются после удаления связанных контейнеров.

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

Например, файл docker-stack.yml для образец приложения для голосованияв Docker Labs определяет службу с именем db, которая запускает базу данных postgres. Он сконфигурирован как именованный том для сохранения данных на swarm * и * ограничен для работы только на узлах manager. Вот соответствующий отрывок из этого файла:

version: "{{ site.compose_file_v3 }}"
services:
  db:
    image: postgres:9.4
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend
    deploy:
      placement:
        constraints: [node.role == manager]

доменное имя, имя хоста, ipc, mac_address, привилегированный, read_only, shm_size, stdin_open, tty, пользователь, рабочий_dir

Каждое из них представляет собой одно значение, аналогичное его аналогу docker run. Обратите внимание, что mac_address — это устаревшая опция.

user: postgresql
working_dir: /code

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

privileged: 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.

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

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

2b
1024kb
2048k
300m
1gb

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

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

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

Общие сведения о томах см. в статьях использовать тома и плагины томов.

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

version: "{{ site.compose_file_v3 }}"

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 не пытается его создать и вызывает ошибку, если он не существует.

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

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

version: "{{ site.compose_file_v3 }}"

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

volumes:
  data:
    external: true

Примечание

Устарело в формате файла версия 3.4.

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

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

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

Примечание

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

Несуществующие внешние тома создаются, если вы используете развертывание стека докеров для запуска приложения в Режим swarm (вместо докер compose вверх). В режиме swarm том создаётся автоматически, когда он определяется службой. Поскольку задачи обслуживания планируются на новых узлах, swarm комплект создаёт том на локальном узле. Чтобы узнать больше, см. moby/moby#29976.

labels

Добавляет метаданные в контейнеры, используя Ярлыки 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

Примечание

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

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

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

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

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

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

Ключ верхнего уровня networks позволяет указывает создаваемые сети.

driver

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

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

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

driver: overlay

bridge

По умолчанию Docker использует сеть bridge на одном хосте. Примеры работы с мостовыми сетями см. в руководстве Docker Labs по адресу Мостовая сеть.

overlay

Драйвер overlay создаёт именованную сеть на нескольких узлах в файле swarm.

host или none

Используйте сетевой стек хоста или не используйте сеть. Эквивалент docker run --net=host или docker run --net=none. Используется только при использовании команд docker stack. Если вы используете команду docker-compose, вместо этого используйте network_mode.

Если вы хотите использовать определенную сеть в общей сборке, используйте сеть, как указано во втором примере файла yaml.

Синтаксис для использования встроенных сетей, таких как host и none, немного отличается. Определяет внешнюю сеть с именем host или none (которую Docker уже создал автоматически) и псевдонимом, который может использовать Compose (hostnet или nonet в следующих примерах), затем предоставьте службе доступ к этой сети с помощью псевдонима.

version: "{{ site.compose_file_v3 }}"
services:
  web:
    networks:
      hostnet: {}

networks:
  hostnet:
    external: true
    name: host
services:
  web:
    ...
    build:
      ...
      network: host
      context: .
      ...
services:
  web:
    ...
    networks:
      nonet: {}

networks:
  nonet:
    external: true
    name: none

driver_opts

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

driver_opts:
  foo: "bar"
  baz: 1

attachable

Примечание

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

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

networks:
  mynet1:
    driver: overlay
    attachable: true

enable_ipv6

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

Примечание

Не поддерживается в Compose версии файла 3

enable_ipv6 требует, чтобы вы использовали файл Compose версии 2, т. к. эта директива ещё не поддерживается в режиме Swarm.

ipam

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

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

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

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

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

ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16

Примечание

Дополнительные конфигурации IPAM, такие как gateway, на данный момент поддерживаются только для версии 2.

internal

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

labels

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

Рекомендуется использовать обратную 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 не пытается его создать и вызвать ошибку, если он не существует.

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

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

version: "{{ site.compose_file_v3 }}"

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

networks:
  outside:
    external: true

Примечание

Устарело в формате файла версия 3.5.

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

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

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

name

Примечание

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

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

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

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

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

справка по конфигурации конфигов

Объявление configs верхнего уровня определяет или ссылается на конфиги, которое может быть предоставлено службам в этом стеке. Источником конфигурации является либо file, либо external.

  • file: Конфиг создаётся с содержимым файла по указанному пути.

  • external: если установлено значение true, указывает, что эта конфигурация уже создана. Docker не пытается его создать, а если он не существует, вызывается ошибка config not found.

  • name: имя объекта конфигурации в Docker. Это поле можно использовать для ссылки на конфигурации, содержащие специальные символы. Имя используется как есть и не ограничивается именем стека. Представлен в формате файла версии 3.5.

  • driver и driver_opts: имя пользовательского секретного драйвера и специфичные для драйвера параметры, передаваемые в виде пар ключ/значение. Представлен в формате файла версии 3.8 и поддерживается только при использовании docker stack.

  • template_driver: имя используемого драйвера шаблонов, который определяет, следует ли и как оценивать секретную полезную нагрузку в качестве шаблона. Если драйвер не установлен, шаблоны не используются. В настоящее время поддерживается только один драйвер — golang, который использует golang. Представлен в формате файла версии 3.8 и поддерживается только при использовании docker stack. Обратитесь к использовать шаблонную конфигурацию за примерами шаблонных конфигураций.

В этом примере создаётся my_first_config (как <stack_name>_my_first_config) при развертывании стека, а my_second_config уже существует в Docker.

configs:
  my_first_config:
    file: ./config_data
  my_second_config:
    external: true

Другой опция для внешних конфигов — это когда имя конфига в Docker отличается от имени, существующего внутри сервиса. Следующий пример изменяет предыдущий для использования внешней конфигурации с именем redis_config.

configs:
  my_first_config:
    file: ./config_data
  my_second_config:
    external:
      name: redis_config

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

справочник по настройке секретов

Объявление secrets верхнего уровня определяет или ссылается на секреты, которое может быть предоставлено службам в этом стеке. Источником секрета является либо file, либо external.

  • file: секрет создаётся с содержимым файла по указанному пути.

  • external: если установлено значение true, указывает, что данный секрет уже создан. Docker не пытается его создать, и если он не существует, вызывается ошибка secret not found.

  • name: имя секретного объекта в Docker. Это поле можно использовать для ссылки на секреты, содержащие специальные символы. Имя используется как есть и не ограничивается именем стека. Представлен в формате файла версии 3.5.

  • template_driver: имя используемого драйвера шаблонов, который определяет, следует ли и как оценивать секретную полезную нагрузку в качестве шаблона. Если драйвер не установлен, шаблоны не используются. В настоящее время поддерживается только один драйвер — golang, который использует golang. Представлен в формате файла версии 3.8 и поддерживается только при использовании docker stack.

В этом примере my_first_secret создаётся как <stack_name>_my_first_secret при развертывании стека, а my_second_secret уже существует в Docker.

secrets:
  my_first_secret:
    file: ./secret_data
  my_second_secret:
    external: true

Другой опция для внешних секретов — это когда имя секрета в Docker отличается от имени, существующего в сервисе. Следующий пример изменяет предыдущий, чтобы использовать внешний секрет с именем redis_secret.

Compose Файл версии 3.5 и выше

secrets:
  my_first_secret:
    file: ./secret_data
  my_second_secret:
    external: true
    name: redis_secret

Compose Файл версии 3.4 и далее

my_second_secret:
  external:
    name: redis_secret

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

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

Ваши параметры конфигурации могут содержать переменные среды. 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.

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

Примечание

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

Можно повторно использовать фрагменты конфигурации, используя поля расширения. Данные специальные поля могут иметь любой формат, если они расположены в корне вашего файла 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