#Поддерживаемые параметры шаблонов для Tasks

#Введение

В этом руководстве объясняются назначение и модель данных рендеринга параметров на основе шаблонов для Tasks. С помощью renderTemplateName и renderTemplateNamespace Task может указывать на шаблонный ConfigMap и динамически рендерить параметры.

#Сценарии

Используйте этот механизм, если хотите централизованно управлять значениями параметров Task через шаблоны, а не задавать значения жестко в каждом TaskRun. Например, Task Send Mail может рендерить subject, body и contentType из общего почтового шаблона. См. Настройка пользовательского шаблона письма.

#Предварительные требования

• Ваш Task поддерживает renderTemplateName и renderTemplateNamespace.
• Целевой шаблонный ConfigMap существует в указанном namespace.
• Вы знакомы со синтаксисом Go template (gotemplate).

#Как работает рендеринг шаблонов

Рендеринг шаблонов использует синтаксис Go template (gotemplate). Подробности синтаксиса см. в документации по Go text/template.

1. Webhook считывает renderTemplateName, renderTemplateNamespace и renderTemplateValues.
2. Он загружает целевой шаблонный ConfigMap.
3. Он рендерит файлы шаблонов в этом ConfigMap, используя как renderTemplateValues, так и встроенные переменные.
4. Он подставляет отрендеренные параметры в TaskRun.

#Модель данных шаблона

Данные для рендеринга шаблона поступают из двух источников:

• Значения, заданные пользователем в renderTemplateValues
• Встроенные переменные, подготовленные сервисом template-render

#1. Значения, заданные пользователем в renderTemplateValues

renderTemplateValues — это строка в формате YAML. Значения, определенные в ней, доступны в файлах шаблонов как {{ .values.<key> }}.

Пример содержимого renderTemplateValues:

title: "Build {{ .tasks.status }}"
summary: "Project={{ .project }}, Namespace={{ .namespace }}"

В файлах шаблонов, хранящихся в поле data шаблонного ConfigMap, вы можете ссылаться на них как {{ .values.title }} и {{ .values.summary }}.

#2. Встроенные переменные

Помимо .values, рендерер также подставляет встроенные переменные:

В gotemplate на переменные можно ссылаться с помощью {{ .xxx }}.

Например, {{ .platformURL }} рендерится как https://devops.example.com.

#Шаги

#Шаг 1: Создайте шаблонный ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: notification-template
  namespace: kube-public
  labels:
    # replace template type as needed, such as "mail"
    tekton.alaudadevops.io/template-type: "<template-type>"
  annotations:
    tekton.alaudadevops.io/template-display-name: "Notification Template"
data:
  title.tpl: "{{ .values.title }}"
  summary.tpl: "{{ .values.summary }}"

#Шаг 2: Настройте TaskRun

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: notify-build-result
  namespace: demo
spec:
  taskRef:
    name: send-notification
  params:
    - name: renderTemplateName
      value: notification-template
    - name: renderTemplateNamespace
      value: kube-public
    - name: renderTemplateValues
      value: |
        title: "Build {{ .tasks.status }}"
        summary: "Project={{ .project }}, Namespace={{ .namespace }}"

#Шаг 3: Проверьте отрендеренные параметры в TaskRun

После рендеринга каждая запись *.tpl в ConfigMap.data преобразуется в параметр TaskRun:

• title.tpl -> title
• summary.tpl -> summary

Отрендеренные пары ключ-значение добавляются в spec.params в TaskRun.

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: notify-build-result
  namespace: demo
spec:
  taskRef:
    name: send-notification
  params:
    - name: renderTemplateName
      value: notification-template
    - name: renderTemplateNamespace
      value: kube-public
    - name: renderTemplateValues
      value: |
        title: "Build {{ .tasks.status }}"
        summary: "Project={{ .project }}, Namespace={{ .namespace }}"
    - name: title
      value: "Build Succeeded"
    - name: summary
      value: "Project=demo, Namespace=demo"

#FAQ

#Каково значение timeZone по умолчанию и как его изменить?

Значение по умолчанию — UTC. Если вы хотите изменить его, обновите template-render.time-zone в configure-tektoncd-enhancement-configmap.

#Что делать, если platformURL или detailsURL не соответствует ожидаемому?

platformURL определяется во время развертывания кластера. Если он не соответствует ожидаемому значению, обновите data.platformURL в ConfigMap global-info в namespace kube-public.

Если detailsURL не соответствует ожидаемому значению, обновите template-render.details-url-template в configure-tektoncd-enhancement-configmap.

#В чем разница между renderTemplateValues и встроенными переменными?

renderTemplateValues содержит пользовательские значения и доступен как .values.<key>. Встроенные переменные генерируются рендерером из контекста выполнения, например .platformURL, .project и .tasks.status.

#Нужно ли использовать renderTemplateValues?

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

#Как ключи *.tpl в ConfigMap.data отображаются в параметры TaskRun?

Суффикс .tpl удаляется из каждого ключа. Например, subject.tpl становится параметром subject в TaskRun.

#Почему переменные project или cluster пустые?

Обычно только namespace, созданные через UI, автоматически подставляют переменные project и cluster. Это связано с тем, что они извлекаются из меток cpaas.io/cluster и cpaas.io/project ресурса Namespace. Вы также можете вручную добавить эти метки в namespace.