GitLab как Helm-репозиторий: настройка и инструкция

GitLab поддерживает хранение Helm-чартов прямо в проектах начиная с версии 14.1 — это позволяет хранить манифесты Kubernetes рядом с кодом. В статье показано, как подготовить чарты, добавить репозиторий в локальный Helm, опубликовать пакет вручную и из CI, а также приведены рекомендации по безопасности, чек-листы и отладке.

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

• Использование Helm-репозитория GitLab
• Добавление репозитория в Helm
• Отправка чарта в репозиторий
• Развёртывание чарта из репозитория
• Доступ к репозиторию GitLab из CI
• Резюме и рекомендации

GitLab начиная с версии 14.1 добавил поддержку Helm-чартов в список форматов реестров пакетов. Теперь чарты можно хранить и распространять в пределах проектов GitLab без отдельного Helm-реестра.

Коротко: Helm-чарт — это набор YAML-манифестов Kubernetes, упакованный в единый пакет. Они ускоряют и упрощают развёртывание сложных приложений в кластере. Использование GitLab как реестра позволяет командам хранить чарты рядом с кодом в управляемом организацией хранилище.

Использование Helm-репозитория GitLab

Требование: ваша инсталляция GitLab должна быть не ниже версии 14.1. Если вы используете GitLab.com (хостинг от GitLab), то всё уже доступно.

Подготовьте простой Helm-чарт, который вы собираетесь отправить в репозиторий. Если у вас ещё нет чарта, выполните:

helm create example

Это создаст новый шаблонный чарт с именем

example

Если вы не меняли ничего, сгенерированный чарт готов к публикации в GitLab без дополнительной подготовки.

Перейдите в ваш экземпляр GitLab. Создайте новый проект или откройте существующий. В левой боковой панели выберите Packages & Registries > Package Registry внутри проекта. Если эти меню не видны, откройте Settings > General, разверните раздел “Visibility, project features, permissions” и включите переключатель “Packages”.

Добавление репозитория в Helm

Чтобы Helm-клиент мог использовать ваш GitLab-реестр, добавьте репозиторий локально.

Пример команды (замените параметры на свои):

helm repo add --username  --password  example-repo https://gitlab.example.com/api/v4/projects//packages/helm/stable

• example-repo — имя локального репозитория в Helm.
• — ваш логин в GitLab.
• — персональный токен доступа с правами публикации (описано ниже).
• — внутренний ID проекта в GitLab.

Создайте персональный токен доступа: кликните по аватарке в правом верхнем углу GitLab -> Preferences -> Access Tokens. Добавьте новый токен с областью api. Обратите внимание: область write_repository может показаться подходящей, но она не работает для публикации Helm-пакетов через API — для этого требуется api.

Замените в URL на внутренний ID проекта, который отображается на странице проекта под его названием.

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

Отправка чарта в репозиторий

После добавления репозитория вы можете отправлять любые директории с валидным Helm-чартом в ваш GitLab. Удобно установить плагин helm-push, который добавляет команду helm push.

Упакуйте чарт, если он ещё не упакован:

helm package example-chart

Это создаст gzipped tar-архив example-chart.tgz, содержащий чарт.

Установите плагин helm-push:

helm plugin install https://github.com/chartmuseum/helm-push.git

И затем отправьте файл в репозиторий:

helm push example-chart.tgz example-repo

В веб-интерфейсе GitLab откройте Packages & Registries > Package Registry вашего проекта — вы увидите загруженный чарт. Кликните по имени чарта, чтобы посмотреть подробности, историю релизов, загрузить файлы или удалить выпуск кнопкой “Delete” в правом верхнем углу.

Развёртывание чарта из репозитория

После публикации чарта вы можете установить его в ваш Kubernetes-кластер напрямую из репозитория:

# загрузить данные о репозиториях
helm repo update

# установить чарт
helm install example-repo/example-chart

Если у вас несколько конфигураций Kubernetes, используйте флаги --kubeconfig и --namespace, чтобы указать нужный kubeconfig и пространство имён.

Совет: для непрерывной интеграции используйте семантические теги версий в чартах (Chart Version) — тогда helm upgrade сможет корректно обновлять релизы.

Доступ к репозиторию GitLab из CI

GitLab интегрирует реестр с CI/CD: пайплайны уже получают пресет-переменные окружения, которые упрощают публикацию чарта. Обычно не нужно вручную задавать дополнительные CI-переменные для аутентификации.

Пример .gitlab-ci.yml, который создаёт чарт и публикует его в реестр:

stages:
  - helm-publish

helm-publish:
  stage: helm-publish
  image:
    name: alpine/helm:latest
    entrypoint: [""]
  script:
    - helm repo add --username $CI_REGISTRY_USER --password $CI_REGISTRY_PASSWORD my-repo $CI_REGISTRY
    - helm package my-chart
    - helm plugin install https://github.com/chartmuseum/helm-push.git
    - helm push my-chart.tgz my-repo

Переменные окружения, предоставляемые GitLab ($CI_REGISTRY, $CI_REGISTRY_USER, $CI_REGISTRY_PASSWORD), настроены так, чтобы разрешать публикацию пакетов в реестр проекта. Те же переменные применимы и для других форматов пакетов (npm, Composer, NuGet, Maven).

Важно: если вы используете приватные runner’ы или специфические образы, убедитесь, что образ содержит необходимые утилиты (helm и плагин push) или устанавливает их в рантайме.

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

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

Разработчик

• Подготовить и протестировать локально Helm-чарт.
• Обновить Chart.yaml с семантической версией.
• Упаковать чарт (helm package) и проверить содержимое архива.
• Создать MR/коммит в проекте с релизом чарта при необходимости.

DevOps / Инженер по релизам

• Добавить репозиторий в Helm (helm repo add) на CI и в документацию.
• Настроить пайплайн публикации чарта в .gitlab-ci.yml.
• Обеспечить правильные права доступа и хранение токенов.
• Автоматизировать очистку старых версий чарта (если нужно).

Владелец проекта / Maintainer

• Включить Packages в настройках проекта.
• Управлять доступом пользователей (чтение/запись).
• Удалять старые пакеты, освобождая место.
• Контролировать политики хранения и соответствие стандартам безопасности.

Когда это не подходит / Контрпримеры

• Если вам нужно хранить большие артефакты или бинарные образы — лучше использовать специализированные регистры (например, OCI-реестр для образов Docker).
• Если требуется продвинутая индексация чарта вне структуры проектов — отдельный ChartMuseum или центральный Helm-репозиторий может быть удобнее.
• Если у вас очень высокая частота публикаций и строгие SLA на доступ — рассмотрите выделенный инфраструктурный реестр с горизонтальным масштабированием.

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

• ChartMuseum: отдельный HTTP-сервер для хранения Helm-пакетов, легко интегрируется с CI.
• OCI-реестры: хранение Helm-чартов в формате OCI (новый стандарт), позволяет использовать существующую инфраструктуру для контейнеров.
• Центральный Helm-репозиторий внутри организации: удобен для единой точки доступа и контроля.

Выбор зависит от требований к масштабируемости, управлению версиями и интеграции с остальной инфраструктурой.

Шпаргалка команд (Cheat sheet)

• Создать базовый чарт: helm create example
• Упаковать чарт: helm package my-chart
• Добавить репозиторий: helm repo add --username --password name https://gitlab.example.com/api/v4/projects//packages/helm/stable
• Обновить список репозиториев: helm repo update
• Установить чарт: helm install name/release
• Установить плагин push: helm plugin install https://github.com/chartmuseum/helm-push.git
• Отправить пакет: helm push my-chart.tgz name

Методика тестирования и критерии приёмки

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

• Чарт успешно публикуется в GitLab через локальный Helm и через CI.
• После публикации чарт видим в UI проекта и доступен для загрузки.
• helm repo update обновляет индекс, и helm install разворачивает ресурс корректно.
• CI-пайплайн выполняется без хранения секретов в явном виде в репозитории.

Тестовые сценарии

1. Локальная публикация

   • Упаковать чарт локально.
   • Добавить репозиторий с персональным токеном.
   • Выполнить helm push и проверить появление пакета в UI.

2. Публикация из CI

   • Настроить .gitlab-ci.yml с использованием $CI_REGISTRY_* переменных.
   • Запустить пайплайн и убедиться, что пакет появился в реестре.

3. Развёртывание

   • Выполнить helm repo update и helm install в тестовом кластере.
   • Проверить, что все Kubernetes-ресурсы переходят в состояние Ready/Running.

Отладка и распространённые ошибки

• “401 Unauthorized” при добавлении репозитория: проверьте правильность токена и область доступа (должна быть api).
• Плагин helm-push не установлен: установите плагин или используйте альтернативную загрузку через API.
• Неправильный в URL: используйте внутренний ID проекта (проверяется на странице проекта).
• Чарт не обновляется при helm upgrade: проверьте Chart.yaml и увеличьте версию чарта.

Безопасность и приватность

• Храните персональные токены в секретах CI (Protected Variables) и используйте минимально необходимые права.
• При использовании публичных проектов чарты будут доступны всем с правом чтения; для приватных проектов доступ ограничен.
• Если чарты содержат чувствительные данные (пароли, ключи), не включайте их в Chart values — используйте секреты и механизмы внешнего управления конфигурацией.
• Учитывайте локальные правила соответствия (например, требования по хранению логов и доступа к кластерам). Для конфиденциальных данных используйте шифрование и контроль доступа.

Полезные ментальные модели

• “Чарт как код”: держите чарты рядом с исходным кодом приложения, чтобы версия приложения и чарт были синхронизированы.
• “Реестр = артефакты” — GitLab проект выступает как единая точка хранения артефактов, но не как отдельный распределённый репозиторий.
• “CI как издатель” — пайплайны публикуют артефакты автоматически по мерджу/тегу.

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

GitLab предоставляет удобный встроенный механизм хранения Helm-чартов, который упрощает публикацию и развёртывание приложений. Настройка сводится к генерации токена с областью api, добавлению репозитория в Helm и использованию helm push (или пайплайна) для публикации. Обратите внимание на безопасность токенов и на версионирование чарта.

Важно

• Всегда тестируйте развёртывание в тестовом кластере перед продакшеном.
• Не храните секреты в Chart values.