运行模板
目录
概述使用场景核心概念运行模板包含的内容创建运行模板从运行模板列表创建复制现有运行模板从现有 PipelineRun 保存使用运行模板运行 Pipeline直接从运行模板运行从常规运行条目重用运行模板在 Pipeline 执行对话框中应用运行模板为运行模板配置 TriggerTrigger 的职责从运行模板创建 Trigger将更新同步到 TriggerTemplate事件变量源事件变量与不同的运行上下文配置事件变量的默认值配置 ScheduledTriggerPipeline 变更与运行模板添加 Pipeline 参数重命名、移除或更改参数添加或更改 Workspace更改其他运行要求更改 Hub Pipeline 版本管理运行模板更新删除最佳实践常见问题直接运行需要提供哪些值?为什么事件变量没有传递到 Pipeline?为什么运行表单中出现了新的 Pipeline 参数?同步对 TriggerTemplate 的更新有什么作用?Pipeline 更改是否需要更新运行模板?删除运行模板会删除历史运行吗?相关主题概述
运行模板保存一组可重复使用的 Pipeline 执行设置。您可以将 Pipeline 参数、Workspaces、Integrations 以及其他运行选项保存到模板中,然后将同一配置 重新用于手动执行、通过 Trigger 进行事件驱动的执行,或通过 ScheduledTrigger 进行计划执行。
当您已经验证 Pipeline 应如何运行时,运行模板会非常有用。运行模板中已填充且未设置为 Set at Runtime 的值会用作运行输入。运行表单不会询问其中的大多数值;
由 Pipeline 的 Integrations 绑定的参数和 Workspaces 是例外,这些内容仍会显示并且可以编辑(请参阅下面的运行步骤)。对于特定运行,只需提供预期会发生变化的值。
可重复使用的 Pipeline 执行设置的产品名称是 Run Template。 与 Trigger 相关的材料可能会使用底层术语 TriggerTemplate。管理可重复使用的运行配置时,请使用 Run Template 条目。
在本指南中,Hub Pipeline 是指通过 Tekton
hub resolver 或产品目录获取的 Pipeline。在当前版本中,目录资源由独立的 ArtifactHub Shim 组件提供;不再随产品提供旧版嵌入式
Tekton Hub runtime。有关 resolver 的行为,请参阅
Hub Resolver 和
ArtifactHub Shim Catalog。
使用场景
运行模板适用于:
- 为开发、测试和生产环境准备单独的执行配置。
- 为不同服务保存构建、测试、扫描或部署设置。
- 从现有 PipelineRun 中保存经过验证的配置。
- 将一个执行配置重复用于手动、事件驱动和计划启动。
核心概念
运行模板保存的是运行 Pipeline 的方式。它不会复制或修改 Pipeline 定义。一个 Pipeline 可以有多个运行模板,例如分别用于开发、测试和生产的模板。
运行模板包含的内容
运行模板通常包含:
运行内容通常分为两类:
- 稳定配置:在运行模板中具有固定值且未设置为
Set at Runtime的内容。它会作为运行输入使用,因此用户无需关注。 - 运行时配置:每次运行都可能发生变化的内容,例如 Git 分支、提交、镜像标签或发布批次。它由用户或 Trigger 事件提供。
创建运行模板
从运行模板列表创建
- 打开 运行模板。
- 点击 创建。
- 选择要运行的 Pipeline。
- 配置 Pipeline 参数、Workspaces、集成和其他运行选项。
- 将每次运行都需要更改的值设置为
Set at Runtime。 - 可选:在 事件 部分中,选择模板应使用其变量的一个或多个事件。同名的事件变量会进行合并。
- 保存运行模板。
复制现有运行模板
- 找到现有运行模板。
- 打开其详情或操作菜单。
- 点击 复制。
- 输入新模板的名称。
- 检查复制的 Pipeline、参数、Workspaces、集成和运行时设置。
- 保存新的运行模板。
复制适用于为其他服务或环境创建类似配置。复制的模板独立于原模板进行维护。
复制模板后,请在将其用于生产环境前检查环境、部署目标、Workspaces、凭证和关联的 Trigger。
从现有 PipelineRun 保存
当 PipelineRun 已具有经过验证的配置时,可以从 PipelineRun 执行条目中使用 保存运行模板。在 保存模式 中,选择:
- 创建新的运行模板,将当前运行配置保存为新模板。
- 更新现有运行模板,替换已使用此 Pipeline 的模板配置。选择目标模板,然后保存。
这适用于:
- 将成功的执行保存为团队模板。
- 快速创建测试或发布模板。
- 根据已知的执行配置开始创建新模板。
- 在验证运行后更新现有模板。
使用能够描述服务、环境和用途的名称,例如
order-service-dev、order-service-test 或 order-service-prod。
更新现有运行模板可能会影响后续手动执行以及引用该模板的任何 Trigger 或 ScheduledTrigger。保存前请检查这些启动方式。
使用运行模板运行 Pipeline
直接从运行模板运行
您可以从运行模板列表或详情页面启动运行:
- 找到运行模板。
- 选择 运行。
- 提供标记为
Set at Runtime的值。 - 提交 PipelineRun。
运行表单会显示标记为 Set at Runtime 的内容,此外还会显示由 Pipeline 的 Integrations 绑定的参数和 Workspaces,即使运行模板为它们提供了固定值。运行模板中具有固定值的其他参数、Workspaces 和 Integrations 会作为运行输入使用,不会显示为可编辑内容。典型的运行时内容包括:
- 参数,例如 Git 分支、提交、镜像标签或发布批次。
- Workspaces,当此次运行需要使用不同的工作空间时。
- Integrations,当此次运行需要使用不同的仓库、注册表或凭证时。
从常规运行条目重用运行模板
您还可以从常规 Pipeline 运行条目中选择现有运行模板,并将其值应用于当前运行。
此方法适合临时重用配置。若要长期重复使用,请直接从运行模板列表或详情页面运行 Pipeline,以便在一个位置维护运行配置。
在 Pipeline 执行对话框中应用运行模板
- 打开 Pipeline 执行对话框。
- 在 运行模板 中选择运行模板。
- 查看从运行模板导入的值,并填写 Pipeline 执行表单显示的字段。
- 提交 PipelineRun。
在 Pipeline 执行对话框中应用运行模板时,Pipeline 执行表单控制显示哪些字段。运行模板为当前运行提供值;它不会根据其 Set at Runtime 设置筛选 Pipeline 执行表单。
为运行模板配置 Trigger
Trigger 的职责
当外部事件符合其条件时,Trigger 会启动 Pipeline。在运行模板工作流中:
- 运行模板存储可重用的运行配置。
- Trigger 定义可启动运行的外部事件。
- TriggerBinding 定义可供 Trigger 使用的事件变量。
- EventListener 接收外部事件,并将其传递给匹配的 Trigger。
完整的 Trigger 配置操作步骤请参阅 集中式 Trigger 管理 (位于使用 Hub Pipeline 和运行模板的集中式管理中)。
本页重点介绍 Trigger 事件与运行模板事件变量之间的关系:
- 创建 Trigger 时选择的 Event 决定 Trigger 处理哪些事件条件。一个运行模板可以关联多个 Event。
- 在运行模板中设置为
Set at Runtime的参数、Workspaces 和 Integrations,可以在创建 Trigger 时与事件变量关联。
从运行模板创建 Trigger
- 打开运行模板详情页面。
- 打开 Triggers 选项卡并创建 Trigger。当前运行模板已自动选作固定引用。不会显示 Template Type。
- 根据集中式 Trigger 管理指南配置事件和 Trigger 条件。
- 如果运行模板包含运行时内容,并且此 Trigger 需要补全运行时值、注入事件变量或关联新的 Event,请选择 将更新同步到 TriggerTemplate。
- 根据需要,将 TriggerBinding 中的事件变量与 Pipeline 参数关联。
- 保存 Trigger。
当运行模板包含运行时内容时,如果此 Trigger 需要补全必需的运行时值、注入事件变量或将新的 Event 与运行模板关联,请使用
将更新同步到 TriggerTemplate。
该表单仅显示标记为 Set at Runtime 的内容。如果选择此选项,并且 Event 尚未与此运行模板关联,则保存 Trigger 时会先将 Event 及其事件变量声明写回运行模板,然后创建 Trigger。
当引用的运行模板包含运行时参数、Workspaces 或 Integrations 时,同步选项默认处于选中状态。当模板不包含运行时内容时,默认处于未选中状态。对于不包含运行时内容的 ScheduledTrigger,不会显示此选项。
关联事件变量和发送测试事件是可选步骤。当 Trigger 需要特定于事件的值,或需要验证完整的事件到运行流程时,请使用这些步骤。产品不会从此表单发送测试事件。若要执行此验证,请通过已配置的 EventListener 或其他受支持的事件发送方传送事件,然后检查生成的 PipelineRun。
将更新同步到 TriggerTemplate
当 Trigger 或 ScheduledTrigger 引用运行模板时,表单可以包含 将更新同步到 TriggerTemplate。
在以下情况下选择此选项:
- 补全必需的运行时参数、Workspaces 或 Integrations。
- 将 Trigger 中的事件变量注入运行模板的运行时内容。
- 补全 ScheduledTrigger 中的必需参数。
选择此选项后,表单仅显示标记为 Set at Runtime 的运行模板内容。对这些内容的更改会写回运行模板,并影响后续手动运行以及引用该模板的其他 Trigger。
取消选择此选项后:
- 隐藏事件变量、运行时参数、Workspaces 和 Integrations 表单。
- 不会更新运行模板。缺失的 Event、事件变量声明和运行时值不会写回。
- 仍会使用其自身的 Event 和调度配置保存 Trigger 或 ScheduledTrigger。
事件变量源
事件变量由 Trigger 使用的 TriggerBinding 定义。可用变量可能因事件类型、事件源和 TriggerBinding 而异。
配置 Trigger 时,请检查:
- Trigger 使用哪个 TriggerBinding。
- TriggerBinding 提供哪些事件变量。
- 运行模板中的哪些内容应引用事件变量。
- 生成的 PipelineRun 是否包含事件中的值。
事件变量与不同的运行上下文
手动执行、Trigger 执行和 ScheduledTrigger 执行使用同一个运行模板,但它们的运行上下文不同。每个上下文中可用的变量也可能不同:
- Trigger 执行:当当前事件的 TriggerBinding 提供某个变量时,
$(tt.params.<name>)使用该事件中的值。 - 手动执行:没有外部事件提供变量。如果运行值包含
$(tt.params.<name>),手动执行会使用该变量的默认值对其进行渲染。如果未配置默认值,前端会清除整个值。 - 没有值的 Trigger 执行:在当前 Tekton Triggers
v0.36.0实现中,如果 TriggerTemplate 声明了某个参数但未设置默认值,且 TriggerBinding 未提供该参数,PipelineRun 可能会保留字面值$(tt.params.<name>)。这与手动执行运行模板不同,后者会由前端清除整个值。 - ScheduledTrigger 执行:ScheduledTrigger 通过其计划模板参数提供值。请为计划运行所需的每个引用的事件变量配置值或默认值。
因此,同一个运行模板可能会根据启动方式的不同生成不同的运行值。不要假设每个 Trigger、ScheduledTrigger 和手动执行都会提供相同的事件变量。
配置事件变量的默认值
为了使运行模板可通过多种启动方式重复使用,请为其运行内容引用的事件变量配置默认值。当当前运行上下文未提供变量时,会使用默认值。如果事件提供了同名变量的值,则使用事件值。
例如,如果运行模板使用以下值:
将 project-id 事件变量的默认值设置为 frontend-project。然后:
- 事件提供
project-id的 Trigger 使用事件中的值。 - 手动执行会将该值渲染为
frontend-project。 - 未提供
project-id的另一个 Trigger 使用frontend-project,而不是保留未解析的变量表达式。 - ScheduledTrigger 执行使用
frontend-project。
配置默认值:
- 打开运行模板更新入口。
- 在 Event 部分,选择一个或多个提供该变量的 Event(TriggerBindings)。
- 在 Event variables 中找到变量,例如
project-id。 - 在 Default value 中输入默认值,例如
frontend-project。 - 保存运行模板。
一个运行模板可以关联多个 Event。具有相同名称的事件变量会合并为一个变量。重复的名称不会阻止保存。
保存的默认值属于共享的运行模板配置,会影响后续的手动执行、Trigger 执行和 ScheduledTrigger 执行。Event variables 中的 In use 标记表示该变量被当前运行模板运行内容引用。运行模板会维护关联事件变量的默认值和使用关系;变量名称及可用值由关联的 TriggerBinding 决定,映射关系则在 Trigger 中维护。
更新运行模板可能会影响其手动执行、关联的 Trigger 以及关联的 ScheduledTrigger。在保存共享配置更改之前,请检查这些启动方式。
配置 ScheduledTrigger
ScheduledTrigger 根据时间规则启动运行模板。它可用于夜间构建、定期扫描、回归测试或定时发布。
- 打开运行模板详情页。
- 打开 ScheduledTriggers 选项卡并创建 ScheduledTrigger。当前运行模板已作为固定引用选中。
- 设置计划和时区。
- 如果 ScheduledTrigger 需要补全必需的运行时值,请选择 Synchronize updates to TriggerTemplate。请参阅 同步对 TriggerTemplate 的更新。
- 检查运行模板及其运行时内容。
- 保存 ScheduledTrigger。
ScheduledTrigger 运行时,会使用固定的运行模板内容作为运行输入。需要更改的值可以配置为 ScheduledTrigger 参数。这些参数为运行模板中对应的
$(tt.params.<name>) 事件变量提供值;它们不是针对每个 Pipeline 参数的任意覆盖值。ScheduledTrigger 提供的值优先用于匹配的事件变量。如果未提供该变量,则使用运行模板事件变量的默认值。
Pipeline 变更与运行模板
运行模板执行表单遵循其 Pipeline 的最新定义。更改 Pipeline 后,请检查使用该 Pipeline 的每个运行模板。
添加 Pipeline 参数
当 Pipeline 添加参数时,执行运行模板时默认会显示该参数。模板尚未为新参数设置 Set at Runtime,因此执行表单会将其视为可见的运行时内容。
如果需要固定的默认值,或需要为该参数设置 Set at Runtime,请更新并保存运行模板。未标记为 Set at Runtime 的值会作为固定运行输入存储。后续执行时,运行表单不会询问其中的大多数值;由 Pipeline 的 Integrations 绑定的参数和 Workspaces 仍会显示并可编辑。新的 Pipeline 参数会一直显示,直到再次保存模板。
重命名、移除或更改参数
如果 Pipeline 参数被重命名、移除或更改类型,现有运行模板配置可能不再适用。请检查:
- 参数名称是否仍然匹配。
- 值是否仍符合新的定义。
- TriggerBinding 事件变量是否仍映射到正确的 Pipeline 参数。
添加或更改 Workspace
如果 Pipeline 添加 Workspace,或更改了 Workspace 的提供方式,请更新运行模板,并检查目标环境的 Workspace 绑定。
更改其他运行要求
如果 Pipeline 更改了 Integration 要求、任务级运行要求或其他执行设置,请检查相应的运行模板内容,并验证直接执行、Trigger 执行和 ScheduledTrigger 执行。
更改 Hub Pipeline 版本
当运行模板使用 Hub Pipeline 时,请先检查新的 Hub Pipeline 版本,然后更新现有运行模板。在运行模板更新对话框中,表单视图中的 Pipeline 选择器为只读。若要在不创建另一个运行模板的情况下更改关联的 Hub Pipeline 版本,请切换到 YAML 模式,更新运行模板的 PipelineRun 资源中的 Pipeline 引用,然后从 YAML 视图保存。接着重新打开更新对话框,并在表单视图中检查生成的参数、Workspaces、Integrations 和运行时设置。在 YAML 中更改 Pipeline 引用后,如果在保存前切回表单视图,模板的固定值会被清除。
对于 Hub Pipeline 引用,请保留现有的 catalog、kind 和 Pipeline 名称,并将 version 值更改为已检查的版本:
除非新的 Hub Pipeline 要求进行相应的配置更改,否则请保持其他运行模板设置不变。
直接验证更新后的运行模板,然后验证每个关联的 Trigger 和 ScheduledTrigger。在新版本通过这些检查之前,请保留之前的 Hub Pipeline 版本,以便在需要回滚时将现有运行模板改回原版本。
管理运行模板
更新
您可以在表单视图中更新参数、Workspaces、Integrations、事件变量默认值和其他运行设置。若要更改关联的 Pipeline 引用,请按照更改 Hub Pipeline 版本中所述使用 YAML 模式。之后的手动运行和 Trigger 将使用更新后的配置。
删除
不再使用运行模板时,请将其删除。删除前,请检查其关联的 Trigger、ScheduledTrigger 和执行历史记录。
最佳实践
- 为开发、测试和生产环境分别创建模板,而不是通过编辑一个共享模板来切换环境。
- 将未设置为
Set at Runtime的固定值保留在模板中,这样用户就不必在运行时提供这些值。由 Pipeline 的 Integrations 绑定的参数和 Workspaces 仍会显示在运行表单中。 - 对于需要长期重复使用的场景,请直接从运行模板列表或详情页运行。
- 在模板名称中包含服务、环境和用途。
- 为多个 Trigger 或启动方式共同使用的事件变量配置默认值。
- 更改事件变量映射后,通过已配置的 EventListener 或其他受支持的事件发送方发送事件,并验证生成的 PipelineRun。
- 使用适当的权限和变更审核保护生产环境中的运行模板和 Trigger。
常见问题
直接运行需要提供哪些值?
请提供设置为 Set at Runtime 的参数、Workspaces 和 Integrations。运行模板中已存储的固定值会作为运行输入。由 Pipeline 的 Integrations 绑定的参数和 Workspaces 也会显示在运行表单中,并预先填入其固定值且可编辑,因此请在提交前检查这些值。若要为每次运行更改固定值,请先更新运行模板。
为什么事件变量没有传递到 Pipeline?
请检查 Trigger 的 TriggerBinding、事件变量映射以及由 Trigger 创建的 PipelineRun。确认事件确实提供了该变量。
为什么运行表单中出现了新的 Pipeline 参数?
运行模板尚未为该参数设置 Set at Runtime。在您更新并保存运行模板之前,新的 Pipeline 参数会一直显示。
同步对 TriggerTemplate 的更新有什么作用?
它控制 Trigger 或 ScheduledTrigger 是否可以更改所引用运行模板的运行时内容。请参阅同步对 TriggerTemplate 的更新。
Pipeline 更改是否需要更新运行模板?
执行运行模板时,新的 Pipeline 参数默认会显示。如果新参数需要固定的默认值或 Set at Runtime,请更新并保存运行模板。同时请检查参数、Workspace、Integration 和事件变量的更改。
删除运行模板会删除历史运行吗?
不会。删除运行模板只会移除其配置。现有 PipelineRun 仍会根据平台的执行历史记录策略保留。