#Настройка пользовательских почтовых шаблонов

#Введение

В этом руководстве объясняется, как добавить новый пользовательский шаблон почтового уведомления для Task Send Mail.

#Сценарии

Для большинства вариантов использования сначала применяйте встроенные шаблоны:

• Шаблон почты по умолчанию: выводит базовую информацию о текущем PipelineRun.
• Пользовательский шаблон почты: поддерживает пользовательское содержимое письма через предоставленные параметры шаблона.

Если встроенные шаблоны не соответствуют вашим требованиям, следуйте этому руководству, чтобы создать и настроить новый шаблон.

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

• Task Send Mail доступен в вашем кластере.
• У вас есть разрешение на создание ConfigMap в целевом пространстве имен шаблона.

#Поддержка шаблонов в Send Mail

Task Send Mail поддерживает рендеринг на основе шаблонов для subject, body и contentType. При ссылке на общий шаблон ConfigMap команды могут централизованно поддерживать содержимое писем и повторно использовать один и тот же шаблон в нескольких pipeline.

Подробности о процессе рендеринга, встроенных переменных и renderTemplateValues см. в разделе Поддерживаемые параметры шаблона для Tasks.

#Шаги

#1. Создайте ConfigMap шаблона

Создайте ConfigMap и задайте параметры следующим образом:

Рекомендуемое пространство имен:

• По возможности размещайте ConfigMap шаблона в kube-public. kube-public — это часто используемое общее пространство имен, которое упрощает повторное использование одного и того же шаблона ресурсами TaskRun из разных пространств имен.
• Если вы храните шаблон в другом пространстве имен, явно укажите renderTemplateNamespace на это пространство имен в параметрах Task/Pipeline. Подробности см. в разделе Поддерживаемые параметры шаблона для Tasks.

Обязательные параметры:

• Метка tekton.alaudadevops.io/template-type: mail: помечает этот ConfigMap как почтовый шаблон, чтобы webhook мог определить его как источник рендеринга для Send Mail.
• Ключи данных subject.tpl, body.tpl, contentType.tpl: рендерятся с использованием синтаксиса Go template (gotemplate) и сопоставляются с параметрами subject, body и contentType. О синтаксисе gotemplate см. в документации Go text/template. Доступные переменные шаблона см. в разделе Поддерживаемые параметры шаблона для Tasks.

Необязательные параметры:

• Аннотация tekton.alaudadevops.io/template-display-name: понятное человеку имя, отображаемое в селекторах UI и панелях предварительного просмотра.
• Аннотация style.tekton.dev/descriptors: задает вложенную форму для renderTemplateValues в UI, чтобы пользователи могли заполнять переменные шаблона с помощью элементов формы вместо ручного редактирования YAML. О синтаксисе и шаблонах дескрипторов см. в разделе Как настроить динамические формы.

Пример:

apiVersion: v1
kind: ConfigMap
metadata:
  name: release-mail-template
  namespace: kube-public
  labels:
    tekton.alaudadevops.io/template-type: mail
  annotations:
    tekton.alaudadevops.io/template-display-name: "Release Mail Template"
    style.tekton.dev/descriptors: |
      - path: params.extraMessage
        x-descriptors:
          - urn:alm:descriptor:label:en:Extra Message
          - urn:alm:descriptor:description:en:Additional message shown in mail body.
          - urn:alm:descriptor:com.tectonic.ui:text
          - urn:alm:descriptor:placeholder:en:Input an extra message
data:
  subject.tpl: "PipelineRun {{ .context.pipelineRun.name }} - {{ .tasks.status }}"
  body.tpl: |
    PipelineRun: {{ .context.pipelineRun.name }}
    Status: {{ .tasks.status }}
    Message: {{ .values.extraMessage }}
  contentType.tpl: "text/plain; charset=UTF-8"

#2. Настройте pipeline для использования вашего шаблона

Задайте renderTemplateName и renderTemplateNamespace, затем передайте пользовательские значения через renderTemplateValues.

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: demo-pipeline-with-mail-template
spec:
  workspaces:
    - name: smtp-credentials
  tasks:
    - name: build
      taskRef:
        name: build-task
  finally:
    - name: notify
      taskRef:
        name: send-mail
      params:
        - name: sendMailImage
          value: registry.alauda.cn:60070/devops/tektoncd/hub/msmtp:latest
        - name: renderTemplateName
          value: release-mail-template
        - name: renderTemplateNamespace
          value: kube-public
        - name: renderTemplateValues
          value: |
            extraMessage: "Project: {{ .project }}, Namespace: {{ .namespace }}"
        - name: from
          value: no-reply@example.com
        - name: to
          value:
            - team@example.com
      workspaces:
        - name: smtp-credentials
          workspace: smtp-credentials

#3. Проверьте результаты рендеринга

Проверьте измененный TaskRun и убедитесь, что subject, body и contentType были добавлены в spec.params.

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: demo-pipeline-with-mail-template-notify
  namespace: demo
spec:
  taskRef:
    name: send-mail
  params:
    - name: renderTemplateName
      value: release-mail-template
    - name: renderTemplateNamespace
      value: kube-public
    - name: renderTemplateValues
      value: |
        extraMessage: "Project: demo, Namespace: demo"
    - name: subject
      value: "PipelineRun demo-pipeline-run - Succeeded"
    - name: body
      value: |
        PipelineRun: demo-pipeline-run
        Status: Succeeded
        Message: Project: demo, Namespace: demo
    - name: contentType
      value: "text/plain; charset=UTF-8"

Если рендеринг завершается неудачно, проверьте аннотацию tekton.alaudadevops.io/template-render-error у TaskRun.

#FAQ

#Нужно ли настраивать style.tekton.dev/descriptors?

Нет. Это необязательно. Настраивайте его только в том случае, если вам нужна структурированная UI-форма для renderTemplateValues.

#Можно ли использовать встроенные переменные и values.xxx в одном шаблоне?

Да. Вы можете комбинировать встроенные переменные, например .context.pipelineRun.name, .tasks.status, с пользовательскими значениями, такими как .values.extraMessage.

#Что произойдет, если renderTemplateName не задан?

Рендеринг шаблона будет пропущен. Вам нужно будет указать параметры subject и body вручную.

#Какое пространство имен следует использовать для ConfigMap шаблона?

По возможности используйте kube-public. Это общее пространство имен, которое упрощает повторное использование одного и того же шаблона ресурсами TaskRun из разных пространств имен.

Если ConfigMap шаблона хранится в другом пространстве имен, явно задайте renderTemplateNamespace для этого пространства имен. Подробности о параметрах см. в разделе Поддерживаемые параметры шаблона для Tasks.

#Что нужно проверить в первую очередь, если рендеринг не работает?

1. Убедитесь, что renderTemplateName и renderTemplateNamespace указывают на существующий ConfigMap шаблона.
2. Убедитесь, что ConfigMap содержит метку tekton.alaudadevops.io/template-type: mail и обязательные ключи subject.tpl, body.tpl и contentType.tpl.
3. Проверьте аннотацию TaskRun tekton.alaudadevops.io/template-render-error на наличие конкретного сообщения об ошибке.