Kompose: перенести Docker Compose в Kubernetes

Иллюстрация с логотипами Docker и Kubernetes

Kompose автоматически преобразует файлы Docker Compose в Kubernetes-манифесты. Это упрощает миграцию локальных стеков в кластер, но требует ручной проверки и доработки вывода перед применением в продакшене. Используйте Kompose как стартовую точку, а не как окончательное решение.

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

Getting Started
Converting Your Stack
Deploying to Your Cluster
Limitations
Когда Kompose не подходит
Альтернативы
Playbook для миграции
Критерии приёмки
Заключение

Введение

Docker Compose позволяет описывать и запускать группу контейнеров как один стек. Это удобно для локальной разработки и тестирования. Kubernetes — это система оркестрации контейнеров с собственными манифестами и более сложной моделью объектов. Kompose — это инструмент, который помогает перенести Compose-файл в Kubernetes, генерируя соответствующие ресурсы.

Важно: Kompose фокусируется на преобразовании YAML в YAML. Он не разворачивает ресурсы в кластер напрямую в актуальных версиях; вы сами применяете сгенерированные манифесты через kubectl.

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

Getting Started

Kompose доступен для Windows, macOS и большинства дистрибутивов Linux. Готовые бинарные файлы публикуются в репозитории GitHub проекта. Загрузите релиз, дайте право на исполнение и переместите бинарник в каталог из PATH. Поддерживаются и пакеты через менеджеры пакетов.

Пример установки (Linux):

curl -L https://github.com/kubernetes/kompose/releases/download/v1.23.0/kompose-linux-amd64 -o kompose

chmod +x kompose

sudo mv ./kompose /usr/local/bin/kompose

После установки выполните kompose в терминале — вы увидите список команд. Команда kompose version покажет текущую версию.

Скриншот: запуск Kompose для создания Kubernetes-манифестов из Docker Compose

Подготовьте файл docker-compose.yml. Простой пример, который запускает Apache и MySQL, выглядит так:

version: "3"

services:
  apache:
    image: httpd:latest
    ports:
      - "80:80"

  mysql:
    image: mysql:latest
    expose:
      - "3306"
    volumes:
      - mysql:/var/lib/mysql

volumes:
  mysql:

Также нужен Kubernetes-кластер. Можно создать его в облаке или поднять локально с помощью MicroK8s, kind или minikube.

Converting Your Stack

Команда kompose convert принимает путь к Compose-файлу и генерирует Kubernetes-манифесты. Если путь не указан, используется docker-compose.yml в рабочем каталоге. Поддерживается несколько файлов через флаг -f.

kompose convert -f docker-compose.yml -f docker-compose-dev.yml

Kompose создаёт отдельные YAML-файлы для каждого компонента стека. Они помещаются в рабочую директорию. Ниже — пример вывода для простого стека (апач + mysql):

Скриншот: Kompose создал Kubernetes-манифесты из Docker Compose

Сгенерированы Deployment и Service для каждого сервиса Compose. Также создан PersistentVolumeClaim для MySQL — это представление тома из Compose и способ сохранить данные вне жизненного цикла Pod.

Если открыть сгенерированные файлы, они являются обычными совместимыми с kubectl Kubernetes-манифестами. Пример apache-deployment.yaml:

apiVersion: apps/v1

kind: Deployment

metadata:
  annotations:
    kompose.cmd: kompose convert
    kompose.version: 1.23.0 (bc7d9f4f)
  creationTimestamp: null
  labels:
    io.kompose.service: apache
  name: apache

spec:
  replicas: 1
  selector:
    matchLabels:
      io.kompose.service: apache
  strategy: {}
  template:
    metadata:
      annotations:
        kompose.cmd: kompose convert
        kompose.version: 1.23.0 (bc7d9f4f)
      creationTimestamp: null
      labels:
        io.kompose.service: apache
    spec:
      containers:
        - image: httpd:latest
          name: apache
          ports:
            - containerPort: 80
      resources: {}
      restartPolicy: Always

status: {}

Аннотации Kompose помогают идентифицировать ресурсы, созданные с помощью инструмента.

Deploying to Your Cluster

Применяйте сгенерированные файлы стандартной командой kubectl. Рекомендуется хранить их в отдельной директории, чтобы kubectl не пытался читать ваш docker-compose.yml.

kubectl apply -f ./manifests

После применения ресурсы будут создаваться в кластере. Проверьте состояние командой kubectl get deployments. Когда в колонке AVAILABLE появится желаемое значение (например, 1), служба доступна.

Скриншот: проверка статуса деплойментов в Kubernetes

Чтобы масштабировать сервис, отредактируйте поле replicas в соответствующем Deployment и выполните kubectl apply снова.

Важно: если вы повторно запускаете kompose convert по изменённому docker-compose.yml, то затем применение результата перезапишет любые ручные изменения, сделанные в манифестах. Подходите к этому сознательно.

Ограничения

Kompose хорошо работает с типичными паттернами Compose. Но не всё можно корректно маппировать в Kubernetes. Ниже — основные ограничения и нюансы, о которых нужно знать.

Отсутствие 1:1 соответствия: некоторые возможности Compose не имеют прямого аналога в Kubernetes.
Сетевые политики и Ingress: Kompose часто создаёт Service типа ClusterIP/NodePort. Ingress-правила для маршрутизации внешнего трафика обычно не генерируются.
Томa и bind-mount’ы: привязки хост-файловой системы в Compose (bind mounts) нельзя напрямую воспроизвести в управляемом кластере. Необходимо использовать PV/PVC, облачные тома или CSI.
PersistentVolumes: Kompose создаёт PVC, но не автоматом создаёт PV. Кластер должен иметь StorageClass или доступные PV.
Опинионированные решения: инструмент выбирает простейшие варианты при неоднозначности, а не всегда те, которые нужны в продакшне.

Контрпримеры и когда это не сработает

Compose с локальными SOCKS/Unix-сокетами и хост-монтами не перевести прямо в Kubernetes без переработки архитектуры.
Сценарии, где требуется сложная маршрутизация (HostNetwork, специфичные NodeAffinity, PDB, сложные NetworkPolicy) требуют ручной работы.
Statefull-приложения с зависимостями от локальных путей и нестандартных прав доступа часто ломаются после конверсии.

Когда Kompose не подходит

Если вам требуется тщательный контроль над объектами Kubernetes (Ingress, NetworkPolicy, PodSecurityPolicy, NodeAffinity).
Если приложение использует hostPath или специфичные устройства узла.
Для production-ready CI/CD-конвейера в больших организациях стоит применять Helm, Kustomize или писать манифесты вручную.

Альтернативы

Helm: шаблонизация и управление версиями манифестов.
Kustomize: декларативная кастомизация манифестов без шаблонов.
Ручная конвертация: полезна для полного контроля.
Платформенные инструменты (SaaS) и GitOps-подходы для полного жизненного цикла приложения.

Мини-методология миграции (шаги)

Подготовка: зафиксируйте текущий docker-compose.yml и зависимости.
Конверсия: kompose convert в отдельную директорию.
Анализ: вручную просмотрите все манифесты. Ищите аннотации Kompose, тома и типы Service.
Рефакторинг: замените NodePort на Ingress, добавьте NetworkPolicy, SecurityContext, Resource Requests/Limits.
Сеть и хранилище: подготовьте PV/PVC или StorageClass.
Тестирование: примените в тестовом неймспейсе, прогоните интеграционные тесты.
Продакшн: примените в продакшн через GitOps/CI и мониторьте.

Playbook: быстрый SOP для миграции

Создайте ветку в репозитории: migration/kompose-.
Скопируйте docker-compose.yml в ./manifests/source.
Выполните kompose convert -f ./manifests/source/docker-compose.yml -o ./manifests/generated.
Просмотрите generated/ и сохраните версию.
Примените в staging: kubectl apply -f ./manifests/generated -n staging.
Выполните smoke-тесты и проверку логов.
Интегрируйте исправления, добавьте Ingress/Policies/Secrets.
Подготовьте PR с манифестами и чеклистом для ревью.

Ролевые чек-листы

Разделим обязанности по ролям.

Разработчик

Проверить зависимости и переменные окружения.
Избежать bind-mounts локальных путей.
Подготовить миграционный сценарий данных.

SRE / Платформенная команда

Подготовить StorageClass / PV.
Настроить Ingress и TLS.
Добавить NetworkPolicy и RBAC.
Настроить мониторинг и алертинг.

Прогнать тестовый прогон на staging.
Проверить логи, поведение при рестарте Pod.
Выполнить нагрузочное тестирование.

Примеры и шаблоны

Шаблон задачи при переносе сервиса:

Описание сервиса
Docker Compose версии
Список томов и их назначение
Список портов и назначение
Требования к масштабированию
Критерии приёмки

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

Приложение стартует в тестовом неймспейсе без ошибок.
Доступность сервиса соответствует требованиям (smoke tests проходят).
Данные сохраняются при перезапуске Pod.
Мониторинг и логирование собирают метрики и логи.

Decision flowchart (Mermaid)

flowchart TD
  A[Есть docker-compose.yml?] --> B{Использовать Kompose?}
  B -- Да --> C[kompose convert]
  C --> D[Проверить манифесты]
  D --> E{Нужны правила безопасности / ingress?}
  E -- Да --> F[Добавить Ingress/NetworkPolicy/Secrets]
  E -- Нет --> G[Применить в staging]
  B -- Нет --> H[Использовать Helm/Kustomize/ручную генерацию]
  G --> I[Тестирование]
  F --> I
  I --> J{Готово к продакшну?}
  J -- Да --> K[Применить в prod через CI/GitOps]
  J -- Нет --> L[Итерация: исправления]

Безопасность и конфиденциальность

Секреты: Docker Compose может хранить чувствительные данные в plaintext. Не переносите секреты напрямую в манифесты. Используйте Kubernetes Secrets или внешнее хранилище секретов.
RBAC: сгенерированные манифесты не создают автоматом правил доступа. Нужна проверка и настройка ролей.
Логи и аудит: убедитесь, что логи собираются централизованно и доступ к кластеру ограничен.

Совместимость и миграция

Версии Kompose и Kubernetes: следите за совместимостью версий. Иногда поведение флагов меняется между релизами Kompose.
Хранилище: подготовьте StorageClass и протестируйте PVC до применения в продакшне.

Резюме

Kompose — удобный инструмент для первых шагов миграции из Docker Compose в Kubernetes. Он экономит время и даёт рабочую базу. Однако его вывод требует ручной ревизии и доработки для продакшн-готовности: настройка безопасности, сетевых маршрутов, работы с томами и политики доступов — всё это остаётся за инженером.

Краткий чек-лист перед продакшном: