Tasks 支持的模板参数

简介

本指南说明了用于 Tasks 的模板驱动参数渲染的用途和数据模型。通过 renderTemplateName 和 renderTemplateNamespace,Task 可以指向一个模板 ConfigMap,并动态渲染参数。

场景

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

前提条件

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

模板渲染的工作方式

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

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

模板数据模型

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

  • 来自 renderTemplateValues 的用户提供值
  • 模板渲染服务准备的内置变量

1. 来自 renderTemplateValues 的用户提供值

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

示例 renderTemplateValues 内容:

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

在存储于模板 ConfigMap data 字段下的模板文件中,你可以将它们引用为 {{ .values.title }} 和 {{ .values.summary }}。

2. 内置变量

除了 .values 之外,渲染器还会注入以下内置变量:

变量类型描述仅 Pipeline
platformURLstring平台的基础 URL。它从 kube-public 命名空间下 global-info ConfigMap 的 data.platformURL 中读取。例如:https://devops.example.com。否
detailsURLstring运行详情页面的 URL。例如:https://devops.example.com/console-acp/workspace/demo~cluster-a~dev/pipeline/pipelineRuns/detail/pr-abc123。要调整此值,请更新 configure-tektoncd-enhancement-configmap 中的 template-render.details-url-template。否
startsAttime当前执行的开始时间。否
timeZonestring为模板渲染配置的全局时区。该值必须是有效 time zone 的名称。要调整此值,请更新 configure-tektoncd-enhancement-configmap 中的 template-render.time-zone。否
creatorstring触发该执行的用户。否
projectstring执行上下文的项目名称。否
clusterstring执行上下文的集群名称。否
namespacestringTaskRun 运行所在的命名空间。否
taskRunNamestring当前 TaskRun 名称。否
isPipelineRunbool当前运行是否属于 PipelineRun。否
runTypestring执行类型(TaskRun 或 PipelineRun)。否
pipelineRunNamestring当前 PipelineRun 名称。是
pipelineRunUIDstring当前 PipelineRun UID。是
params.<paramName>string | []string | map[string]string某个 Pipeline 参数键的值。具体类型取决于 Pipeline 参数类型。是
context.pipeline.namestringPipeline 名称。是
context.pipelineRun.namestringPipelineRun 名称。是
context.pipelineRun.namespacestringPipelineRun 命名空间。是
workspaces.<workspaceName>.boundstringWorkspace 是否已绑定。若 Workspace 声明包含 optional: true,且 PipelineRun 省略了 Workspace 绑定,则为 "false"。是
tasks.statusstringtasks 部分下所有 pipelineTasks 的汇总状态(不包括 finally 部分)。取值:Succeeded、Failed、Completed 或 None。是
tasks.<pipelineTaskName>.statusstring指定 pipelineTask 的执行状态。取值:Succeeded、Failed 或 None。是
tasks.<taskName>.results.<resultName>string | []string | map[string]string指定 task result 的结果值。具体类型取决于 result 类型。是

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