TriggerTemplate

TriggerTemplate 是 Tekton Triggers 中的一个强大组件，用于定义在检测到事件时应创建的资源蓝图。它充当事件驱动流水线的动作部分，明确指定应针对事件实例化哪些 Kubernetes 资源（通常是 TaskRuns 或 PipelineRuns）。

术语说明

术语	说明
TriggerTemplate	定义在检测到事件时应创建哪些资源的 Tekton 资源。
ResourceTemplate	在 TriggerTemplate 中定义的 Kubernetes 资源规范，用于创建资源。
Parameter	TriggerTemplate 中的变量，可通过 TriggerBindings 从事件负载中填充数据。
$(tt.params.x)	在资源模板中引用参数的语法。
generateName	Kubernetes 元数据字段，通过添加随机后缀创建唯一名称的资源。

为什么需要 TriggerTemplate

事件驱动资源创建的挑战

在响应外部事件的 CI/CD 系统中，创建资源时会遇到以下挑战：

动态资源创建：需要根据每个事件的具体信息创建资源，如流水线运行。
参数化：不同事件需要传递不同参数给流水线。
可复用性：相同的资源创建模式常常需要在多个事件中复用。
模板化：为每种事件类型手动创建资源容易出错且难以扩展。

如果没有 TriggerTemplates，解决这些问题需要：

为每个事件编写自定义脚本生成 Kubernetes 资源
处理复杂的参数替换逻辑
在不同事件处理器间重复定义资源
手动同步事件数据与资源创建

TriggerTemplate 如何解决这些问题

TriggerTemplate 提供了一种声明式、Kubernetes 原生的方式来：

定义资源蓝图：明确指定事件发生时应创建哪些资源。
参数化资源：使用从事件中提取的参数定制资源。
保证一致性：为类似事件创建结构一致的资源。
职责分离：将事件检测（EventListener）和数据提取（TriggerBinding）与资源创建解耦。
支持复用：定义一次模板，可在多个触发器中复用。

这种方法为事件检测后的操作定义了清晰、声明式的流程，使 CI/CD 系统更易维护和扩展。

优势

声明式定义：使用 Kubernetes 原生 YAML 定义要创建的资源
参数化：动态使用事件数据定制资源
可复用性：模板定义一次，多处触发器复用
职责分离：事件检测、数据提取与资源创建清晰分离
默认值支持：为可能缺失的参数提供默认值
动态命名：生成唯一命名的资源避免冲突
多资源支持：单个事件可创建多个资源
资源校验：资源在运行时创建前进行校验

适用场景

TriggerTemplates 在以下场景中至关重要：

自动化 CI/CD 流水线：代码推送或拉取请求打开时自动创建流水线运行。
多环境部署：使用相同模板，传入不同参数部署到不同环境。
事件驱动工作流：响应外部系统事件（如问题更新、监控告警）创建资源。
动态资源创建：根据事件特定参数（如提交 ID、分支名）生成资源。
参数化测试：基于事件类型创建不同参数的测试流水线。
作为运行时配置模板：为重复执行的流水线提供标准化运行时配置（参数、工作区、安全上下文等），用户可通过前端 UI 选择匹配模板快速生成满足场景需求的 pipelinerun 实例。

约束与限制

TriggerTemplate 中的参数只能是字符串类型
使用 JSON 对象作为参数时需谨慎处理
资源校验发生在运行时，而非创建时
默认服务账户权限可能需扩展以支持非 Tekton 资源
嵌入资源必须包含在使用它们的 PipelineRun 或 TaskRun 中
带数字前缀的参数名需特殊处理

原则

TriggerTemplate 结构

TriggerTemplate 主要包含两个部分：

参数定义：声明可在资源模板中使用的参数
资源模板：定义要创建的 Kubernetes 资源

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: example-template
spec:
  params:
    - name: param1
      description: 参数1的描述
      default: default-value  # 可选默认值
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: example-pipeline-run-
      spec:
        pipelineRef:
          name: example-pipeline
        params:
          - name: pipeline-param
            value: $(tt.params.param1)

参数处理

TriggerTemplate 中参数遵循以下原则：

声明：参数必须在 params 部分声明，包含名称，可选描述和默认值。
引用：在资源模板中使用 $(tt.params.parameter-name) 语法引用参数。
默认值：若 TriggerBinding 未提供参数，则使用默认值（如果有）。
字符串值：所有参数值均视为字符串，即使表示数字或 JSON 对象。
特殊字符：带数字前缀或特殊字符的参数在资源模板中可能需加引号。

资源模板创建流程

事件被检测和处理时：

EventListener 接收事件
拦截器（Interceptors）处理和过滤事件（如配置）
TriggerBindings 从事件中提取数据
TriggerTemplate 接收提取的参数
在资源模板中进行参数替换
创建带替换值的 Kubernetes 资源

每个创建的资源都会带有以下标签以追踪来源：

tekton.dev/eventlistener: <EventListenerName>
tekton.dev/triggers-eventid: <EventID>

运行时配置模板

标签约定

triggertemplate.triggers.tekton.dev/usage: runtime-config

必须设置为 runtime-config，用于标识模板用途。
tekton.dev/pipeline: <pipeline-name>

关联模板对应的流水线。
triggertemplate.triggers.tekton.dev/runtime-config-default: "true"

可选，标记模板为该流水线的默认配置。若存在多个默认模板，则选择创建时间最新的。

资源模板约定

spec.resourcetemplates 中只能定义一个 PipelineRun 资源。
必须包含 pipelineRef 引用目标流水线。
支持 PipelineRun 的所有运行时配置字段，如 params、workspaces、podTemplate 等。

配置示例

基础 CI 流水线模板

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: ci-pipeline-template
spec:
  params:
    - name: git-revision
      description: Git 提交 SHA
    - name: git-repo-url
      description: Git 仓库 URL
    - name: git-repo-name
      description: Git 仓库名称
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: $(tt.params.git-repo-name)-ci-
      spec:
        pipelineRef:
          name: ci-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)
          - name: repo-url
            value: $(tt.params.git-repo-url)
        workspaces:
          - name: source
            emptyDir: {}

多环境部署模板

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: deploy-template
spec:
  params:
    - name: environment
      description: 部署环境
      default: development
    - name: image-tag
      description: 部署的镜像标签
    - name: app-name
      description: 应用名称
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: deploy-$(tt.params.app-name)-$(tt.params.environment)-
      spec:
        pipelineRef:
          name: deployment-pipeline
        params:
          - name: target-environment
            value: $(tt.params.environment)
          - name: image-tag
            value: $(tt.params.image-tag)
          - name: application
            value: $(tt.params.app-name)

多资源模板示例

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: multi-resource-template
spec:
  params:
    - name: git-revision
      description: Git 提交 SHA
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: build-pipeline-
      spec:
        pipelineRef:
          name: build-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: test-pipeline-
      spec:
        pipelineRef:
          name: test-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)

运行时配置模板示例

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: deploy-pipeline-staging-config
  labels:
    triggertemplate.triggers.tekton.dev/usage: runtime-config
    tekton.dev/pipeline: deploy-pipeline
    triggertemplate.triggers.tekton.dev/runtime-config-default: true
spec:
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: deploy-pipeline-staging-
      spec:
        pipelineRef:
          name: deploy-pipeline
        params:
          - name: environment
            value: "staging"
          - name: replicas
            value: "2"
        workspaces:
          - name: config
            configMap:
              name: staging-config

TriggerTemplate 相关重要参数说明

参数替换

参数替换是 TriggerTemplate 动态化和复用的核心机制。

适用场景

将提交 SHA 插入 PipelineRun
在流水线参数中使用仓库 URL 和分支名
向流水线传递事件元数据
使用事件特定信息定制资源名称

约束与限制

仅支持字符串值
JSON 对象需特殊处理
带数字前缀的参数可能需加引号

原则/参数说明

参数替换语法为 $(tt.params.parameter-name)，其中 parameter-name 是 TriggerTemplate params 部分定义的参数名。

示例：

params:
  - name: git-revision
    description: Git 提交 SHA
resourcetemplates:
  - apiVersion: tekton.dev/v1
    kind: PipelineRun
    spec:
      params:
        - name: revision
          value: $(tt.params.git-revision)

JSON 处理

在 TriggerTemplate 中处理 JSON 数据时需注意。

适用场景

向流水线传递复杂数据结构
处理包含嵌套 JSON 的 webhook 负载
创建需要 JSON 配置的资源

约束与限制

JSON 对象必须作为字符串处理
引号转义较为复杂
旧版模板可能需要特殊注解

原则/参数说明

处理 JSON 对象时：

在资源模板中使用 JSON 参数时，不要加引号包裹

对于需要转义引号的旧版模板，添加注解：

metadata:
  annotations:
    triggers.tekton.dev/old-escape-quotes: "true"

TriggerTemplate

目录

术语说明

为什么需要 TriggerTemplate

事件驱动资源创建的挑战

TriggerTemplate 如何解决这些问题

优势

适用场景

约束与限制

原则

TriggerTemplate 结构

参数处理

资源模板创建流程

运行时配置模板

配置示例

基础 CI 流水线模板

多环境部署模板

多资源模板示例

运行时配置模板示例

TriggerTemplate 相关重要参数说明

参数替换

适用场景

约束与限制

原则/参数说明

JSON 处理

适用场景

约束与限制

原则/参数说明

参考资料

#TriggerTemplate

#目录

#术语说明

#为什么需要 TriggerTemplate

#事件驱动资源创建的挑战

#TriggerTemplate 如何解决这些问题

#优势

#适用场景

#约束与限制

#原则

#TriggerTemplate 结构

#参数处理

#资源模板创建流程

#运行时配置模板

#配置示例

#基础 CI 流水线模板

#多环境部署模板

#多资源模板示例

#运行时配置模板示例

#TriggerTemplate 相关重要参数说明

#参数替换

#适用场景

#约束与限制

#原则/参数说明

#JSON 处理

#适用场景

#约束与限制

#原则/参数说明

#参考资料

TriggerTemplate

目录

术语说明

为什么需要 TriggerTemplate

事件驱动资源创建的挑战

TriggerTemplate 如何解决这些问题

优势

适用场景

约束与限制

原则

TriggerTemplate 结构

参数处理

资源模板创建流程

运行时配置模板

配置示例

基础 CI 流水线模板

多环境部署模板

多资源模板示例

运行时配置模板示例

TriggerTemplate 相关重要参数说明

参数替换

适用场景

约束与限制

原则/参数说明

JSON 处理

适用场景

约束与限制

原则/参数说明

参考资料