#Task 支持的模板参数

#简介

本指南介绍了面向 Task 的模板驱动参数渲染的用途和数据模型。
借助 renderTemplateName 和 renderTemplateNamespace，Task 可以指向一个模板 ConfigMap，并动态渲染参数。

#场景

当你希望通过模板集中管理 Task 参数值，而不是在每个 TaskRun 中硬编码这些值时，可以使用此机制。
例如，Send Mail Task 可以从共享的邮件模板中渲染 subject、body 和 contentType。请参见 Configure Custom Mail Template。

#前提条件

• 你的 Task 支持 renderTemplateName 和 renderTemplateNamespace。
• 目标模板 ConfigMap 存在于引用的命名空间中。
• 你熟悉 Go template (gotemplate) 语法。

#模板渲染的工作方式

模板渲染使用 Go template (gotemplate) 语法。有关语法细节，请参见 Go text/template documentation。

1. webhook 读取 renderTemplateName、renderTemplateNamespace 和 renderTemplateValues。
2. 它加载目标模板 ConfigMap。
3. 它使用 renderTemplateValues 和内置变量来渲染该 ConfigMap 中的模板文件。
4. 它将渲染后的参数注入到 TaskRun 中。

#模板数据模型

模板渲染数据有两个来源：

• 来自 renderTemplateValues 的用户提供值
• 由 template-render 服务准备的内置变量

#1. 来自 renderTemplateValues 的用户提供值

renderTemplateValues 是一个 YAML 格式的字符串。其中定义的值可在模板文件中通过 {{ .values.<key> }} 访问。

示例 renderTemplateValues 内容：

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

在存储于模板 ConfigMap data 字段下的模板文件中，你可以通过 {{ .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 中渲染后的参数

渲染完成后，ConfigMap.data 中的每个 *.tpl 条目都会转换为一个 TaskRun 参数：

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

渲染后的键值对会追加到 TaskRun 的 spec.params 中。

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"

#常见问题

#timeZone 的默认值是什么，如何更改？

默认值是 UTC。
如果你想更改它，请在 configure-tektoncd-enhancement-configmap 中更新 template-render.time-zone。

#如果 platformURL 或 detailsURL 不符合预期，该怎么办？

platformURL 在集群部署期间确定。
如果它不符合预期，请更新 kube-public 命名空间下 global-info ConfigMap 中的 data.platformURL。

如果 detailsURL 不符合预期，请在 configure-tektoncd-enhancement-configmap 中更新 template-render.details-url-template。

#renderTemplateValues 和内置变量有什么区别？

renderTemplateValues 包含用户自定义值，并以 .values.<key> 的形式暴露。
内置变量由渲染器根据运行时上下文生成，例如 .platformURL、.project 和 .tasks.status。

#我必须使用 renderTemplateValues 吗？

不需要。你也可以只使用内置变量。
当你需要使用不属于内置变量的自定义键时，才使用 renderTemplateValues。

#ConfigMap data 中的 *.tpl 键如何映射到 TaskRun 参数？

每个键中的 .tpl 后缀都会被移除。
例如，subject.tpl 会变成 TaskRun 中的 subject 参数。

#为什么 project 或 cluster 变量为空？

通常，只有通过 UI 创建的命名空间才会自动注入 project 和 cluster 变量。
这是因为它们是从 Namespace 资源上的 cpaas.io/cluster 和 cpaas.io/project 标签中读取的。
你也可以手动为命名空间添加这些标签。