Полное руководство по обновлению на Docker Compose v2

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

• Что нового в v2?
• Несовместимости с v1
• Обновление на Linux
• Обновление в Docker Desktop для Windows и Mac
• Что дальше?
• Резюме
• План миграции и контрольные списки
• Таблица совместимости
• Матрица рисков и смягчения
• FAQ

Что нового в v2?

Docker Compose v2 приносит привычный функционал Compose напрямую в CLI Docker. Вместо отдельного бинарника docker-compose теперь используется команда docker compose. Интеграция делает поведение более согласованным с остальным Docker CLI.

Ключевые изменения в командном интерфейсе — простая подстановка:

$ docker-compose up -d

заменяется на

$ docker compose up -d

Новые и улучшенные возможности:

• Копирование файлов между хостом и контейнерами: docker compose cp.
• Деплой в облачные сервисы: теперь целями могут быть провайдеры, такие как Amazon ECS или Microsoft ACI, что позволяет запускать docker compose up для удалённого деплоя.
• Профили сервисов: выборочная включённость контейнеров в стек для локальной разработки и CI.
• Более гибкое управление проектами: команды можно запускать вне каталога с docker-compose.yml с помощью docker compose --project-name my-project stop, а новая команда docker compose ls показывает все проекты Compose.
• Compose переписан на Go и теперь использует общий код с основным Docker CLI для более предсказуемого поведения.

Важно: терминология и поведение остались близкими к v1, но интеграция в Docker CLI открывает новые варианты использования и автоматизации.

Несовместимости с v1

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

1. Имена контейнеров используют дефисы вместо подчёркиваний

• Раньше контейнер сервиса db в проекте app назывался app_db. В v2 он станет app-db.
• Возможные последствия: скрипты, регулярные выражения, мониторинг или политики, которые завязаны на формате имени, могут перестать работать.
• Временное решение: для обратной совместимости можно использовать флаг --compatibility (где он поддерживается) или адаптировать ваши скрипты.

2. Сборка по умолчанию через BuildKit

• docker compose build использует BuildKit по умолчанию. BuildKit быстрее и мощнее, но остаются несколько отличий от старого сборщика.
• Если у вас есть специфичные Dockerfile-паттерны или нестандартные хуки, протестируйте сборку под BuildKit.
• Отключение BuildKit: перед запуском команд установите переменную окружения DOCKER_BUILDKIT=0.

3. Удаление устаревших флагов и замен команд

• docker compose rm --all больше не поддерживается; вместо этого используйте эквивалентные комбинации команд или обновите скрипты.
• docker compose scale убрана в пользу docker compose up --scale.
• Рекомендуется просмотреть CI/CD и вспомогательные скрипты на предмет старых флагов и команд.

Совет: сначала тестируйте в изолированной среде (CI, staging), затем применяйте изменения в продуктиве.

Обновление на Linux

Compose v2 поставляется как плагин CLI Docker. Требуется Docker Engine версии v20.10.13 или новее.

Шаги установки (пример для Debian/Ubuntu-подобных систем):

$ sudo apt update
$ sudo apt install docker-compose-plugin

Проверка установки:

$ docker compose version

Ожидаемый результат: версия Docker Compose v2.x.x (например, v2.3.3).

Если вы хотите удалить Compose v1 — обычно это один бинарник /usr/local/bin/docker-compose:

$ sudo rm /usr/local/bin/docker-compose

Альтернатива: оставить v1 и настроить алиас, чтобы существующие скрипты продолжали работать:

$ echo 'alias docker-compose="docker compose"' >> ~/.bashrc
$ source ~/.bashrc
$ docker-compose version

Рекомендация: держать v1 и v2 рядом временно, пока вы не убедитесь, что всё в порядке.

Обновление в Docker Desktop для Windows и Mac

Compose v2 включён в Docker Desktop, начиная с версий 3.4+. В версиях Docker Desktop 4.4.2 и новее v2 используется по умолчанию.

В Desktop v4.4.2 docker-compose автоматически алиасится на docker compose. Если нужно вернуть старое поведение, выполните:

$ docker-compose disable-v2

Или снимите галочку «Use Docker Compose v2» в настройках Docker Desktop.

Замечание: на Windows/Mac обычно достаточно обновить Docker Desktop до рекомендованной версии и проверить настройки.

Что дальше?

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

Возможности продления работы с v1:

• Установка v1 как отдельного бинарника — он будет работать, но не получать новых функций.
• Лучший путь — адаптировать проекты к v2 и использовать преимущества интеграции и новых возможностей.

План миграции и контрольные списки

Ниже — практический план, который можно использовать как SOP для поэтапного перехода.

Пошаговый план миграции (микро-SOP)

1. Инвентаризация

• Найдите все скрипты, CI-пайплайны и инструменты, которые вызывают docker-compose напрямую.
• Зафиксируйте используемые версии Docker Engine и Docker Desktop.

2. Тестирование локально

• Установите docker compose рядом с docker-compose или включите v2 в Docker Desktop.
• Запустите полную сборку и интеграционные тесты в ветке feature.

3. Исправления и адаптация

• Обновите скрипты: замените docker-compose на docker compose или добавьте алиас.
• Исправьте регулярные выражения и фильтры, завязанные на формате имени контейнера.
• Прогоните сборки под BuildKit; при необходимости временно отключите BuildKit через DOCKER_BUILDKIT=0.

4. CI и staging

• Обновите образы CI: добавьте плагин docker-compose-plugin или обновите runner до Docker Engine ≥ v20.10.13.
• Прогоните тесты производительности и долгосрочной устойчивости.

5. Ролл-аут в прод

• Мигрируйте по одному сервису/кластера, контролируя метрики и логи.
• Держите план отката: восстановление старой версии Docker Desktop или повторная установка бинарника v1.

6. Деактивация совместимости

• После успешного перехода удалите алиасы и --compatibility обходы, чтобы полноценно использовать v2.

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

Разработчик

• Обновить локальный Docker Desktop или установить плагин на Linux.
• [ ] Проверить, что docker compose up поднимает стек локально.
• Тесты на сборку и интеграцию проходят под BuildKit.
• Исправить скрипты, завязанные на именах контейнеров.

Инженер по доставке/CI

• Обновить образы runner/агентов до Docker Engine ≥ v20.10.13.
• [ ] Установить docker-compose-plugin на CI-агентах.
• Прогнать весь CI-поток: сборка, тесты, публикация артефактов.

Оперейшнс/инженер по развёртыванию

• Проверить совместимость с оркестратором (ECS/ACI), если используется удалённый деплой.
• Обновить документацию поддержки и runbook.
• Подготовить план отката и мониторинг на время миграции.

Инженер по безопасности

• Проверить влияние BuildKit на процессы безопасности сборки.
• Убедиться, что политики имён контейнеров и лейблы соответствуют требованиям.
• Просмотреть доступность бинарников v1 и план их удаления.

Таблица совместимости

Матрица рисков и смягчения

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

• Все CI-пайплайны проходят без ошибок в ветке миграции.
• Приложение успешно разворачивается в staging с помощью docker compose up.
• Мониторинг собирает метрики и логи как ожидается (имена контейнеров/лейблы не нарушают парсинг).
• Документация обновлена и команда уведомлена о новых командах и поведении.

Тесты и критерии проверки

1. Проверка базового старта

• Шаги: docker compose up -d для всего стека.
• Ожидаемо: все сервисы переходят в состояние healthy/Up.

2. Проверка сохранения данных

• Шаги: остановить контейнер, удалить, поднять снова; проверить тома.
• Ожидаемо: данные на томах сохраняются.

3. Проверка сборки образа

• Шаги: docker compose build с обычным Dockerfile.
• Ожидаемо: сборка проходит; если нет — попробовать DOCKER_BUILDKIT=0 docker compose build.

4. Интеграционные тесты

• Шаги: запустить тесты, которые взаимодействуют с сервисами в контейнерах.
• Ожидаемо: тесты проходят в CI и локально.

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

• Продвинуться поэтапно: оставить v1 на старых окружениях и переводить кластеры один за другим.
• Использовать алиасы на уровне оболочки или обёртки в CI, чтобы минимизировать изменения в кодовой базе.
• Рассмотреть миграцию на более высокий уровень оркестрации (Kubernetes), если требования к масштабированию и надежности растут.

Пулл-кейсы и когда миграция может не подойти

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

Decision tree для принятия решения (Mermaid)

flowchart TD
  A[Есть тестовая среда?] -->|Да| B[Можно проводить миграцию]
  A -->|Нет| C[Создать тестовую среду]
  C --> B
  B --> D{Есть критичные скрипты, завязанные на именах контейнеров?}
  D -->|Да| E[Адаптировать скрипты или использовать алиасы]
  D -->|Нет| F[Тестировать с BuildKit]
  F --> G{Сборки проходят?}
  G -->|Да| H[Запуск в staging]
  G -->|Нет| I[Отключить BuildKit и исследовать ошибки]

Сравнение v1 и v2 — краткая матрица

1-line глоссарий

• Docker Compose: инструмент для описания и запуска многоконтейнерных Docker-приложений.
• BuildKit: современная система сборки изображений Docker с улучшенной производительностью.
• Docker CLI plugin: расширение Docker CLI, добавляемое как плагин (используется для Compose v2).

Материалы для анонса (короткий текст 100–200 слов)

Docker Compose v2 теперь стабильна и интегрирована в Docker CLI. Это означает, что привычные команды docker-compose переходят в более единый синтаксис docker compose, а сама реализация переписана на Go, что повышает стабильность и согласованность с Docker. Для большинства проектов переход прост: достаточно обновить Docker Engine до версии v20.10.13+ или обновить Docker Desktop. Перед миграцией проверьте скрипты, которые зависят от формата имён контейнеров, и прогоните сборку под BuildKit. Для гибкости можно временно сохранить бинарник v1 или настроить алиас. Следуйте контрольным спискам из этого руководства для безопасной поэтапной миграции.

Краткое резюме

Docker Compose v2 упрощает работу с Compose, расширяет возможности и улучшает совместимость с остальным Docker-стеком. Планируйте миграцию: проведите инвентаризацию, выполните тесты в CI/staging, обновите скрипты и лишь затем переведите production. После миграции удалите временные алиасы и используйте новые возможности v2.

FAQ

Нужно ли менять мои docker-compose.yml файлы?

Во многих случаях нет. Формат файлов остаётся совместимым. Основные изменения касаются вызовов CLI и поведения сборки.

Что делать, если сборки ломаются после включения BuildKit?

Попробуйте временно отключить BuildKit: DOCKER_BUILDKIT=0 docker compose build, разберитесь в расхождениях и исправьте Dockerfile.

Могу ли я использовать v1 и v2 одновременно?

Да. На Linux можно оставить бинарник v1 и установить плагин v2. В Docker Desktop v2 обычно алиасится на docker-compose, но вы можете отключить алиас.

Как быстро вернуть старое поведение, если что-то пойдёт не так?

• В Desktop: снимите галочку «Use Docker Compose v2» или выполните docker-compose disable-v2.
• На Linux: переустановите бинарник v1 или снимите алиас, восстановив /usr/local/bin/docker-compose.