Шаблоны

Эта часть руководства по лучшим практикам посвящена работе с шаблонами.

Структура директории templates/

Директория templates/ должна быть организована следующим образом:

• Файлы шаблонов должны иметь расширение .yaml, если они генерируют YAML-вывод. Расширение .tpl может использоваться для файлов шаблонов, которые не производят форматированного содержимого.
• Имена файлов шаблонов должны использовать нотацию с дефисами (my-example-configmap.yaml), а не camelCase.
• Каждое определение ресурса должно находиться в отдельном файле шаблона.
• Имена файлов шаблонов должны отражать тип ресурса в названии, например: foo-pod.yaml, bar-svc.yaml

Имена именованных шаблонов

Именованные шаблоны (шаблоны, созданные внутри директивы {{ define }}) доступны глобально. Это означает, что чарт и все его субчарты будут иметь доступ ко всем шаблонам, созданным с помощью {{ define }}.

По этой причине все имена именованных шаблонов должны иметь уникальный префикс.

Правильно:

{{- define "nginx.fullname" }}
{{/* ... */}}
{{ end -}}

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

{{- define "fullname" -}}
{{/* ... */}}
{{ end -}}

Настоятельно рекомендуется создавать новые чарты с помощью команды helm create, поскольку при этом имена шаблонов автоматически формируются в соответствии с этой лучшей практикой.

Форматирование шаблонов

Шаблоны должны иметь отступы в два пробела (никогда не используйте табуляцию).

Директивы шаблона должны иметь пробел после открывающих фигурных скобок и перед закрывающими фигурными скобками:

Правильно:

{{ .foo }}
{{ print "foo" }}
{{- print "bar" -}}

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

{{.foo}}
{{print "foo"}}
{{-print "bar"-}}

По возможности шаблоны должны удалять лишние пробельные символы:

foo:
  {{- range .Values.items }}
  {{ . }}
  {{ end -}}

Блоки (такие как управляющие конструкции) могут иметь отступы для отображения потока кода шаблона.

{{ if $foo -}}
  {{- with .Bar }}Hello{{ end -}}
{{- end -}}

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

Пробельные символы в сгенерированных шаблонах

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

Лучше всего так:

apiVersion: batch/v1
kind: Job
metadata:
  name: example
  labels:
    first: first
    second: second

Так тоже допустимо:

apiVersion: batch/v1
kind: Job

metadata:
  name: example

  labels:
    first: first
    second: second

Но такого следует избегать:

apiVersion: batch/v1
kind: Job

metadata:
  name: example





  labels:
    first: first

    second: second

Комментарии (YAML-комментарии и комментарии шаблонов)

И YAML, и шаблоны Helm имеют маркеры комментариев.

YAML-комментарии:

# Это комментарий
type: sprocket

Комментарии шаблонов:

{{- /*
Это комментарий.
*/}}
type: frobnitz

Комментарии шаблонов следует использовать для документирования возможностей шаблона, например, для пояснения именованного шаблона:

{{- /*
mychart.shortname предоставляет обрезанную до 6 символов версию имени релиза.
*/}}
{{ define "mychart.shortname" -}}
{{ .Release.Name | trunc 6 }}
{{- end -}}

Внутри шаблонов YAML-комментарии могут использоваться, когда полезно, чтобы пользователи Helm могли (возможно) видеть комментарии во время отладки.

# Это может вызвать проблемы, если значение превышает 100Gi
memory: {{ .Values.maxMem | quote }}

Комментарий выше виден, когда пользователь выполняет helm install --debug, тогда как комментарии, указанные в секциях {{- /* */}}, не видны.

Будьте осторожны при добавлении YAML-комментариев # к секциям шаблона, содержащим значения Helm, которые могут потребоваться для некоторых функций шаблона.

Например, если к приведённому выше примеру добавить функцию required, и maxMem не задано, то YAML-комментарий # вызовет ошибку рендеринга.

Правильно: helm template не выполняет рендеринг этого блока

{{- /*
# Это может вызвать проблемы, если значение превышает 100Gi
memory: {{ required "maxMem must be set" .Values.maxMem | quote }}
*/ -}}

Неправильно: helm template возвращает Error: execution error at (templates/test.yaml:2:13): maxMem must be set

# Это может вызвать проблемы, если значение превышает 100Gi
# memory: {{ required .Values.maxMem "maxMem must be set" | quote }}

Смотрите Отладка шаблонов, где приведён другой пример такого поведения — YAML-комментарии остаются без изменений.

Использование JSON в шаблонах и выводе шаблонов

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

Например, этот YAML ближе к обычному методу YAML для выражения списков:

arguments:
  - "--dirname"
  - "/foo"

Но его легче читать, когда он свёрнут в стиле JSON-списка:

arguments: ["--dirname", "/foo"]

Использование JSON для повышения читаемости — хорошая практика. Однако синтаксис JSON не следует использовать для представления более сложных конструкций.

При работе с чистым JSON, встроенным в YAML (например, конфигурация init-контейнера), конечно, уместно использовать формат JSON.