简体中文

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、分支名）生成资源。
参数化测试：基于事件类型创建不同参数的测试流水线。
作为运行时配置模板：为重复执行的 Pipelines 提供标准化运行时配置（参数、工作区、安全上下文等），用户可通过前端 UI 选择匹配模板快速生成符合场景需求的 pipelinerun 实例。

约束与限制

TriggerTemplates 中的参数只能是字符串类型
使用 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/v1beta1
      kind: PipelineRun
      metadata:
        generateName: example-pipeline-run-
      spec:
        pipelineRef:
          name: example-pipeline
        params:
          - name: pipeline-param
            value: $(tt.params.param1)

参数处理

TriggerTemplates 中参数遵循以下原则：

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

资源模板创建流程

事件被检测和处理时：

EventListener 接收事件
拦截器（如配置）处理和过滤事件
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/v1beta1
      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/v1beta1
      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/v1beta1
      kind: PipelineRun
      metadata:
        generateName: build-pipeline-
      spec:
        pipelineRef:
          name: build-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)
    - apiVersion: tekton.dev/v1beta1
      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 相关的重要参数说明

参数替换

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

适用场景

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

约束与限制

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

原则/参数说明

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

例如：

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

JSON 处理

在 TriggerTemplates 中处理 JSON 数据时需注意特殊事项。

适用场景

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

约束与限制

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

原则/参数说明

处理 JSON 对象时：

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

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

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

Operator

管道

Triggers

Results

TriggerTemplate

目录

术语说明

为什么需要 TriggerTemplate

事件驱动资源创建的挑战

TriggerTemplate 如何解决这些问题

优势

适用场景

约束与限制

原则

TriggerTemplate 结构

参数处理

资源模板创建流程

运行时配置模板

配置示例

基础 CI 流水线模板

多环境部署模板

多资源模板示例

运行时配置模板示例

与 TriggerTemplate 相关的重要参数说明

参数替换

适用场景

约束与限制

原则/参数说明

JSON 处理

适用场景

约束与限制

原则/参数说明

参考资料

Operator

管道

Triggers

Results

#TriggerTemplate

#目录

#术语说明

#为什么需要 TriggerTemplate

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

#TriggerTemplate 如何解决这些问题

#优势

#适用场景

#约束与限制

#原则

#TriggerTemplate 结构

#参数处理

#资源模板创建流程

#运行时配置模板

#配置示例

#基础 CI 流水线模板

#多环境部署模板

#多资源模板示例

#运行时配置模板示例

#与 TriggerTemplate 相关的重要参数说明

#参数替换

#适用场景

#约束与限制

#原则/参数说明

#JSON 处理

#适用场景

#约束与限制

#原则/参数说明

#参考资料

TriggerTemplate

目录

术语说明

为什么需要 TriggerTemplate

事件驱动资源创建的挑战

TriggerTemplate 如何解决这些问题

优势

适用场景

约束与限制

原则

TriggerTemplate 结构

参数处理

资源模板创建流程

运行时配置模板

配置示例

基础 CI 流水线模板

多环境部署模板

多资源模板示例

运行时配置模板示例

与 TriggerTemplate 相关的重要参数说明

参数替换

适用场景

约束与限制

原则/参数说明

JSON 处理

适用场景

约束与限制

原则/参数说明

参考资料