TriggerTemplate

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

术语说明

术语描述
TriggerTemplate一种 Tekton 资源,用于定义检测到事件时要创建的资源。
ResourceTemplate在 TriggerTemplate 中定义的 Kubernetes 资源规范,用于指定要创建的资源。
参数TriggerTemplate 中的变量,可通过 TriggerBindings 使用事件负载中的数据进行填充。
$(tt.params.x)用于在资源模板中引用参数的语法。
generateNameKubernetes 元数据字段,通过添加随机后缀来创建具有唯一名称的资源。

为什么需要 TriggerTemplate

事件驱动资源创建面临的挑战

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

  1. 动态创建资源:流水线等资源需要使用每个事件特有的信息进行创建。
  2. 参数化:不同事件需要向流水线传递不同的参数。
  3. 可复用性:相同的资源创建模式通常需要在多个事件之间重复使用。
  4. 模板化:为每种事件类型手动创建资源容易出错,且难以扩展。

如果没有 TriggerTemplate,解决这些挑战将需要:

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

TriggerTemplate 如何解决这些问题

TriggerTemplate 提供了一种声明式、Kubernetes 原生的方式,用于:

  1. 定义资源蓝图:明确指定事件发生时应创建的资源。
  2. 参数化资源:使用从事件中提取的参数来定制资源。
  3. 确保一致性:针对相似事件,以相同的结构一致地创建资源。
  4. 分离关注点:将事件检测(EventListener)和数据提取(TriggerBinding)与资源创建解耦。
  5. 实现可复用性:一次定义模板,并在多个触发器之间重复使用。

这种方式以清晰的声明式形式定义检测到事件时应执行的操作,使 CI/CD 系统更易于维护和扩展。

优势

  • 声明式定义:使用 Kubernetes 原生 YAML 定义要创建的资源
  • 参数化:使用事件数据动态定制资源
  • 可复用性:一次创建模板,并在多个触发器之间重复使用
  • 关注点分离:明确分离事件检测、数据提取和资源创建
  • 默认值:为事件中可能不存在的参数提供备用值
  • 动态命名:生成唯一命名的资源以避免冲突
  • 多个资源:根据单个事件创建多个资源
  • 资源验证:在创建资源之前于运行时对其进行验证

适用场景

TriggerTemplate 在以下场景中不可或缺:

  1. 自动化 CI/CD 流水线:在代码推送或创建拉取请求时自动创建流水线运行。

  2. 多环境部署:使用包含不同参数的同一模板,将应用部署到各种环境。

  3. 事件驱动工作流:响应外部系统事件创建资源,例如问题更新或监控警报。

  4. 动态资源创建:使用每个事件特有的参数生成资源,例如提交 ID 或分支名称。

  5. 参数化测试:根据事件类型使用不同参数创建测试流水线。

  6. 作为运行时配置模板:为重复执行的 Pipeline 提供标准化的运行时配置(例如参数、工作区、安全上下文等)。用户可以通过前端 UI 选择匹配的模板,快速生成符合场景要求的 pipelinerun 实例。

约束和限制

  • TriggerTemplate 中的参数只能是字符串值
  • 将 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: Description of parameter 1
      default: default-value  # Optional 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 中的参数遵循以下原则:

  1. 声明:必须在 params 部分声明参数,并指定名称,可选择性地指定描述和默认值。

  2. 引用:在资源模板中使用语法 $(tt.params.parameter-name) 引用参数。

  3. 默认值:如果 TriggerBinding 未提供参数,则在指定默认值的情况下使用该默认值。

  4. 字符串值:所有参数值都按字符串处理,即使它们表示数字或 JSON 对象。

  5. 特殊字符:带有数字前缀或特殊字符的参数,在资源模板中可能需要使用引号。

资源模板创建

检测并处理事件时:

  1. EventListener 接收事件
  2. Interceptor 处理并筛选事件(如果已配置)
  3. TriggerBinding 从事件中提取数据
  4. TriggerTemplate 接收提取的参数
  5. 在资源模板中进行参数替换
  6. 使用替换后的值创建 Kubernetes 资源

每个创建的资源都会接收用于跟踪其来源的标签:

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

运行时配置模板

  1. 标签约定
  • triggertemplate.triggers.tekton.dev/usage: runtime-config

    必须设置为 runtime-config,以标识模板的用途。

  • tekton.dev/pipeline: <pipeline-name>

    将模板与特定流水线关联。

  • triggertemplate.triggers.tekton.dev/runtime-config-default: "true"

    可选,用于将模板标记为流水线的默认配置。如果存在多个默认模板,则选择创建时间戳最新的模板。

  1. 资源模板约定
  • 在 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: The git commit SHA
    - name: git-repo-url
      description: The git repository URL
    - name: git-repo-name
      description: The name of the git repository
  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: Deployment environment
      default: development
    - name: image-tag
      description: Image tag to deploy
    - name: app-name
      description: Application name
  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: The git commit 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 插入 PipelineRuns
  • 在流水线参数中使用仓库 URL 和分支名称
  • 将事件元数据传递给流水线
  • 使用特定于事件的信息自定义资源名称

约束和限制

  • 仅支持字符串值
  • JSON 对象需要特殊处理
  • 以数字开头的参数可能需要加引号

原理/参数说明

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

例如:

params:
  - name: git-revision
    description: The git commit 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 对象时:

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

参考资料