Helm: подробно о values

Values — это параметры, которыми управляется чарт. Здесь разобраны приоритеты, все способы передачи, типы данных, вложенность, шаблонизация, проверка схемы и отладка

Что такое values

Шаблоны чарта не содержат жёстко заданных значений. Вместо этого они обращаются к объекту .Values, например {{ .Values.replicaCount }}. Значения приходят из нескольких источников, и Helm объединяет их в один итоговый объект. Одно и то же приложение можно разворачивать в разных окружениях, меняя только values.

Приоритет источников

Если один и тот же ключ задан в нескольких местах, побеждает источник с большим приоритетом. От низкого к высокому:

1. values.yaml чарта — значения по умолчанию, которые автор чарта положил в архив;
2. values.yaml родительского чарта — для зависимостей, их значения задаются под именем или alias зависимости;
3. файлы через -f / --values — если указано несколько файлов, побеждает последний;
4. --set, --set-string, --set-file, --set-json — побеждают все файлы; внутри флагов побеждает последний.

# base.yaml задаёт replicaCount=2, prod.yaml задаёт 5, --set задаёт 7
helm upgrade web ./chart -f base.yaml -f prod.yaml --set replicaCount=7
# Итог: replicaCount = 7

Способы передачи значений

Типы данных в --set

--set port=8080           # число
--set debug=true          # bool
--set name=null           # null: удаляет ключ из итоговых values
--set version=1.10        # число 1.1 (лишний ноль потеряется!)
--set-string version=1.10 # строка "1.10"
--set env[0].name=LOG     # элемент массива
--set env[0].value=debug

Экранирование запятых и точек

# Запятая внутри значения экранируется обратной косой чертой
--set 'hosts=a.example.com\,b.example.com'

# Точка в имени ключа: экранируйте её
--set 'annotations.kubernetes\.io/ingress\.class=nginx'

Вложенность и массивы

Значения могут быть вложенными словарями и списками. Для списков Helm заменяет весь массив целиком, а не объединяет поэлементно.

# values.yaml по умолчанию
ingress:
  enabled: false
  hosts:
    - host: example.local
      paths:
        - /

# Переопределение в файле prod.yaml
ingress:
  enabled: true
  hosts:
    - host: shop.example.com
      paths:
        - /
        - /api

Если в prod.yaml написать hosts с одним элементом, список будет заменён полностью. Это поведение удобно, но часто удивляет: если нужно добавить элемент, перепишите весь список.

Удаление ключа через null

# Удалить значение из чарта по умолчанию
resources: null

# То же через командную строку
helm upgrade web ./chart --set resources=null

Значения в шаблонах

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

# Значение по умолчанию, если ключа нет или он пустой
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"

# Обязательное значение: если его нет, рендеринг упадёт с понятным сообщением
host: {{ required "Укажите ingress.host" .Values.ingress.host }}

# Преобразование блока YAML с правильными отступами
resources:
  {{- toYaml .Values.resources | nindent 2 }}

# Условие
{{- if .Values.ingress.enabled }}
kind: Ingress
{{- end }}

# Перебор списка
{{- range .Values.ingress.hosts }}
- host: {{ .host | quote }}
{{- end }}

Значения, которые не должны попасть в шаблон

Значения из .Values видны всем шаблонам. Если нужна константа, которая не должна меняться через values, объявите её в шаблоне через $var := ... или в _helpers.tpl. Не превращайте в values всё подряд: чем больше параметров, тем сложнее сопровождать чарт.

Глобальные значения и зависимости

global:
  imageRegistry: registry.example.com
  environment: production

Ключ global доступен и в основном чарте, и во всех зависимостях как .Values.global. Для параметров конкретной зависимости используйте её имя или alias:

postgresql:          # имя зависимости
  auth:
    database: shop
db:                  # alias той же зависимости
  auth:
    database: shop_other

Проверка схемы: values.schema.json

Файл values.schema.json в корне чарта описывает допустимые значения в формате JSON Schema. Helm проверит их при install, upgrade, lint и template. Это ловит опечатки и неверные типы до деплоя.

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image"],
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "image": {
      "type": "object",
      "required": ["repository", "tag"],
      "properties": {
        "repository": { "type": "string" },
        "tag": { "type": "string" }
      }
    }
  }
}

Если значение не проходит проверку, Helm выдаст ошибку с путём до проблемного ключа. Для приложений с сотнями параметров это экономит много времени.

Секреты

Значения попадают в историю релиза: helm get values и Secret релиза хранят их. Поэтому пароли и токены в открытом виде в values не кладите.

• Создайте Secret заранее и ссылайтесь на него по имени в values, например existingSecret: db-credentials.
• Для шифрования файлов values используйте плагин helm-secrets с sops или аналогичный инструмент.
• Переменные окружения CI подставляйте через --set-string в последний момент, не сохраняя в файлах.

Отладка значений

# Значения по умолчанию чарта
helm show values ./chart

# Итоговые значения релиза (только переопределённые)
helm get values web -n demo

# Итоговые значения, включая значения по умолчанию
helm get values web -n demo --all

# Значения для конкретной ревизии
helm get values web -n demo --revision 3

# Отрисовать только один шаблон, чтобы проверить подстановку
helm template web ./chart -f prod.yaml --show-only templates/deployment.yaml

# Показать значения, которые получит шаблон, прямо в выводе
helm template web ./chart -f prod.yaml --debug | less

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

Рекомендуемая структура файлов

chart/
  values.yaml              # безопасные значения по умолчанию
  values.schema.json       # проверка типов и обязательных полей
environments/
  base.yaml                # общие параметры для всех окружений
  dev.yaml                 # переопределения для разработки
  prod.yaml                # переопределения для продакшена
secrets/
  prod.enc.yaml            # зашифрованные секреты (sops)