#Task 的支持模板参数

#简介

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

#场景

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

#前提条件

• 你的 Task 支持 renderTemplateName 和 renderTemplateNamespace。
• 已安装 artifacthub-shim-extension，并启用了其模板渲染 webhook。
• 目标模板 ConfigMap 存在于所引用的命名空间中。
• 你熟悉 Go template (gotemplate) 语法。

#模板渲染的工作原理

模板渲染使用 Go template (gotemplate) 语法。有关语法详情，请参见 Go text/template 文档。

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。 如果你想更改它，请更新 artifacthub-shim chart values 中的 extension.templateRender.timeZone。

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

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

如果 detailsURL 不符合预期，请更新 artifacthub-shim chart values 中的 extension.templateRender.detailsURLTemplate。

#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 标签中获取的。 你也可以手动为该命名空间添加这些标签。