Alauda DevOps Pipelines Docs
简体中文

TriggerTemplate

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

目录

术语解释

术语描述
TriggerTemplate一个 Tekton 资源，定义在检测到事件时要创建哪些资源。
ResourceTemplate在 TriggerTemplate 内定义要创建的 Kubernetes 资源的规格。
ParameterTriggerTemplate 中的一个变量，可以通过 TriggerBindings 用事件有效负载中的数据填写。
$(tt.params.x)用于在资源模板中引用参数的语法。
generateName一个 Kubernetes 元数据字段，通过添加随机后缀来创建具有唯一名称的资源。

为什么需要 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.parameter-name) 引用参数。

  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 动态和可重用的核心机制。

适用场景

  • 将提交 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 对象时：

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

参考资料

本页概览