Миграция GitLab Managed Apps на проекты управления кластерами

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

• Перенос от Managed Apps
• Управление приложениями вручную
• Переход на модель проектов управления кластерами
• Контрольный список и SOP
• Частые вопросы

Перенос от Managed Apps

GitLab Managed Apps — это была функция интеграции с Kubernetes, которая предоставляла установку популярных приложений одним кликом. Она упрощала первичный запуск кластера, предлагая шаблоны для NGINX Ingress, Cert Manager, Prometheus и других.

В версии 13.x функция была помечена как устаревшая, а в GitLab 14.0 одно‑нажатие было полностью удалено. CI/CD‑шаблон для установки приложений ещё работает в 14.x, но он тоже объявлен устаревшим и будет удалён в GitLab 15.0. Основная причина — Managed Apps слишком ограничивали дальнейшее управление: приложения просто устанавливались или удалялись, без удобных возможностей для поддержания и кастомизации в процессе эксплуатации.

Важно: существующие инсталляции Managed Apps остаются работоспособными после обновления до GitLab 14.0. Вы можете безопасно обновить GitLab без простоя сервисов. Единственное — вы больше не увидите страницу “Applications” в UI и не сможете удалять приложения оттуда.

Получение контроля над вашими приложениями

Если текущие развертывания вас устраивают и вы не планируете их часто менять, можно оставить всё как есть. Приложения продолжают работать в Kubernetes‑namespace gitlab-managed-apps. Под капотом это обычные Helm‑деплойменты, поэтому ими можно управлять стандартными инструментами:

• kubectl — для просмотра и базового управления ресурсами;
• Helm (v3 предпочтительно) — для управления релизами, изменения значений и обновлений.

Выведете список ресурсов, установленных GitLab, командой:

kubectl get all -n gitlab-managed-apps

Эта команда покажет все связанные ресурсы и поможет понять, что активно в кластере без GitLab UI.

Некоторые старые инсталляции могли быть установлены через Helm v2. Клиенты Helm v3 не совместимы с релизами Helm v2 по формату хранения метаданных. Чтобы проверить, какие релизы были установлены с помощью Helm v3, выполните:

kubectl get all -n gitlab-managed-apps | grep 'helm.sh/release'

Релизы, видимые в выводе выше, установлены Helm v3. Сравните список с полным выводом get all, чтобы выявить релизы, добавленные через Helm v2.

Если у вас есть релизы Helm v2, у вас есть два варианта:

• Миграция релизов на Helm v3 по официальному руководству Helm (рекомендуется для долгосрочного управления).
• Временная установка локального клиента Helm v2 для немедленного взаимодействия и исправления проблем.

Переход на модель проектов управления кластерами

GitLab 14.0 продвигает новую практику — проекты управления кластерами (cluster management projects). Это шаблон проекта, который хранит Helm‑чарты и значения (values) в репозитории. Вы клонируете шаблон, подключаете проект к кластеру, правите чарты и запускаете CI, чтобы применить изменения к кластеру.

Такой подход решает главную проблему Managed Apps: контроль версий чарта и values в Git‑репозитории. Вы получаете управление как кодом (infrastructure as code) и возможность ревью, отката и аудита изменений.

Вы можете переложить существующие Managed Apps в проект управления кластерами. Предположим, что у вас уже есть подключённый к GitLab кластер (развертывания Managed Apps это уже делают).

Пошагово:

1. Создайте новый проект в GitLab: нажмите «+» → Create from template → найдите “GitLab Cluster Management” → Use template.
2. Дайте проекту имя и нажмите Create project.
3. В проекте откройте каталог applications. Каждый подкаталог — это отдельное приложение (например, applications/ingress).
4. Откройте helmfile.yaml в корне репозитория. Этот файл ссылается на индивидуальные application‑чарты. Раскомментируйте соответствующие строки, чтобы включить приложения, которые вы используете.

Далее нужно сопоставить версии чарта, которые уже развернуты в вашем кластере. Это важно, чтобы при переносе вы не случайно не обновили приложение на другую версию.

Получите список Helm‑релизов в namespace:

helm ls -n gitlab-managed-apps

В таблице найдите колонку CHART: она содержит значение формата app-name-X.Y.Z. Вам нужен номер версии X.Y.Z.

В проекте откройте applications//helmfile.yaml и измените поле version на ту, что вы зафиксировали.

Наконец, перенесите существующие значения (values) чарта в файл applications//values.yaml. Для этого выгрузите YAML‑представление текущих values через Helm:

helm get values ingress -n gitlab-managed-apps -a --output yaml

Замените ingress на имя релиза вашего приложения. Копируйте весь вывод и перезапишите файл applications/ingress/values.yaml в проекте. Проверьте пути и настройки, которые могут содержать ссылки на namespace или специфичные секреты.

Когда вы подготовили изменения, закоммитьте их и создайте merge в default‑ветку (обычно main). Пример команд:

git checkout -b my-branch

git add .

git commit -m "Migrate existing GitLab Managed Apps"

git checkout main

git merge my-branch

git push -u origin main

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

После успешного мерджа теперь вы управляете приложениями через репозиторий проекта управления кластерами. Для обновлений изменяйте поле version или values.yaml и применяйте через CI. Это даёт предсказуемый, ревью‑ориентированный процесс обновлений.

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

• Снимите резервную копию текущих values и любых Kubernetes‑секретов, связанных с приложениями.
• Проверьте, какие релизы установлены через Helm v2 vs v3.
• Зафиксируйте текущие версии чарта (X.Y.Z).
• Подготовьте проект управления кластерами и подключите кластер.
• Выгрузите текущие values и поместите их в applications//values.yaml.
• Коммит и merge в main, наблюдайте за пайплайном и логами Helm.
• План отката: иметь манифесты/helm‑values и возможность быстро восстановить предыдущую конфигурацию.

SOP: пошаговый план миграции (минимум для одного приложения)

1. Инвентаризация
   • Выполните kubectl get all -n gitlab-managed-apps.
   • Выполните helm ls -n gitlab-managed-apps.
   • Зафиксируйте имя релиза и CHART (версию).
2. Резервное копирование
   • helm get values -n gitlab-managed-apps -a --output yaml → сохранить файл.
   • Экспорт секретов, если необходимо (см. процедуры безопасности вашей организации).
3. Подготовка проекта
   • Создать проект из шаблона GitLab Cluster Management.
   • Подключить кластер через UI (Cluster integration) или с помощью существующей интеграции.
4. Импорт в проект
   • Раскомментировать/включить приложение в helmfile.yaml.
   • Поставить точную version в applications//helmfile.yaml.
   • Скопировать сохранённый YAML в applications//values.yaml.
5. Тестовый прогон
   • Создать ветку, закоммитить изменения.
   • Открыть MR/merge request и запустить пайплайн.
   • Проверить логи CI и ресурсы в кластере.
6. Оценка и приёмка
   • Сравнить манифесты и версии.
   • Проверить метрики приложения и доступность.
7. Завершение
   • Убрать старые метаданные, если всё стабильно.
   • Обновить внутреннюю документацию и runbooks.

Роли и обязанности (кто делает что)

• SRE/DevOps
  • Проводит инвентаризацию релизов и версии чарта.
  • Экспортирует значения и секреты.
  • Настраивает и тестирует проект управления кластерами.
• Разработчики/платформенные команды
  • Проверяют работоспособность приложений после миграции.
  • Участвуют в ревью изменений values и helmfile.
• Руководитель платформы
  • Утверждает окно миграции и план отката.
  • Обеспечивает соответствие политик безопасности.

Дерево решений для миграции

flowchart TD
  A[Start: Есть Managed Apps?] --> B{Планируете ли вы менять
 приложение часто?}
  B -- Да --> C[Мигрировать в проект управления кластерами]
  B -- Нет --> D[Оставить как есть в gitlab-managed-apps]
  C --> E{Релиз Helm v2?}
  E -- Да --> F[Мигрировать релиз на Helm v3 или временно
 использовать helm v2 клиент]
  E -- Нет --> G[Экспортировать values и перенести в проект]
  G --> H[Запустить CI и проверить]
  F --> G
  H --> I[Мониторить и документировать]
  D --> I
  I --> Z[Готово]

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

• Пайплайн проекта управления прошёл успешно без ошибок.
• Приложение сохраняет прежнюю доступность (время отклика/health checks стабильны).
• Все кастомные настройки из оригинального values.yaml перенесены.
• Документация обновлена и содержит шаги для отката.

Когда миграция может не подойти (контрпримеры)

• Очень старые кластеры с критичными релизами Helm v2 и жёсткими зависимостями, где миграция рискнa для продакшена — в этом случае разумно сначала поднять копию кластера для тестов.
• Если у вас процессы, жестко завязанные на GitLab UI Applications и их потоках — придётся обновить внутренние процессы и обучить команду.

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

• Временная стратегия: установить локальный Helm v2 клиент и поддерживать релизы вручную до тестовой миграции.
• Использовать сторонние GitOps‑операторы (Argo CD, Flux) для управления чардами вместо встроенного шаблона GitLab.

Факты и полезные команды

• Namespace по умолчанию для Managed Apps: gitlab-managed-apps
• Полезные команды:

kubectl get all -n gitlab-managed-apps
helm ls -n gitlab-managed-apps
helm get values  -n gitlab-managed-apps -a --output yaml
kubectl get all -n gitlab-managed-apps | grep 'helm.sh/release'

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

• Секреты и ключи не должны храниться в открытом виде в репозитории проекта. Используйте GitLab CI Variables, HashiCorp Vault или похожие решения.
• Перед переносом секретов убедитесь, что у проекта управления кластерами настроены права доступа и аудит.

Краткое руководство по откату

1. Если пайплайн привёл к регрессии — откатите MR (revert merge) в GitLab.
2. Если автоматический откат невозможен — примените ранее сохранённые values и/или используйте helm rollback -n gitlab-managed-apps.
3. При необходимости восстановите секреты из резервной копии.

Частые вопросы

Q: Повлияет ли обновление GitLab до 14.0 на работу моих Managed Apps? A: Нет, приложения останутся в рабочем состоянии, но вы потеряете UI‑функции для просмотра и удаления Managed Apps.

Q: Нужно ли немедленно мигрировать все приложения? A: Нет. Вы можете переходить постепенно. Однако для долгосрочного управления рекомендуется мигрировать важные приложения в проект управления кластерами.

Q: Что делать с релизами, установленных через Helm v2? A: Рекомендуется мигрировать релизы на Helm v3. Как временная мера можно использовать локальный Helm v2 клиент.

Q: Хранятся ли секреты в репозитории проекта шаблона? A: По умолчанию нет. Переносите секреты через безопасные хранилища, а в репозитории держите ссылки/инструкции.

Итог

GitLab Managed Apps упростили старт с Kubernetes, но ограничивали операционную гибкость. Переход на проекты управления кластерами даёт явные преимущества: контроль версий чарта, values в Git, ревью‑процессы и предсказуемый CI‑деплой. Миграция проводится шаг за шагом: идентификация релизов, экспорт существующих values, настройка проекта, применение через CI и верификация.

Важно планировать миграцию и подготовить план отката. Для крупных инфраструктур рекомендуется тестировать перенос на clone‑окружении и вовлекать команду SRE и разработчиков в ревью изменений.

Полезные ссылки и команды есть в разделе «Факты и полезные команды» выше. Удачной миграции и предсказуемого управления кластером!