使用 Hub Pipeline 和 Run Template 进行集中管理
目录
概述使用场景核心概念管理职责集中维护 Hub Pipeline按项目和环境维护 Run Template管理启动条件管理工作流前置条件建立集中式管理集中式 Trigger 管理Trigger、TriggerBinding、EventListener 和 Run Template事件变量管理跨多个启动方法的事件变量Trigger 权限和变更管理Pipeline 变更和 Run Template添加 Pipeline 参数重命名、移除或更改参数添加或更改 Workspace更改其他运行要求升级 Hub Pipeline运行配置管理稳定配置运行时配置最佳实践中央平台团队项目团队变更审查人员常见问题一个 Hub Pipeline 必须对应一个 Run Template 吗?每个团队都应该共享一个 Run Template 吗?当一个 Run Template 有多个启动方法时,应如何处理事件变量?何时应使用集中式管理?推荐设置相关主题概述
Hub Pipeline 和 Run Template 提供了一种标准化 Pipeline 流程的方式, 同时保留每个项目和环境所需的运行设置。
在本指南中,Hub Pipeline 指通过 Tekton
hub resolver 或产品目录获取的 Pipeline。在当前版本中,目录资源
由独立的 ArtifactHub Shim 组件提供;旧版内置的
Tekton Hub runtime 不再随产品提供。有关 resolver 行为,请参阅
Hub Resolver 和
ArtifactHub Shim Catalog。
- 中央平台或 DevOps 团队维护共享的、带版本的 Hub Pipeline。
- 项目团队使用 Run Template 维护服务、项目或环境的配置。
- 当事件或计划要求启动时,Trigger 和 ScheduledTrigger 会启动相应的 Run Template。
这将Pipeline 的工作方式与项目运行 Pipeline 的方式以及 Pipeline 的启动时机分离开来。它可以减少重复的 Pipeline 定义、配置偏差, 以及使用错误环境的风险。
使用场景
在以下情况下,集中管理非常有用:
- 多个项目需要相同的构建、测试、扫描或发布流程。
- 平台团队需要标准化安全检查和工件处理。
- 一个标准流程必须服务于开发、测试和生产环境。
- 相同的运行配置必须支持手动、事件驱动和计划启动。
- 新的 Hub Pipeline 版本需要经过受控的影响评审和推出。
核心概念
可以将这些功能理解为:
- Hub Pipeline:标准流程是什么。
- Run Template:项目如何使用该流程。
- TriggerBinding:哪些事件变量可用。
- Trigger:哪些外部事件可以启动该流程。
- ScheduledTrigger:该流程何时按计划启动。
- PipelineRun:一次执行的结果。
管理职责
集中维护 Hub Pipeline
中央团队负责:
- 设计组织的标准 Pipeline 步骤。
- 定义代码检查、安全扫描、制品创建和发布要求。
- 维护清晰的 Pipeline 名称、描述和版本。
- 发布 release notes,说明新功能、行为变更和升级注意事项。
- 验证新版本可在组织支持的环境中运行。
Hub Pipeline 应描述可复用的流程。项目特定的环境名称、部署目标和临时值应保留在 Run Template 中,而不是硬编码到共享 Pipeline 中。
按项目和环境维护 Run Template
项目团队选择适当的 Hub Pipeline 版本,并为以下内容创建 Run Template:
- 项目和服务标识。
- 代码源。
- 开发、测试和生产设置。
- 镜像仓库和镜像标签策略。
- 部署目标。
- Workspaces 和 Integrations。
- 由用户或事件在运行时提供的值。
Run Template 中具有固定值且未设置为 Set at Runtime 的内容会用作运行输入。运行表单不会询问其中的大多数内容;Pipeline Integration 绑定的 Parameters 和 Workspaces 仍会显示并可编辑。一个 Hub Pipeline 可以有多个 Run Template,每个模板代表一种明确的使用场景。
管理启动条件
启动方式和运行配置是相互独立的关注点:
- 当外部事件应启动一次运行时,使用 Trigger。
- 当运行应按计划启动时,使用 ScheduledTrigger。
- 对于手动发布、验证或其他由用户发起的执行,直接运行 Run Template。
事件变量由 TriggerBinding 定义。事件启动 Run Template 时,Trigger 会将这些变量与 Pipeline 运行值关联起来。
管理工作流
前置条件
建立集中式管理之前,请确认:
- 中央平台团队已发布可复用的 Hub Pipeline。
- Hub Pipeline 具有明确的用途、版本和变更说明。
- 项目团队可以访问 Hub Pipeline 和 Run Template。
- 所需的 Workspaces、Integrations 和运行权限均可用。
- 使用 Trigger 时,EventListener 可用。
- 已定义开发、测试和生产环境的权限边界。
建立集中式管理
1. 发布标准 Hub Pipeline
中央团队在 Hub 中发布可复用的 Pipeline,例如
build-and-deploy。
标准流程可以包括:
- 获取源代码。
- 编译和单元测试。
- 依赖项或安全检查。
- 构建并发布制品。
- 部署到目标环境。
- 报告执行结果,以供审计和评审。
Hub Pipeline 将流程标准化;它不会取代项目和环境配置。
2. 选择 Pipeline 版本
在 Hub 中打开 Pipeline 并确认:
- 其用途是否与项目匹配。
- 要使用的版本。
- 所需参数。
- 所需的 Workspaces。
- 所需的 Integrations。
- 版本说明和升级影响。
确认版本后,为该版本创建或更新 Run Template。
3. 创建 Run Template
打开 Run Template,点击 Create,选择目标 Pipeline,然后配置项目和环境运行设置。
也可以使用 Save Run Template 保存已验证的 PipelineRun,并选择 Create a new Run Template 或 Update an existing Run Template。要从现有模板开始,请复制该模板:
- 找到现有模板。
- 点击 Copy。
- 为新模板输入名称。
- 检查环境、部署目标、Workspaces、Integrations 和运行时内容。
- 保存新模板。
例如,可以使用单独的模板表示以下环境:
Run Template 中固定且未设置为 Set at Runtime 的值会作为运行输入。运行表单不会要求输入其中的大多数值;Pipeline Integration 绑定的 Parameters 和 Workspaces 仍会显示并可编辑。只有设置为 Set at Runtime 的内容才需要作为运行时内容提供。
4. 配置启动方式
配置与每种使用场景相匹配的启动方式:
对于 Trigger:
- 准备并验证目标 Run Template。
- 创建使用该 Run Template 的 Trigger。在 Run Template 详细信息页面中,当前模板已作为固定引用预先选定。
- 选择事件和触发条件。
- 如果此 Trigger 需要补全所需的运行时值或注入事件变量,请选择 Synchronize updates to TriggerTemplate。请参阅 Synchronize updates to TriggerTemplate。
- 根据 TriggerBinding 定义,将事件变量与 Pipeline 运行值关联起来。
- 保存 Trigger。如果已选择 Synchronize updates to TriggerTemplate,且 Event 尚未与 Run Template 关联,则会在创建 Trigger 之前将 Event 写回 Run Template。
- 如果验证需要测试事件,请通过已配置的 EventListener 或其他受支持的事件发送方发送该事件,并确认生成的 PipelineRun 中的值。Trigger 表单不会自行发送事件。
当引用的 Run Template 包含运行时 Parameters、Workspaces 或 Integrations 时,同步选项默认处于选中状态。当模板没有运行时内容时,该选项默认处于未选中状态。对于没有运行时内容的 ScheduledTrigger,不会显示此选项。
5. 验证并交付
在提供新的 Run Template 之前,请验证:
- 从 Run Template 直接执行一次。
- 使用 Trigger 时,执行一次事件驱动的运行。
- 使用 ScheduledTrigger 时,执行一次计划运行。
- 验证生成的参数、Workspaces、制品和部署目标。
验证完成后,将生产 Run Template 和 Trigger 交给具有适当权限的用户。
集中式 Trigger 管理
Trigger、TriggerBinding、EventListener 和 Run Template
明确各项职责:
- Run Template 存储项目或环境的完整运行配置。
- TriggerBinding 定义事件流中可用的事件变量。
- Trigger 定义哪些外部事件可以启动 Pipeline,以及如何将事件变量传递给 Run Template。
- EventListener 接收来自代码仓库或其他系统的事件,并将其传递给匹配的 Trigger。
Trigger 不应成为运行配置的另一份副本。将其与 Run Template 关联,可以使手动执行和事件驱动执行在 Workspaces、凭证、部署目标和其他运行值方面保持一致。
事件变量管理
事件变量由 Trigger 使用的 TriggerBinding 定义。不同事件类型和事件源可用的变量可能不同。
一个 Run Template 可以与多个 Event 关联。名称相同的事件变量会合并为一个变量。重复的名称不会阻止保存。
中央平台团队可以为常见事件定义共享的 TriggerBinding 约定。项目团队随后可在 Trigger 中映射变量时使用这些约定。对于以下值,请保持名称和含义一致:
- 项目名称或项目路径。
- Git 分支。
- Commit SHA。
- Commit message。
- Image tag,或用于创建 image tag 的值。
配置映射后,可以选择通过已配置的 EventListener 或其他受支持的事件发送方发送事件,并检查生成的 PipelineRun,以确认事件值已传递到预期的 Pipeline 运行值。Trigger 表单不提供内置的测试事件操作。
跨多个启动方法的事件变量
手动执行、Trigger 执行和 ScheduledTrigger 执行使用同一个 Run Template,但其运行上下文和可用的事件变量可能不同:
- 手动执行没有外部事件。引用的事件变量会使用其默认值;如果没有默认值,则包含该变量的整个值会被清除。
- 如果 TriggerBinding 提供了变量,Trigger 会使用当前事件提供的值。
- ScheduledTrigger 可以为对应的
$(tt.params.<name>)事件变量提供值。这是计划模板值,而不是对每个 Pipeline 参数进行任意覆盖的值。 - 在当前 Tekton Triggers
v0.36.0实现中,如果 TriggerTemplate 声明了一个没有默认值的参数,且 TriggerBinding 未提供该参数,则生成的 PipelineRun 可能会保留字面量$(tt.params.<name>)值。手动执行 Run Template 采用不同的前端路径;当其默认值为空或缺失时,会清除整个值。 - ScheduledTrigger 通过其计划模板参数提供值。对于计划运行所需的每个引用事件变量,请配置一个值或默认值。
- Trigger 或 ScheduledTrigger 提供的值优先用于对应的事件变量。当当前运行上下文未提供该值时,Run Template 默认值会提供稳定的回退值。
当一个 Run Template 被多个 Trigger、ScheduledTrigger 和手动执行重复使用时,请将事件变量默认值作为模板配置的一部分进行检查。有关详细行为和配置步骤,请参阅 Run Template 指南中的事件变量和不同的运行上下文。
Trigger 权限和变更管理
Trigger 可以启动构建、扫描或部署。请考虑以下事项:
- 限制可以创建、更新或删除生产 Trigger 的人员。
- 审查生产事件源和触发条件。
- 更新 Run Template 之前,审查使用该模板的所有 Trigger。
- 更改 TriggerBinding 或事件变量映射后,验证生成的运行值。
- 为开发、测试和生产环境使用不同的 Trigger,以防止事件启动错误的环境。
- 删除 Trigger 之前,确认其 EventListener 和外部事件源已不再使用该 Trigger。
更新被多个 Trigger 使用的 Run Template,可能会同时影响手动执行、事件驱动执行和计划执行。当共享变更的影响不可接受时,请使用单独的生产模板。
Pipeline 变更和 Run Template
Run Template 遵循其关联 Pipeline 的最新定义。当 Pipeline 发生变更时,请审查使用该 Pipeline 的所有 Run Template。
添加 Pipeline 参数
当 Pipeline 添加参数时,执行 Run Template 时默认会显示该参数。该模板尚未为新参数设置 Set at Runtime,因此执行表单会将其视为可见的运行时内容。
如果参数需要固定的默认值或需要 Set at Runtime,请更新并保存 Run Template。未标记为 Set at Runtime 的值会存储为固定运行输入。在后续执行中,运行表单不会询问其中的大多数值;Pipeline Integration 绑定的参数和 Workspace 仍会显示并可编辑。新的 Pipeline 参数会一直显示,直到再次保存模板。
重命名、移除或更改参数
如果 Pipeline 参数被重命名、移除或更改类型,请审查参数名称、值以及任何以该参数为目标的 TriggerBinding 事件变量映射。
添加或更改 Workspace
如果 Pipeline 添加了 Workspace 或更改了其使用要求,请更新 Run Template,并在目标环境中验证 Workspace 绑定。
更改其他运行要求
如果 Pipeline 更改了其 Integration 要求、任务级运行要求或部署行为,请重新验证直接执行 Run Template、Triggers 和 ScheduledTriggers。
升级 Hub Pipeline
发布新的 Hub Pipeline 版本后,请以现有 Run Template 为基础进行升级。不要仅因为 Hub Pipeline 版本发生变化就创建新的 Run Template。
- 中央团队发布新版本并说明变更内容。
- 项目团队确定使用先前版本的现有 Run Template。
- 审查新版本的参数、Workspace、Integration、运行要求、事件变量映射和部署行为。
- 打开每个现有 Run Template 的更新入口。在表单视图中,更新期间关联的 Pipeline 选择器为只读。切换到 YAML 模式,将 Run Template 的
PipelineRun资源中的 Pipeline 引用更新为新的 Hub Pipeline 版本,然后从 YAML 视图保存。在 YAML 中更改 Pipeline 引用后,如果在保存前切回表单视图,模板的固定值会被清除。如果命名空间强制执行name@versionallowlist,例如使用 Kyverno 限制 Tekton Pipeline 执行中的allow-approved-pipeline-versions规则,请先将新的键值对添加到列表中:引用未列出键值对的运行会被拒绝。在仍可能回滚期间,请保留先前的键值对。 - 重新打开更新入口,并在表单视图中检查新增或变更的参数。必要时,在现有 Run Template 中配置固定默认值或
Set at Runtime。 - 检查 Workspace、Integration、部署目标和其他运行设置。
- 在开发或测试环境中直接运行更新后的 Run Template,并验证参数、Workspace、构件和部署结果。
- 验证 Run Template 关联的 Triggers 和 ScheduledTriggers,包括事件变量场景。
- 开发和测试验证成功后,以相同方式更新对应的生产 Run Template,并验证生产环境的启动方法。
- 保留先前的 Hub Pipeline 版本以制定回滚计划。如果需要回滚,请将现有 Run Template 的 Pipeline 引用改回该版本;无需单独创建旧的 Run Template。
运行配置管理
稳定配置
稳定配置示例包括:
- 环境名称。
- 部署目标。
- 默认镜像仓库。
- 默认 Workspace。
- 稳定的 Integration。
当这些值在 Run Template 中填写且未设置为 Set at Runtime 时,它们会作为运行输入使用,并且运行表单不会要求用户填写其中大多数值(请参阅下方“运行时配置”中的 Integration 例外情况)。
运行时配置
可能设置为 Set at Runtime 的内容示例包括:
- Git 分支。
- Commit SHA。
- 镜像标签。
- 发布批次。
- 临时验证标志。
直接从 Run Template 运行时,用户需要提供这些运行时内容。 固定值已存储在 Run Template 中,其中大多数不会显示为可编辑项。例外情况是 Pipeline Integration 绑定的参数和 Workspace:即使 Run Template 为它们提供了固定值,控制台运行表单仍会将其显示为可编辑项。需要更改固定值时,请先更新 Run Template。
最佳实践
中央平台团队
- 使用清晰且稳定的 Hub Pipeline 名称。
- 为每个版本发布 release notes。
- 说明会影响参数或部署的兼容性和行为变更。
- 在发布前验证关键任务、构件和部署步骤。
- 说明哪些版本适用于开发、测试和生产环境。
- 为常见事件维护一致的 TriggerBinding 约定。
项目团队
- 在 Run Template 名称中包含服务和环境。
- 每个模板只保留一个主要使用场景。
- 对于长期重复使用的场景,直接从 Run Template 列表或详情页运行。
- 当一个模板由多个启动方法复用时,检查事件变量默认值。
- 在更改生产环境前,检查关联的 Triggers、ScheduledTriggers 和近期运行记录。
- 在更改生产 Run Template 前,先在开发或测试环境中验证复制或更新后的模板。
变更审查人员
- 审查生产部署目标、凭证、分支和镜像标签。
- 确认事件驱动的执行不会绕过必要的发布审批。
- 确认 Hub Pipeline 升级已针对每个受影响的 Run Template 和启动方法完成验证。
- 保留足够的变更历史,以便将一次运行追溯到其 Run Template 和 Pipeline 版本。
常见问题
一个 Hub Pipeline 必须对应一个 Run Template 吗?
不必。一个 Hub Pipeline 可以有多个 Run Template,通常按项目、服务或环境区分。
每个团队都应该共享一个 Run Template 吗?
可以共享,但生产场景通常更适合使用独立的模板。共享 Hub Pipeline,并在需要限制配置变更影响范围时创建独立的 Run Template。
当一个 Run Template 有多个启动方法时,应如何处理事件变量?
手动执行、Triggers 和 ScheduledTriggers 使用同一个 Run Template,但可能提供不同的事件变量。为引用的事件变量配置默认值,以提供稳定的回退值。一个 Run Template 也可以与多个 Event 关联;名称相同的变量会被合并。请参阅 Run Template 事件变量指南。
何时应使用集中式管理?
一次性实验、临时调试和短期独立流程可以使用项目 Pipeline 和一次性运行配置。当一个流程需要跨项目、环境或启动方法重复使用时,请使用 Hub Pipeline 和 Run Template。
推荐设置
启用时机。当多个项目需要相同的构建、测试、扫描或发布流程时,请将 Hub Pipeline 与 Run Templates 配合使用。中央平台团队只需维护 Hub Pipeline 及其版本一次,因此安全检查和构件处理无需在每个项目中重复复制和修补;项目团队只需为其服务和环境提供运行值。最佳实践 中的角色特定指南仍然适用。
推荐值。将每个标准流程作为一个带版本的 Hub Pipeline 发布,例如 build-and-deploy,并避免在其中包含项目名称、环境名称、部署目标和临时值。在每个 Run Template 中,通过 hub resolver 引用 Hub Pipeline,并将 version 参数显式设置为经过审查的版本;将稳定值存储为固定输入,仅将 Git 分支、提交 SHA 和镜像标签等每次运行的值标记为 Set at Runtime。在控制台运行表单中,即使 Run Template 为 Pipeline Integration 绑定的参数和 Workspaces 提供了固定值,这些参数和 Workspaces(例如 Git URL、目标镜像和凭证 Workspaces)仍会显示并且可以编辑。保存模板后检查运行表单,并审查所提交的 PipelineRun 的参数。每个服务和环境保留一个 Run Template,例如 order-service-dev、order-service-test 和 order-service-prod。按照 升级 Hub Pipeline 和 更改 Hub Pipeline 版本 中的说明,通过更改现有 Run Templates 中的 version 值来推出新的 Hub Pipeline 版本,先在开发和测试环境中执行,最后在生产环境中执行,并保留之前的版本以便回滚。只有在该版本下发布的内容自审查后未发生变化时,将 version 改回原值才能恢复之前的行为。已发布的 catalog 版本是否可以更改,取决于 catalog 的维护方式(请参阅 引用共享 Pipeline 模板),因此请与 catalog 管理员确认,或保留经过审查的内容副本,并在回滚前进行比较。
前提条件。Hub Pipeline 必须发布到产品 catalog,该 catalog 由 ArtifactHub Shim 组件提供服务,以便 Run Templates 通过 hub resolver 对其进行解析。项目团队需要有权访问 Hub Pipeline 和 Run Template,以及所需的 Workspaces、Integrations 和运行权限;Triggers 还需要 EventListener。完整检查清单请参阅 前提条件。