Values

Эта часть руководства по лучшим практикам посвящена использованию values. Здесь мы даём рекомендации по структуре и использованию values с акцентом на проектирование файла values.yaml чарта.

Соглашения об именовании

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

Правильно:

chicken: true
chickenNoodleSoup: true

Неправильно:

Chicken: true  # заглавная буква может конфликтовать со встроенными переменными
chicken-noodle-soup: true # не используйте дефисы в именах

Обратите внимание, что все встроенные переменные Helm начинаются с заглавной буквы, чтобы их можно было легко отличить от пользовательских значений: .Release.Name, .Capabilities.KubeVersion.

Плоские или вложенные значения

YAML — гибкий формат, и значения могут быть как глубоко вложенными, так и плоскими.

Вложенные:

server:
  name: nginx
  port: 80

Плоские:

serverName: nginx
serverPort: 80

В большинстве случаев плоская структура предпочтительнее вложенной. Причина в том, что так проще и для разработчиков шаблонов, и для пользователей.

Для обеспечения безопасности вложенное значение необходимо проверять на каждом уровне:

{{ if .Values.server }}
  {{ default "none" .Values.server.name }}
{{ end }}

Для каждого уровня вложенности требуется проверка существования. Для плоской конфигурации такие проверки можно пропустить, что делает шаблон проще для чтения и использования.

{{ default "none" .Values.serverName }}

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

Явно указывайте типы

Правила приведения типов в YAML иногда неинтуитивны. Например, foo: false — это не то же самое, что foo: "false". Большие целые числа, такие как foo: 12345678, в некоторых случаях преобразуются в экспоненциальную запись.

Самый простой способ избежать ошибок преобразования типов — быть явным со строками и неявным со всем остальным. Или, коротко, заключайте все строки в кавычки.

Часто бывает полезно хранить целые числа также в виде строк, чтобы избежать проблем с приведением типов, и использовать {{ int $value }} в шаблоне для преобразования строки обратно в целое число.

В большинстве случаев явные теги типов корректно обрабатываются, поэтому foo: !!string 1234 будет воспринимать 1234 как строку. Однако YAML-парсер обрабатывает теги, и информация о типе теряется после первого разбора.

Учитывайте, как пользователи будут использовать ваши values

Существует три возможных источника values:

• Файл values.yaml чарта
• Файл values, переданный через helm install -f или helm upgrade -f
• Значения, переданные через флаг --set или --set-string при выполнении helm install или helm upgrade

При проектировании структуры values помните, что пользователи вашего чарта могут захотеть переопределить их с помощью флага -f или опции --set.

Поскольку --set более ограничен в выразительности, первое правило при написании файла values.yaml — упростите переопределение через --set.

По этой причине часто лучше структурировать файл values с помощью словарей (maps).

Сложно использовать с --set:

servers:
  - name: foo
    port: 80
  - name: bar
    port: 81

Приведённую выше структуру невозможно выразить с помощью --set в Helm <=2.4. В Helm 2.5 обращение к порту foo выглядит как --set servers[0].port=80. Это не только сложнее для понимания пользователем, но и подвержено ошибкам, если впоследствии порядок servers изменится.

Удобно использовать:

servers:
  foo:
    port: 80
  bar:
    port: 81

Обращение к порту foo гораздо очевиднее: --set servers.foo.port=80.

Документируйте values.yaml

Каждое определённое свойство в values.yaml должно быть задокументировано. Строка документации должна начинаться с имени свойства, которое она описывает, и содержать как минимум одно предложение с описанием.

Неправильно:

# имя хоста для веб-сервера
serverHost: example
serverPort: 9191

Правильно:

# serverHost — имя хоста для веб-сервера
serverHost: example
# serverPort — порт HTTP-слушателя для веб-сервера
serverPort: 9191

Начало каждого комментария с имени параметра, который он документирует, упрощает поиск документации с помощью grep и позволяет инструментам документирования надёжно сопоставлять строки документации с описываемыми параметрами.