Helm: основы, values, откаты и приёмы

Helm — менеджер пакетов для Kubernetes. Чарт описывает приложение, релиз — его установку в конкретном кластере.

Основные понятия

Репозитории и поиск чартов

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update                       # обновить индекс всех репозиториев
helm repo list                         # подключённые репозитории
helm repo remove bitnami

helm search repo nginx                 # поиск по подключённым репозиториям
helm search repo nginx --versions      # все версии чарта
helm search hub wordpress              # поиск на Artifact Hub

Установка и обновление

# Установка с нуля
helm install web bitnami/nginx -n demo --create-namespace --version 15.4.0 -f values-prod.yaml

# Самый частый вариант для CI/CD
helm upgrade --install web bitnami/nginx -n demo -f values-prod.yaml --atomic --timeout 5m

# Посмотреть, что изменится, без применения
helm upgrade web bitnami/nginx -n demo -f values-prod.yaml --dry-run --debug

Values: как задаются и как приоритеты

Значения можно передать несколькими способами. Приоритет от низкого к высокому:

1. values.yaml внутри самого чарта (значения по умолчанию);
2. файлы, переданные через -f или --values; если файлов несколько, позже указанный перекрывает ранее указанный;
3. параметры --set, --set-string и --set-file из командной строки, они имеют наивысший приоритет.

# Значения из файла
helm install web bitnami/nginx -f values-base.yaml -f values-prod.yaml

# Точечная подстановка через --set
helm upgrade web bitnami/nginx --set replicaCount=3 --set image.tag=1.27

# Строка, которую Helm не должен превращать в число или bool
helm upgrade web chart --set-string annotations.build=0042

# Значение из файла (например, сертификат)
helm upgrade web chart --set-file tls.cert=./cert.pem

# Вложенные списки и значения с запятыми
helm upgrade web chart --set 'hosts[0]=example.com,hosts[1]=www.example.com'
helm upgrade web chart --set-json 'resources={"limits":{"memory":"512Mi"}}'

Посмотреть и подготовить значения

helm show values bitnami/nginx > default-values.yaml   # все параметры чарта с описанием
helm get values web -n demo                             # значения текущего релиза
helm get values web -n demo --all                       # с учётом значений по умолчанию
helm get manifest web -n demo                           # итоговые манифесты, как они применены

Статус, история и откаты

helm history web -n demo
helm rollback web 3 -n demo --wait      # вернуться к ревизии 3
helm status web -n demo
helm get values web -n demo --revision 3  # значения конкретной ревизии

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

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

helm lint ./mychart                                  # ошибки в структуре и шаблонах
helm template web ./mychart -f values-prod.yaml     # отрисовать манифесты локально
helm template web ./mychart | kubectl apply --dry-run=client -f -
helm test web -n demo                               # запустить тесты из templates/tests/

Создание своего чарта

helm create mychart              # заготовка структуры
helm package ./mychart          # собрать архив mychart-0.1.0.tgz
helm dependency update ./mychart  # подтянуть зависимости из Chart.yaml

# Минимальная структура
mychart/
  Chart.yaml        # имя, версия, описание
  values.yaml       # значения по умолчанию
  templates/        # шаблоны манифестов
  charts/           # зависимости

# Фрагмент шаблона: значения подставляются через .Values
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-app
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: app
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

OCI-реестры

helm registry login registry.example.com
helm package ./mychart
helm push mychart-0.1.0.tgz oci://registry.example.com/charts
helm install web oci://registry.example.com/charts/mychart --version 0.1.0

Лайфхаки

• Сравнить релизы перед обновлением. Плагин helm-diff показывает разницу манифестов: helm diff upgrade web bitnami/nginx -f values-prod.yaml.
• Быстро проверить итоговые значения. helm template ... -f a.yaml -f b.yaml | less покажет результат без подключения к кластеру.
• Не забывайте про --atomic в CI. Неудачный деплой не оставит кластер в полуготовом состоянии.
• Фиксируйте версию чарта (--version), чтобы сборка была воспроизводимой.
• Переносите конфиг через файлы, а не через --set. Файлы попадают в git и видны в ревью, а длинные цепочки --set быстро становятся нечитаемыми.
• Используйте --namespace и --create-namespace вместе. Так релиз не попадёт случайно в default.
• Проверяйте схему values. Файл values.schema.json в чарте не даст передать значение нужного типа или пропустить обязательный параметр.
• Пробуйте чарт в kind или minikube перед продакшеном: там дешевле ошибиться.
• Переменные окружения в CI. Передавайте --set image.tag=$CI_COMMIT_SHORT_SHA, чтобы каждый деплой был привязан к коммиту.

Типичные ошибки