TriggerTemplate
TriggerTemplate 是 Tekton Triggers 中的一个强大组件,用于定义检测到事件时应创建的资源蓝图。它充当事件驱动流水线的操作部分,明确指定应针对事件实例化哪些 Kubernetes 资源(通常为 TaskRuns 或 PipelineRuns)。
目录
术语说明为什么需要 TriggerTemplate事件驱动资源创建面临的挑战TriggerTemplate 如何解决这些问题优势适用场景约束和限制原则TriggerTemplate 结构参数处理资源模板创建运行时配置模板配置示例基本 CI 流水线模板多环境部署模板包含多个资源的模板运行时配置模板与 TriggerTemplate 相关的重要参数说明参数替换适用场景约束和限制原理/参数说明JSON 处理适用场景约束和限制原理/参数说明参考资料术语说明
为什么需要 TriggerTemplate
事件驱动资源创建面临的挑战
在响应外部事件的 CI/CD 系统中,创建资源时会遇到以下挑战:
- 动态创建资源:流水线等资源需要使用每个事件特有的信息进行创建。
- 参数化:不同事件需要向流水线传递不同的参数。
- 可复用性:相同的资源创建模式通常需要在多个事件之间重复使用。
- 模板化:为每种事件类型手动创建资源容易出错,且难以扩展。
如果没有 TriggerTemplate,解决这些挑战将需要:
- 为每个事件编写用于生成 Kubernetes 资源的自定义脚本
- 使用复杂逻辑处理参数替换
- 在不同事件处理程序之间重复定义资源
- 手动同步事件数据与资源创建过程
TriggerTemplate 如何解决这些问题
TriggerTemplate 提供了一种声明式、Kubernetes 原生的方式,用于:
- 定义资源蓝图:明确指定事件发生时应创建的资源。
- 参数化资源:使用从事件中提取的参数来定制资源。
- 确保一致性:针对相似事件,以相同的结构一致地创建资源。
- 分离关注点:将事件检测(EventListener)和数据提取(TriggerBinding)与资源创建解耦。
- 实现可复用性:一次定义模板,并在多个触发器之间重复使用。
这种方式以清晰的声明式形式定义检测到事件时应执行的操作,使 CI/CD 系统更易于维护和扩展。
优势
- 声明式定义:使用 Kubernetes 原生 YAML 定义要创建的资源
- 参数化:使用事件数据动态定制资源
- 可复用性:一次创建模板,并在多个触发器之间重复使用
- 关注点分离:明确分离事件检测、数据提取和资源创建
- 默认值:为事件中可能不存在的参数提供备用值
- 动态命名:生成唯一命名的资源以避免冲突
- 多个资源:根据单个事件创建多个资源
- 资源验证:在创建资源之前于运行时对其进行验证
适用场景
TriggerTemplate 在以下场景中不可或缺:
-
自动化 CI/CD 流水线:在代码推送或创建拉取请求时自动创建流水线运行。
-
多环境部署:使用包含不同参数的同一模板,将应用部署到各种环境。
-
事件驱动工作流:响应外部系统事件创建资源,例如问题更新或监控警报。
-
动态资源创建:使用每个事件特有的参数生成资源,例如提交 ID 或分支名称。
-
参数化测试:根据事件类型使用不同参数创建测试流水线。
-
作为运行时配置模板:为重复执行的 Pipeline 提供标准化的运行时配置(例如参数、工作区、安全上下文等)。用户可以通过前端 UI 选择匹配的模板,快速生成符合场景要求的 pipelinerun 实例。
约束和限制
- TriggerTemplate 中的参数只能是字符串值
- 将 JSON 对象用作参数时必须谨慎处理
- 资源验证在运行时进行,而非创建时进行
- 对于非 Tekton 资源,可能需要扩展默认服务账户的权限
- 嵌入式资源必须包含在使用它们的 PipelineRun 或 TaskRun 中
- 以数字前缀开头的参数名称需要特殊处理
原则
TriggerTemplate 结构
TriggerTemplate 由两个主要部分组成:
- 参数定义:声明资源模板中可以使用的参数
- 资源模板:定义要创建的 Kubernetes 资源
参数处理
TriggerTemplate 中的参数遵循以下原则:
-
声明:必须在
params部分声明参数,并指定名称,可选择性地指定描述和默认值。 -
引用:在资源模板中使用语法
$(tt.params.parameter-name)引用参数。 -
默认值:如果 TriggerBinding 未提供参数,则在指定默认值的情况下使用该默认值。
-
字符串值:所有参数值都按字符串处理,即使它们表示数字或 JSON 对象。
-
特殊字符:带有数字前缀或特殊字符的参数,在资源模板中可能需要使用引号。
资源模板创建
检测并处理事件时:
- EventListener 接收事件
- Interceptor 处理并筛选事件(如果已配置)
- TriggerBinding 从事件中提取数据
- 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 流水线模板
多环境部署模板
包含多个资源的模板
运行时配置模板
与 TriggerTemplate 相关的重要参数说明
参数替换
参数替换是使 TriggerTemplate 具备动态性和可复用性的核心机制。
适用场景
- 将提交 SHA 插入 PipelineRuns
- 在流水线参数中使用仓库 URL 和分支名称
- 将事件元数据传递给流水线
- 使用特定于事件的信息自定义资源名称
约束和限制
- 仅支持字符串值
- JSON 对象需要特殊处理
- 以数字开头的参数可能需要加引号
原理/参数说明
参数替换的语法为 $(tt.params.parameter-name),其中 parameter-name 是在 TriggerTemplate 的 params 部分中定义的参数名称。
例如:
JSON 处理
在 TriggerTemplate 中处理 JSON 数据时,需要注意一些特殊事项。
适用场景
- 向流水线传递复杂数据结构
- 处理包含嵌套 JSON 的 Webhook 负载
- 创建需要 JSON 配置的资源
约束和限制
- JSON 对象必须作为字符串处理
- 转义引号可能比较困难
- 旧版模板可能需要特殊注解
原理/参数说明
处理 JSON 对象时:
- 在资源模板中使用 JSON 参数时,不要将其括在引号中
- 对于需要转义引号的旧版模板,请添加注解: