Профили Docker Compose: запускать только нужные сервисы

Диаграмма: использование профилей в Docker Compose

Быстрые ссылки

Почему использовать профили?
Определение профилей
Неявные старты профиля
Когда профили не подходят
Краткая сводка

Почему использовать профили?

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

Ранее приходилось разделять определения сервисов по нескольким docker-compose.yml-файлам и запускать их вместе командой с множеством флагов -f. Это усложняло документацию и процесс запуска. Профили позволяют держать все в одном файле и выбирать, какие сервисы запускать.

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

Определение профилей

Профили задаются в поле profiles у каждого сервиса в вашем docker-compose.yml. Поле принимает список. Сервис может принадлежать одному или нескольким профилям.

Пример:

version: "3"
services:
  app:
    image: my-app:latest

  debug:
    image: my-app-debug:latest
    profiles:
      - dev

Профили создаются неявно из имён, перечисленных в profiles. Сервисы, которые разделяют имя профиля, автоматически объединяются в один набор.

Чтобы запустить сервисы определённого профиля, используйте флаг –profile:

docker-compose up --profile dev

Эта команда запустит оба сервиса из примера: app (если у него нет profiles или он назначен на все) и debug (поскольку он в профиле dev). Если вызвать docker-compose up без –profile, будут запущены только сервисы без указанного profiles.

Можно указать несколько профилей, повторяя флаг –profile несколько раз. Альтернативно используется переменная окружения COMPOSE_PROFILES со списком, разделённым запятыми.

Правило: сервисы без поля profiles всегда запускаются вне зависимости от выбранных профилей. Сервисы с профилем запускаются только при явном запросе этого профиля. Если сервис имеет несколько профилей, запрос любого из них разрешит запуск сервиса.

Неявные старты профиля

Если вы запускаете сервис вручную через docker-compose run, Compose не будет учитывать профили. В этом случае Compose автоматически запустит зависимости указанного сервиса, если они либо не имеют профиля, либо разделяют профиль верхнего сервиса.

Пример:

version: "3"
services:
  app:
    image: my-app:latest

  debug-utils:
    image: my-app-debug-utils:latest
    profiles:
      - dev

  debug:
    image: my-app-debug:latest
    depends_on:
      - debug-utils
    profiles:
      - dev

Если выполнить docker-compose run debug, Compose запустит debug-utils и debug, даже если профиль dev не был выбран через –profile. Это происходит, потому что debug запрошен вручную, и его зависимости нужны для корректной работы.

Ограничение: неявные старты применяются только к прямым зависимым сервисам. Если debug-utils имеет свою зависимость, и она не принадлежит тому же профилю и не включена постоянно, зависимость не запустится автоматически.

Чтобы разрешить зависимостям корректный запуск при использовании run, все сервисы в дереве зависимостей должны принадлежать тому же профилю, что и верхний сервис, либо быть постоянно включёнными. В противном случае добавьте –profile при запуске, чтобы явно активировать дополнительные профили.

Когда профили не подходят

Важно понимать ограничения и контрпримеры, где профили не решат задачу:

Если вы хотите, чтобы одна и та же служба имела разные конфигурации (например, разные переменные окружения, команды или тома) в dev и prod, профили сами по себе не переключают настройки сервиса — они только включают/выключают запуск. В таких случаях используйте отдельные override-файлы (-f) или шаблонизацию конфигурации.
Если ваша CI/CD-пайплайн жёстко ожидает одинаковые имена сервисов и одинаковую структуру сети, добавление профилей может потребовать согласования пайплайна, чтобы он явно активировал нужные профили.
Для сложной условной логики построения образов, переменных окружения или секретов профиль не заменит внешней оркестрации или инструментов шаблонизации (например, Helm, Ansible, или envsubst).

Альтернативные подходы

Если профили не подходят, рассмотрите:

Множественные файлы Compose: docker-compose.yml + docker-compose.override.yml + docker-compose.prod.yml. Плюс: явная дифференциация конфигураций. Минус: поддержание нескольких файлов.
Шаблонизация Compose (envsubst, yq, jinja2): генерировать конкретные docker-compose.yml для каждого окружения.
Использование более мощных оркестраторов (Kubernetes, Nomad) для продакшена и Compose для локальной разработки.

Пошаговая методика внедрения профилей

Проанализируйте сервисы: какие нужны всегда (ядро), какие — только в разработке, тестировании или CI.
Добавьте profiles: пометьте вспомогательные сервисы как dev, test, debug и т. п.
Тестируйте локально: запустите docker-compose up и docker-compose up –profile dev. Убедитесь, что ядро запускается без профилей.
Обновите документацию и скрипты запуска (Makefile, CI). Добавьте примеры с COMPOSE_PROFILES.
Проверяйте зависимости: запустите docker-compose run для ключевых сценариев и проверьте неявные старты.
Постепенно переносите CI/CD на явный вызов –profile, если это необходимо.

Контрольные списки по ролям

Разработчик:

Проверить, что локальный debug-сервис помечен профилем.
Запустить: docker-compose up –profile dev.
Убедиться, что основные сервисы стартуют без –profile.

Инженер CI:

Обновить задания, чтобы явно включать нужные профили в тестах.
Автоматизировать COMPOSE_PROFILES в среде сборки.

Оператор/DevOps:

Проверить совместимость версий Compose на проде. Профили появились в Docker Compose 1.28.
Документировать команды и поведение при ручном run.

Фактовая справка

Когда добавлены: профили появились в Compose начиная с версии 1.28.
Как активировать: –profile или COMPOSE_PROFILES=”name1,name2”.
Поведение зависимостей: run игнорирует профили, но запускает зависимости по дереву, если они совместимы.

Краткие определения

Профиль: тэг для сервиса в docker-compose.yml, который управляет его запуском.
Неявный старт: автоматический запуск зависимых сервисов при docker-compose run.

Советы по миграции и совместимости

Проверьте версию docker-compose или Docker Desktop: профили поддерживаются в современных выпусках (после 1.28). Если ваша среда старше, обновите бинарь.
Если у вас CI с фиксированными образами Compose, добавьте явную установку версии или используйте docker/compose контейнер.
Для команд с -f переход на профили позволяет упростить скрипты, но протестируйте сценарии rollback.

Важно: не все инструменты и плагины умеют работать с профилями — проверьте интеграции (IDE-плагины, GUI-инструменты администратора).

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

Обычный файл с профилем dev:

version: "3"
services:
  app:
    image: my-app:latest

  db:
    image: postgres:13

  debug:
    image: my-app-debug:latest
    profiles:
      - dev

Запускы:

production (по умолчанию):

docker-compose up -d

development:

docker-compose up --profile dev -d
# или
COMPOSE_PROFILES=dev docker-compose up -d

Критерии приёмки

Ядро приложения запускается без указания профиля.
Дополнительные сервисы запускаются при активации соответствующего профиля.
CI-пайплайн может воспроизвести локальные запуски с нужными профилями.
Документация обновлена и содержит команды примера для dev и prod.

Когда профили помогут сообществу

Профили позволяют создавать варианты популярных стеков. Например, один docker-compose.yml для WordPress может содержать профили mysql и mariadb. Меняя профиль, вы переключаете движок базы данных без правки файла.

Заключение

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

Краткое объявление: если у вас обновлённый Compose (>=1.28) или Docker Desktop, начните использовать profiles, чтобы упростить запуск вспомогательных сервисов в локальной разработке.