Docker compose file reference

Теги: docker 

Compose file version 3 reference

example

version: "3.9"
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:

Структура

Часть параметров можно записывать с полным синтаксисом, часть - в виде сокращенного.

  • build Параметры конфигурации, которые применяются во время сборки.
    • context - либо путь к каталогу, содержащему Dockerfile, либо URL-адрес репозитория git
    • dockerfile - альтернативный докерфайл
    • args - аргументы сборки, которые являются переменными среды, доступными только во время процесса сборки
    • cache_from - список имеджей, которые движок использует для разрешения кеша
    • labels - метадата в виде docker labels
    • network - сетевые контейнеры, к которым подключаются инструкции RUN во время сборки
    • shm_size - размер раздела /dev/shm для контейнеров этой сборки
    • target - создает этап для многоэтапной сборки
  • cap_add, cap_drop - опции контейнера (игнорируется в [docker-swarm] моде)
  • cgroup_parent контрольная группа контейнеров (игнорируется в сварм-моде)

  • command можно переопределить команду по умолчанию

      command: bundle exec thin -p 3000

  • configs. Доступ к конфигурациям для каждой службы с помощью конфигурации для каждой службы. Оба варианта синтаксиса

    configs configuration reference

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

  • depends_on - зависимость от другого контейнера. Контейнеры поднимутся в порядке установленных зависимостей.

    • docker-compose up starts services in dependency order.
    • docker-compose up SERVICE automatically includes SERVICE’s dependencies.
    • docker-compose stop stops services in dependency order.

    Установление зависимостей не ожидает готовности чего либо внутри контейнера. Опция игнорируется в сорм-моде.

  • deploy - конфигурация, связанная с развертыванием и запуском служб. Подпараметры вступают в силу только при развертывании в swarm через docker stack deploy и игнорируются при запуске docker-compose up и docker-compose, за исключением resources
    • endpoint_mode метод обнаружения службы для внешних клиентов, подключающихся к swarm
    • labels эти метки устанавливаются только для службы, а не для каких-либо контейнеров службы
    • mode тип контейнера в сворме
    • placement размещение ограничений и предпочтений
    • max_replicas_per_node
    • replicas количество контейнеров, которые должны быть запущены в любой момент времени
    • resources - квоты ресрусов (ЦПУ, память)
    • restart_policy как перезапускать контейнеры при выходе. Заменяет restsrt
    • rollback_config как следует выполнить откат службы в случае неудачного обновления

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

      Не поддерживается:

      • build
      • cgroup_parent
      • container_name
      • devices
      • tmpfs
      • external_links
      • links
      • network_mode
      • restart
      • security_opt
      • userns_mode
  • devices. Список сопоставлений устройств. Использует тот же формат, что и параметр создания клиента docker --device.
  • dns. Пользовательские DNS-серверы
  • dns_search. Пользовательские домены DNS

  • entrypoint. Переопределяет точку входа по умолчанию (если в Dockerfile есть инструкция CMD, она тоже игнорируется).

      entrypoint: /code/entrypoint.sh

  • env_file. Переменные окружения из файла. Переменные среды, объявленные в environment, переопределяют эти значения — это остается истинным, даже если эти значения пусты или не определены. Порядок задания списка файлов имеет значение - файлы в списке обрабатываются сверху вниз

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

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

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

    так:

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

    или так:

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

    Аналогично - эти переменные не видны автоматически в build - нужно задать args

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

      expose:
    - "3000"
    - "8000"
  • external_links. Ссылка на контейнеры, запущенные за пределами этого docker-compose.yml или даже за пределами Compose, особенно для контейнеров, которые предоставляют общие службы. Контейнеры, созданные извне, должны быть подключены по крайней мере к одной из тех же сетей, что и служба, которая на них ссылается. Игнорируется в сворме.
  • extra_hosts. Сопоставления имен хостов. Используйте те же значения, что и в параметре клиента docker --add-host

  • healthcheck. Настройка проверки, которая запускается, чтобы определить, являются ли контейнеры для этой службы «работоспособными»

      healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 40s
  • image. Jбраз, с которого будет запускаться контейнер. Может быть либо репозиторием/тегом, либо ID образа
  • init. Запускает init внутри контейнера для передачи сигналов и запуска процессов.
  • isolation. Технология изоляции контейнера. В Linux поддерживается только значение по умолчанию. В Windows допустимыми значениями являются значения default, process и hyperv
  • labels
  • links. Ссылка на контейнеры в другом сервисе. Легаси. Использовать external_links. Игнорируется в сворм-моде.
  • logging. Конфигурации логгирования внутри контейнера
  • network_mode. Сетевой режим. Используйте те же значения, что и параметр docker client --network, а также специальную форму service:[service name]. Игнорируется свормом.

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

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

    Конфигурация для network

    Руководство по сетиям в compose

    • aliases. Псевдонимы (альтернативные имена хостов) для этой службы в сети. Другие контейнеры в той же сети могут использовать либо имя службы, либо этот псевдоним для подключения к одному из контейнеров службы.
    • ipv4_address, ipv6_address Статический IP-адрес для контейнеров для этой службы при подключении к сети
  • pid. Устанавливает режим PID в режим PID хоста. Это включает совместное использование контейнером и операционной системой хоста адресного пространства PID.

  • ports. Открывает порты. Поддерживает короткий и длинный синтаксис. Можно задавать диапазоны.

    Короткий:

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

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

      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: хост для публикации порта хоста на каждом узле или вход для порта в режиме сворма для балансировки нагрузки.

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

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

      profiles: ["frontend", "debug"]
  profiles:
  - frontend
  - debug
  • restart. Политика перезапуска. no — это политика перезапуска по умолчанию, и она не перезапускает контейнер ни при каких обстоятельствах. Если указано always, контейнер всегда перезапускается. Политика on-failure перезапускает контейнер, если код выхода указывает на ошибку при отказе. unless-stopped всегда перезапускает контейнер, за исключением случаев, когда контейнер остановлен (вручную или иным образом). Игнорируется в сворме.

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

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

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

      version: "3.9"
  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/ в контейнерах задач службы. По умолчанию используется источник, если он не указан.
    • uid и gid: числовой UID или GID, которому принадлежит файл в /run/secrets/ в контейнерах задач службы. Оба значения по умолчанию равны 0, если не указано иное.

    • mode разрешения для файла, который будет смонтирован в /run/secrets/ в контейнерах задач службы, в восьмеричном представлении.

      version: "3.9"
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

      Еще пример

      version: '3'

secrets:
db_user:
    external: true
db_password:
    external: true

services:
postgres_db:
image: postgres
secrets:
    - db_user
    - db_password
environment:
    - POSTGRES_USER_FILE=/run/secrets/db_user
    - POSTGRES_PASSWORD_FILE=/run/secrets/db_password

      Конфигурация secrets

  • security_opt. Схема маркировки по умолчанию для каждого контейнера. Игнорируется в сворме.
  • stop_grace_period. Как долго ждать при попытке остановить контейнер, если он не обрабатывает SIGTERM (или любой другой сигнал остановки, указанный с помощью stop_signal), перед отправкой SIGKILL.
  • stop_signal. Устанавливает пользовательский сигнал для остановки контейнера.
  • sysctls. Параметры ядра для установки в контейнере
  • tmpfs. Расположение монитруемых внутри контейнера временных файловых систем.
  • ulimits
  • userns_mode. Отключает пространство имен пользователей для этой службы, если демон Docker настроен с пространствами имен пользователей. Игнорируется в сворме.

  • volumes. Пути хоста или именованные тома, заданные как подопции к службеДоступно оба синтаксиса.

    Тома можно смонтировать на уровне службы. Это полезно так-же чтобы использовать том в нескольких службах.

      version: "3.9"
  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:

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

    Подробнее о томах и в docker plugins

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

      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

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

    • type: тип монтирования bind, tmpfs или npipe
    • source: источник монтирования, путь на хосте для монтирования. Или имя тома, определенное в ключе томов верхнего уровня. Неприменимо для монтирования tmpfs.
    • target: путь в контейнере, куда смонтирован том
    • read_only: флаг, чтобы сделать том доступным только для чтения
    • bind: настроить дополнительные параметры связывания
      • propagation: режим распространения, используемый для привязки
    • volume: настроить дополнительные параметры тома
      • nocopy: флаг для отключения копирования данных из контейнера при создании тома
    • tmpfs: настроить дополнительные параметры tmpfs
      • size: размер монтирования tmpfs в байтах
      version: "3.9"
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 помните, что контейнеры, поддерживающие сервис, могут быть развернуты на любом узле, и каждый раз при обновлении сервиса это может быть другой узел.

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

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

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

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

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

      version: "3.9"

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

volumes:
    data-volume:

      Параметры:

      • driver. Укажите, какой драйвер тома следует использовать для этого тома. По умолчанию используется любой драйвер, который был настроен для использования Docker Engine, который в большинстве случаев является локальным
      • driver_opts. Список параметров драйвера.

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

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

          version: "3.9"

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

  volumes:
      data:
          external: true
      • labels
      • name. Задайте собственное имя для этого тома. Поле имени можно использовать для ссылки на тома, содержащие специальные символы. Имя используется как есть и не будет ограничиваться именем стека.

  • domainname, hostname, ipc, mac_address, privileged, read_only, shm_size, stdin_open, tty, user, working_dir. Каждое из них представляет собой одно значение, аналогичное его аналогу вщслук кгт. Обратите внимание, что 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

Переменные в compose

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

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

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

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

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

Для использования знака $ или экранирования переменных используйте $$

Дополнительные поля

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

version: "3.9"
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

Смотри еще: