Helm: зависимости чартов и каталог charts/

Как один чарт использует другие чарты: что лежит в charts/, как объявлять зависимости, как управлять ими и передавать значения

Зачем нужны зависимости

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

Структура каталога charts/

mychart/
  Chart.yaml          # метаданные и список зависимостей
  Chart.lock          # зафиксированные версии зависимостей (создаётся командой)
  values.yaml         # значения по умолчанию для самого чарта и его зависимостей
  templates/          # шаблоны манифестов основного чарта
  charts/             # скачанные зависимости в виде архивов .tgz
    redis-18.6.1.tgz
    postgresql-15.5.0.tgz

Каталог charts/ содержит саму установленную зависимость, которую Helm упакует вместе с основным чартом. Вручную файлы там обычно не правят: их заполняет команда helm dependency, исходя из Chart.yaml.

Не редактируйте архивы в charts/ руками. Они перезаписываются при каждом helm dependency update. Изменять поведение зависимости нужно через её values в основном values.yaml.

Объявление зависимостей в Chart.yaml

apiVersion: v2
name: shop
version: 1.4.0
description: Интернет-магазин: backend, база и кеш
dependencies:
  - name: postgresql
    version: "15.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
    alias: db
  - name: redis
    version: "18.6.1"
    repository: "https://charts.bitnami.com/bitnami"
    condition: cache.enabled
    tags:
      - cache
  - name: common
    version: "2.x.x"
    repository: "oci://registry.example.com/charts"

Поля зависимости

Поле	Назначение
name	Имя чарта в репозитории. Обязательно.
version	Версия или диапазон версий (SemVer). Например, `"15.x.x"` или `"~18.6.0"`.
repository	Адрес: HTTP-репозиторий, OCI-реестр (`oci://`) или локальный путь (`file://../common`).
condition	Путь к булеву значению в values. Если значение false, зависимость не ставится.
tags	Метки. Зависимость включается или выключается по тегу через значение `tags.<имя>`.
alias	Другое имя, под которым зависимость видна в values и шаблонах. Удобно, если один чарт подключён дважды.
import-values	Какие значения подчинённого чарта экспортировать в родительский.

Команды управления зависимостями

Команда	Что делает
helm dependency list	Показывает зависимости и их статус: установлена ли нужная версия, ок ли архив.
helm dependency update	Разрешает версии по диапазонам, скачивает архивы в charts/ и обновляет Chart.lock.
helm dependency build	Восстанавливает charts/ точно по Chart.lock, без поиска новых версий. Так собирают воспроизводимые сборки.

helm dependency list ./shop
helm dependency update ./shop    # после изменения версий в Chart.yaml
helm dependency build ./shop     # в CI, чтобы взять ровно то, что зафиксировано
helm package ./shop              # архив включит содержимое charts/

Chart.lock

Файл Chart.lock фиксирует конкретные версии и хеши зависимостей. Его нужно коммитить в git. Если lock-файл расходится с Chart.yaml, Helm предупредит, и команду helm dependency update придётся выполнить заново.

В CI используйте helm dependency build, а не update: сборка берёт зафиксированные версии и не зависит от того, что появилось в репозитории за последний час.

Значения для зависимостей

Параметры зависимости задаются в values основного чарта под её именем (или alias). Всё, что находится под ключом с именем зависимости, передаётся в её шаблоны как её собственные values.

# values.yaml основного чарта
replicaCount: 2

db:                      # alias зависимости postgresql
  enabled: true
  auth:
    database: shop
    username: shop_user
  primary:
    persistence:
      size: 20Gi

cache:
  enabled: true
redis:                   # имя зависимости redis, condition: cache.enabled
  architecture: standalone
  auth:
    enabled: false

Глобальные значения

Ключ global доступен всем чартам, включая зависимости. Удобно для общих параметров: имени хранилища, реестра образов, меток окружения.

global:
  imageRegistry: registry.example.com
  storageClass: fast-ssd

В шаблоне зависимости .Values.global.storageClass будет тем же значением, что и в родительском чарте. Используйте global только для действительно общих параметров: иначе зависимости станут сильно связаны.

Экспорт значений через import-values

Иногда родительскому чарту нужны значения из зависимости, например адрес сервиса. Их можно экспортировать:

dependencies:
  - name: postgresql
    version: "15.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    import-values:
      - child: primary.service    # путь в values зависимости
        parent: dbService         # куда положить в values родителя

Включение и отключение зависимостей

# Не ставить redis
helm install shop ./shop --set cache.enabled=false

# Выключить по тегу: все зависимости с тегом cache
helm install shop ./shop --set tags.cache=false

# Проверить, какие чарты будут отрисованы
helm template shop ./shop --set cache.enabled=false | grep -c "kind:"

Условие condition удобнее тегов: оно указывает конкретный ключ. Теги нужны, когда одной логической функции соответствует несколько зависимостей, например «все компоненты мониторинга».

Отладка зависимостей

Симптом	Что проверить
Error: found in Chart.yaml, but missing in charts/ directory	Не выполнен `helm dependency update` или `build`, архив не скачан.
Error: the lock file is out of sync	Версии в Chart.yaml изменены без обновления Chart.lock. Выполните `helm dependency update`.
Значения не доходят до зависимости	Ключ в values записан не под именем или alias зависимости. Сверьте с `helm show values` архива.
Зависимость не устанавливается	Значение в condition равно false или тег выключен. Проверьте `helm get values --all`.
Репозиторий недоступен	Проверьте адрес и `helm repo add` для HTTP-репозитория; для OCI выполните `helm registry login`.

Локальные зависимости

Общую часть можно вынести в отдельный чарт и подключить по локальному пути. Это удобно для библиотек шаблонов, например для общих меток и имён.

dependencies:
  - name: common
    version: "0.1.0"
    repository: "file://../common"

После этого выполните helm dependency update: Helm упакует локальный чарт в charts/. Изменения в ../common попадут в зависимость только после повторного update.

Пример: полный цикл

# 1. Добавляем зависимость в Chart.yaml и настраиваем её values
# 2. Подтягиваем архивы и фиксируем версии
helm dependency update ./shop
git add shop/Chart.yaml shop/Chart.lock

# 3. Проверяем шаблоны, включая зависимости
helm lint ./shop
helm template shop ./shop -f values-prod.yaml | less

# 4. Собираем архив и устанавливаем
helm package ./shop
helm upgrade --install shop ./shop -n shop --create-namespace --atomic