Alauda DevOps Pipelines Docs
简体中文

TriggerTemplate

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

目录

术语说明

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

为什么需要 TriggerTemplate

事件驱动资源创建的挑战

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

  1. 动态资源创建：需要根据每个事件的特定信息创建资源，如流水线。
  2. 参数化：不同事件需要传递不同参数给流水线。
  3. 可复用性：相同的资源创建模式通常需要在多个事件间复用。
  4. 模板化：为每种事件类型手动创建资源容易出错且不具扩展性。

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

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

TriggerTemplate 如何解决这些问题

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

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

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

优势

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

适用场景

TriggerTemplates 在以下场景中必不可少：

  1. 自动化 CI/CD 流水线：代码推送或拉取请求打开时自动创建流水线运行。
  2. 多环境部署：使用相同模板，传入不同参数部署到多个环境。
  3. 事件驱动工作流：响应外部系统事件（如问题更新或监控告警）创建资源。
  4. 动态资源创建：根据事件特定参数（如提交 ID 或分支名）生成资源。
  5. 参数化测试：根据事件类型创建不同参数的测试流水线。

约束与限制

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

原则

TriggerTemplate 结构

TriggerTemplate 主要包含两个部分：

  1. 参数定义：声明可在资源模板中使用的参数
  2. 资源模板：定义要创建的 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 中参数遵循以下原则：

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

资源模板创建流程

事件被检测和处理时：

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

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

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

配置示例

基础 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)

与 TriggerTemplate 相关的重要参数说明

参数替换

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

适用场景

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

约束与限制

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

原则/参数说明

参数替换语法为 $(tt.params.参数名)，其中 参数名 是 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 对象时：

  1. 在资源模板中使用时，不要将 JSON 参数用引号包裹
  2. 对于需要转义引号的旧版模板，添加注解： 
    metadata:
  annotations:
    triggers.tekton.dev/old-escape-quotes: "true"

参考资料