Шаблонные функции Nelm целиком

Что нужно знать перед уроком

M4 урок 6 — первое использование werf_secret_file. Этот урок собирает все специфичные для Werf/Nelm (не входящие в стандартный Helm/Sprig) шаблонные функции.

Теория

werf_secret_file — встраивание расшифрованного файла

1
2

data:
  config.yaml: { { werf_secret_file "config.yaml" | b64enc } }

Разобрано в M4 уроке 6 — расшифровывает файл из .helm/secret/ в памяти во время рендера, подходит для данных, слишком объёмных для secret-values.yaml (сертификаты, приватные ключи).

Debug-функции: видимы только в debug-логе, не влияют на рендер

Четыре функции — dump_debug, printf_debug, include_debug, tpl_debug — выводят диагностическую информацию в лог, но не в итоговый рендеренный манифест. Это принципиально отличает их от обычного {{ ... }}-вывода: они активны только при включённом debug-уровне логирования Nelm, и в обычном режиме работы полностью «невидимы» — ни в манифесте, ни в стандартном выводе.

1

{ { dump_debug $ } }

dump_debug печатает полное дерево контекста ($ — корневой контекст) в лог — удобно для быстрой диагностики «что вообще доступно в этой точке шаблона», без необходимости добавлять и потом убирать временный {{ $ | toYaml }} прямо в манифест (что испортило бы валидный YAML).

1

{ { printf_debug "replicaCount: %d" .Values.replicaCount } }

printf_debug — аналог стандартного printf, но с выводом в debug-лог вместо манифеста; удобен для точечной проверки значения конкретной переменной без риска сломать структуру YAML случайным выводом непредвиденного типа данных.

1

{ { include_debug "myapp.labels" . | nindent 4 } }

include_debug — debug-вариант include, позволяющий проверить, что именно вернёт именованный шаблон (define) с данным контекстом, прежде чем окончательно встраивать его в манифест через обычный include.

1

{{ tpl_debug "{{ .Values.template }}" . }}

tpl_debug — debug-вариант tpl (функции, рендерящей строку как Go-шаблон во время выполнения) — полезен при отладке значений, содержащих вложенные шаблонные выражения (частый паттерн для конфигурационных файлов, генерируемых из values.yaml).

Почему debug-функции существуют отдельно, а не просто через {{- if $.Debug }}

Явные debug-функции устраняют необходимость вручную оборачивать отладочный вывод условными конструкциями и вручную их убирать перед коммитом — разработчик может оставить dump_debug/printf_debug прямо в шаблоне на постоянной основе (как «встроенные точки диагностики»), не рискуя случайно сломать production-рендер, потому что они физически не активируются вне debug-режима.

Частые ошибки и подводные камни

• Использовать обычный {{ .Values.foo | toYaml }} для отладки прямо в манифесте и забывать убрать перед коммитом. Это может сломать структуру итогового YAML или случайно раскрыть секретные значения в рендере — debug-функции решают эту проблему принципиально, будучи невидимыми вне debug-режима.
• Ожидать, что debug-функции выводятся в обычном режиме работы nelm chart render. Необходимо явно включить debug log level (см. флаги nelm/werf для уровня логирования), иначе вывод этих функций просто не появится нигде.
• Путать tpl_debug и include_debug. tpl рендерит строку как шаблон (полезно для динамически формируемых строк-шаблонов), include рендерит именованный define-блок — разные механизмы для разных сценариев динамического шаблонирования.

Практика в кластере

Практики в кластере в этом уроке нет — материал относится к стадии Render (разработка/CI), а не к состоянию объектов в кластере.

Практика разработки

Добавьте временную диагностическую строку в шаблон Deployment пакета Umami:

1

{ { dump_debug .Values.umami } }

Соберите рендер с включённым debug-логированием и убедитесь, что вывод появляется в логе, но не в самом манифесте:

1
2

nelm chart render . -r umami --log-level debug 2>&1 | grep -A5 "umami:"
nelm chart render . -r umami | grep -c "dump_debug"   # должно быть 0 — функция не попадает в манифест

Шпаргалка команд урока

Полный список Werf/Nelm-специфичных функций — 📋 nelm .

Вопросы для самопроверки

Рекомендуемая литература

Официальная документация

• Deckhouse — Nelm-аннотации для Application

Статьи и блоги

• Вышла werf 2.0: новый движок развёртывания Nelm — Flant на Habr.
• Представляем werf 1.0 stable: GitOps и Helm — Flant на Habr.
• GitLab + K8s + Werf — Habr.

Книги

• Matt Butcher, Matt Farina, Josh Dolitsky. Learning Helm. 2019. ISBN 978-1492036781.

Связанные материалы

• Предыдущий урок: M7.06 — Sensitive-данные в манифестах.
• Следующий урок: M7.08 — Семь готовых use-case’ов.

✓ Урок пройден — все вопросы самопроверки отвечены верно