Compose.yaml: полное руководство по структуре и возможностям Docker Compose

Файл compose.yaml — это центральный элемент Docker Compose, позволяющий одной командой поднять многоконтейнерное приложение. В нём описываются все сервисы, сети, тома и прочие ресурсы. Понимание его структуры и правил слияния необходимо для создания надёжных и переносимых конфигураций. В этой статье

Что такое compose.yaml и зачем он нужен

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

Официальная спецификация Compose File (сейчас актуальна версия 3.8 для Docker Compose v1 и версия 2 для Compose v2) определяет строгую структуру. Основные top-level разделы: version, services, networks, volumes, configs, secrets. Каждый из них имеет свои атрибуты и правила. Понимание этой структуры — ключ к созданию надёжных и переносимых конфигураций.

Предыстория и контекст

Docker Compose появился как ответ на необходимость управлять сложными приложениями, состоящими из нескольких контейнеров. Раньше разработчики запускали каждый контейнер вручную через docker run, что было медленно и чревато ошибками. Compose позволил декларативно описывать всю инфраструктуру в одном файле, который можно версионировать и переиспользовать.

Со временем формат файла эволюционировал. В версии 3 появилась поддержка Docker Swarm, в версии 2 — улучшенная работа с сетями и volumes. Сейчас Compose v2 (часть Docker CLI) активно вытесняет старый docker-compose, но файлы конфигурации остаются обратно совместимыми. Основные изменения коснулись синтаксиса: например, убрали поле version (оно стало необязательным), а некоторые атрибуты перешли из корневого уровня в сервисы.

Как устроен top-level раздел services

Раздел services — это ядро compose.yaml. Каждый сервис описывает один контейнер или группу контейнеров (если используется репликация). Внутри сервиса вы указываете образ, порты, переменные окружения, команды, volumes, сети и другие параметры. Например, типичный сервис веб-приложения может выглядеть так:

yaml services: web: image: nginx:latest ports: - "80:80" volumes: - ./html:/usr/share/nginx/html networks: - frontend

Здесь мы говорим Compose: запусти контейнер на основе образа nginx, пробрось порт 80, смонтируй локальную папку html в контейнер и подключи сеть frontend. Все эти атрибуты имеют свои правила: например, volumes можно указывать как кратко (source:destination), так и развёрнуто с дополнительными опциями (тип, права доступа).

Технические подробности: сети, тома и правила слияния

Сети в compose.yaml описываются в разделе networks. Вы можете создавать изолированные сети для разных групп сервисов — например, frontend и backend сети, чтобы разделить доступ. Каждая сеть может быть драйвером bridge (по умолчанию), overlay (для Swarm) или macvlan. Также можно указать параметры IPAM, подсети и шлюзы.

Тома (volumes) — это постоянное хранилище данных, которое переживает перезапуск контейнеров. В разделе volumes вы объявляете именованные тома, а затем подключаете их к сервисам. Bind mount (привязка к папке на хосте) тоже возможны, но их лучше использовать для разработки, а не для продакшена.

Один из самых сложных моментов — правила слияния (merge) конфигураций. Если вы используете несколько Compose-файлов (через -f), Docker Compose объединяет их по определённым правилам. Например, списки портов или volumes объединяются, а не заменяются. Но есть нюансы: для некоторых атрибутов (например, command) действует замена, а не слияние. Чтобы избежать неожиданностей, всегда проверяйте итоговую конфигурацию через docker-compose config.

Как правильно описать зависимости между сервисами в compose.yaml

Зависимости между сервисами задаются через атрибут dependson. Он указывает порядок запуска: сначала запускаются зависимые сервисы, потом текущий. Однако dependson не гарантирует, что сервис будет готов принимать соединения — для этого нужны healthcheck и condition. Например:

yaml services: web: dependson: db: condition: servicehealthy

Это заставит Compose ждать, пока сервис db не пройдёт healthcheck. Такой подход особенно важен для баз данных и кэшей, которым нужно время на инициализацию.

Кого затронет и как

Эта статья будет полезна всем, кто работает с Docker Compose: от новичков, которые только начинают разбираться с контейнерами, до опытных DevOps, которые хотят углубить знания о тонкостях формата. Разработчики смогут писать более чистые и предсказуемые конфигурации, а администраторы — быстрее находить ошибки в развёртывании.

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

Что будет дальше

Docker продолжает развиваться, и формат Compose-файла тоже не стоит на месте. В будущих версиях ожидается более глубокая интеграция с Kubernetes, поддержка новых типов ресурсов и улучшенная обработка ошибок. Рекомендуется следить за официальным репозиторием спецификации на GitHub и обновлять свои конфигурации по мере выхода новых версий.

Итог

Compose.yaml — мощный инструмент, который при правильном использовании значительно упрощает управление контейнеризированными приложениями. Знание его структуры, топ-левел разделов и правил слияния — обязательный навык для любого, кто работает с Docker. Держите эту статью под рукой как шпаргалку и возвращайтесь к ней, когда понадобится быстро найти нужный атрибут или разобраться в неочевидном поведении.