Docker Compose: профили для выбора сервисов

Иллюстрация: схема профилей в Docker Compose

Профили в Docker Compose позволяют селективно запускать наборы сервисов в одном файле docker-compose.yml. Используйте флаг –profile или переменную окружения COMPOSE_PROFILES, чтобы включать подстеки для разработки, тестирования или альтернативных конфигураций без разделения на несколько файлов. Это упрощает локальную разработку и управление средами.

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

Зачем использовать профили?
Что такое профили и как их определить
Неявный запуск сервисов с профилями
Когда профили не подходят
Примеры и шпаргалка команд
Чек-листы по ролям
Советы по совместимости и миграции
Итоги

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

Профили — опциональная возможность. Существующие Compose-файлы продолжают работать как прежде. Профили решают распространённые неудобства при разработке и тестировании:

В development могут быть контейнеры для отладки, логирования или вспомогательных задач, которые не нужны в production.
Раньше приходилось поддерживать несколько файлов docker-compose и запускать их вместе через множественные флаги -f, что неудобно и легко забывается.
Профили позволяют определить вариативность стека внутри одного YAML, облегчая документирование и запуск.

Важно

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

Что такое профили и как их определить

Профили создаются указанием поля profiles у сервиса в вашем docker-compose.yml. Значение profiles — список имён профилей. Один сервис может принадлежать нескольким профилям.

Пример минимального Compose-файла с профилями:

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

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

Если выполнить:

docker-compose up --profile dev

то будут запущены оба сервиса app и debug. Команда без флага –profile запустит только app, потому что у него нет связанного профиля.

Вы также можете указать несколько профилей повторно:

docker-compose up --profile dev --profile metrics

Альтернативно можно задать переменную окружения COMPOSE_PROFILES:

export COMPOSE_PROFILES=dev,metrics
docker-compose up

Правила поведения

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

Неявный запуск сервисов с профилями

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

запустит debug и debug-utils, даже если профиль dev не был выбран через –profile или COMPOSE_PROFILES. Это поведение применяется только к прямым зависимостям: если debug-utils зависит от ещё одного сервиса, который не разделяет профиль dev и не всегда включён, этот третий сервис не будет запущен автоматически.

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

Важно

Не забывайте, что docker-compose up учитывает профили, а docker-compose run — нет. Планируйте архитектуру зависимостей исходя из этой разницы.

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

Профили удобны, но не всегда оптимальны. Рассмотрите альтернативы в таких случаях:

Нужна полная изоляция конфигураций окружений, включая разные версии образов или изменённые сети — лучше использовать несколько файлов docker-compose и отдельные переменные окружения.
Требуется строгое управление секретами и политиками безопасности между средами — отдельные конфигурации с разной системой управления секретами предпочтительнее.
У вас CI/CD, где конвейер ожидает конкретные файлы с фиксированными именами — интеграция профилей может требовать адаптации пайплайна.

Контрпример

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

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

Несколько файлов docker-compose.yml и docker-compose.override.yml — классический способ переопределения.
Шаблонизаторы (envsubst, jinja2, yq) для генерации итогового Compose-файла.
Инфраструктурный код: Helm для Kubernetes, Terraform для облачных сервисов или Docker Stacks для Swarm.
Использовать переменные окружения и условные конфигурации внутри Compose, когда различия минимальны.

Ментальные модели и эвристики

Профиль = набор вспомогательных или альтернативных сервисов, не обязательных для базовой работы приложения.
Всегда включённый сервис = core-сервис приложения, без которого стек не работает.
Dev-профили обычно содержат инструменты разработки и тестирования. Production-профили редко используются — в бою лучше иметь минимальный стек.

Короткая подсказка

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

Примеры и шпаргалка команд

Запустить профиль dev:

docker-compose up --profile dev -d

Запустить сразу несколько профилей:

docker-compose up --profile dev --profile metrics

Использовать переменную окружения:

export COMPOSE_PROFILES=dev,metrics
docker-compose up -d

Запустить сервис напрямую (профили игнорируются):

docker-compose run --rm debug

Пример более сложного файла с несколькими профилями:

version: '3'
services:
  web:
    image: example/web:latest

  redis:
    image: redis:6

  metrics:
    image: prom/prometheus
    profiles:
      - monitoring

  debug-shell:
    image: busybox
    profiles:
      - dev
      - debug

Чек-листы по ролям

Разработчик

Создать профиль dev для инструментов отладки.
Документировать команду запуска в README.
Использовать COMPOSE_PROFILES в локальных скриптах запуска.

QA-инженер

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

Операции

В production не включать профили для ненужных сервисов.
Поддерживать отдельный набор переменных окружения для продакшена.

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

Профили появились в Docker Compose 1.28. Убедитесь, что бинарь Compose на вашей машине или в CI версии 1.28 или новее. В Docker Desktop для Windows и Mac современные выпуски уже включают поддержку.
Если ваша команда использует старые версии Compose, сначала добавьте проверку версии в скрипты CI и локальные скрипты запуска.
При миграции от множества файлов к профилям постепенно переносите сервисы в единый файл и тестируйте каждый профиль по отдельности.
Для обратной совместимости можно оставить docker-compose.override.yml для наиболее частых локальных переопределений, постепенно переходя на профили.

Миграционные шаги

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

Диаграмма принятия решения

flowchart TD
  A{Нужно ли разделять конфигурации?} -->|Да, разные версии образов или сети| B[Использовать отдельные файлы]
  A -->|Нет, только вспомогательные сервисы| C[Использовать профили]
  C --> D{CI/CD требует фиксированных файлов?}
  D -->|Да| B
  D -->|Нет| E[Перейти на профили и обновить документацию]

Шаблон проверки изменений (SOP)

Изменения в docker-compose.yml проходят код-ревью.
Новые профили документируются с примером запуска.
CI проверяет: запуск без профилей, запуск с каждым новым профилем, docker-compose run для тестовых сценариев.

Примеры тест-кейсов

Запуск без профилей должен поднимать только core-сервисы.
Запуск с профилем dev должен включать debug-инструменты.
docker-compose run для сервисов с профилями должен запускать их зависимости, которые не имеют профилей, а также зависимости с тем же профилем.

Частые ошибки и как их избежать

Ошибка: забыли активировать профиль в CI. Решение: явно задать COMPOSE_PROFILES в пайплайне.
Ошибка: сервис зависим от сервиса, который у него нет в том же профиле. Решение: реорганизовать зависимости или сделать зависимый сервис всегда включённым.

Итоги

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

Ключевые идеи

Профили управляют опциональными сервисами внутри одного YAML.
Используйте –profile или COMPOSE_PROFILES для активации профилей.
docker-compose run игнорирует профили при запуске указанного сервиса, но стартует совместимые зависимости.
Проверяйте версию Compose и поэтапно мигрируйте при необходимости.

Примечание

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