使用 ScheduledTrigger 运行 Pipeline
有关 ScheduledTrigger 的架构、动机和设计背景,请参阅 ScheduledTrigger Concepts 页面。
目录
概述典型使用场景支持的资源类型典型工作流基本清单结构分步配置1. 选择周期和时区2. 指向 TriggerTemplate3. 传递参数4. 应用清单5. 验证资源上下文参数的时区解析在整个集群范围内设置 controller 默认时区随时间管理 ScheduledTrigger内联模板示例时区感知的每周示例建议设置参考链接概述
ScheduledTrigger 允许您按照 cron 风格的周期执行 TriggerTemplate,而无需依赖传入的 webhook。每次调度触发时,系统都会渲染模板,注入静态参数或基于时间的参数,并创建您定义的 Tekton 资源(例如 PipelineRuns)。本操作指南将引导您准备先决条件、编写清单,并端到端地验证自动化流程。
典型使用场景
- 每夜运行的回归测试或安全扫描,即使没有 Git 活动也必须执行。
- 计划报告,例如 Time-Zone-Aware Weekly Example 中的每周报告。
支持的资源类型
ScheduledTrigger 当前支持 TriggerTemplate 中的以下 Tekton Pipelines 资源:
建议:对
PipelineRun和TaskRun使用tekton.dev/v1;tekton.dev/v1beta1仍可用于它们,但已弃用,并将在未来版本中移除。CustomRun仅以tekton.dev/v1beta1的形式存在。
典型工作流
- 确认要定期运行的 TriggerTemplate(可复用引用或内联 spec)。
- 确定自动化所需的周期、时区和任何上下文参数。
- 创建一个将模板绑定到调度的
ScheduledTrigger清单。 - 应用清单并监控资源状态/事件,以确保执行正常发生。
基本清单结构
分步配置
1. 选择周期和时区
- 使用标准 cron 语法(分钟 小时 月中的某天 月 星期中的某天)。例如,
15 1 * * 1-5会在周一至周五的 01:15 运行。 - 将
spec.timeZone设置为 Olson 时区字符串(例如Europe/Paris)。如果省略,controller 将使用其自身的时区进行渲染(默认为 UTC — 请参阅上下文参数的时区解析)。 - 当业务时间与集群默认时区不同时,或需要考虑夏令时变化时,优先使用显式时区。
2. 指向 TriggerTemplate
您可以通过 spec.triggerTemplate.ref 引用可复用模板,也可以在 spec.triggerTemplate.spec 下内嵌完整模板。引用可以让多个 ScheduledTrigger 保持同步,而内联 spec 则使每个清单都自包含。
3. 传递参数
- 使用
spec.params将静态值传递到模板($(tt.params.<name>))。上下文占位符(例如$(context.date)和$(context.datetime))仅在此部分中替换;在其他位置,它们会保留为字面文本。 - 将这些占位符与您自己的参数组合,以生成确定性的运行名称、标签或报告分区,然后在模板中将其引用为
$(tt.params.<name>)。 - 由于 Tekton Trigger 参数是字符串,因此请在传递复杂对象(例如 JSON)之前将其序列化。
4. 应用清单
将目标命名空间设为 TriggerTemplate 所在的命名空间。Kubernetes RBAC 必须允许 controller 解析并执行该模板。
5. 验证资源
检查 .status.lastScheduleTime 字段(由 kubectl describe 显示为 Last Schedule Time),以确认 controller 正在触发。Scheduled 事件消息会指出 spec.triggerTemplate.ref 的 TriggerTemplate;对于内联模板(spec.triggerTemplate.spec),名称为空,因此消息显示为 Scheduled for <time>,其中包含两个空格。Scheduled 事件消息中的时间使用 controller 的时区,而不是 ScheduledTrigger 的 spec.timeZone:默认为 UTC(如示例所示),或使用 在整个集群范围内设置 controller 默认时区 中所述的 controller TZ 变量指定的时区,例如使用 2025-11-26T02:00:00+08:00 和 Asia/Shanghai。kubectl describe 提供的 Kubernetes 事件表示运行成功以及调度错误(例如缺少模板)。事件仅保留有限时间,因此较早运行的 Scheduled 事件可能已经消失;Last Schedule Time 仍会保留。无效的 cron 表达式会在创建或更新 ScheduledTrigger 时被拒绝,因此不会显示为事件。
如果执行仍未按预期启动,请查看 ScheduledTrigger 故障排除指南,了解详细的调查步骤。
上下文参数的时区解析
$(context.date) 和 $(context.datetime) 占位符使用调度的有效时区进行渲染。评估 cron schedule 和渲染占位符时使用相同的有效时区,因此触发器的触发时间与其注入的时间戳始终一致。时区按以下顺序解析:
- ScheduledTrigger 上的
spec.timeZone(如果已设置)。该设置优先级最高,是控制单个触发器的推荐方式。 - controller 的进程时区(如果未设置
spec.timeZone)。 - UTC,这是 controller 开箱即用的默认设置。
例如,在未设置 spec.timeZone 且使用 controller 默认时区时,$(context.datetime) 会解析为 UTC 时间戳,例如 2025-11-25T07:42:00Z。
在整个集群范围内设置 controller 默认时区
ScheduledTrigger controller 开箱即用时以 UTC 运行。要更改未设置自身 spec.timeZone 的所有 ScheduledTrigger 的默认时区,请通过 TektonConfig 选项向 controller 注入 TZ 环境变量。operator 会以追加方式应用此设置,并且不会在协调时将其还原:
将示例保存为 tektonconfig-tz.yaml,并将其合并到现有的 TektonConfig 中:
合并补丁会整体替换列表:如果 TektonConfig 已为此 Deployment 设置了 containers,请将这些条目复制到文件中。不要将仅包含部分 TektonConfig 的文件用于 kubectl apply -f:kubectl apply 会将文件存储在 kubectl.kubernetes.io/last-applied-configuration 注解中,之后对另一个部分文件执行 kubectl apply -f 时,会删除先前文件设置但后续文件未包含的字段,例如此 TZ 设置或触发器导出规则。
更改后,operator 会滚动更新 controller。后续运行会使用配置的时区渲染上下文占位符,例如对于 Asia/Shanghai,$(context.datetime) 会变为 2025-11-25T15:42:00+08:00。
- 直接编辑 controller Deployment(例如使用
kubectl set env)会在几分钟内被 operator 还原。始终通过TektonConfig配置TZ,以确保更改持久生效。 - 单个触发器的
spec.timeZone始终会覆盖此集群范围的默认设置。对于单独的调度,优先使用spec.timeZone;将 controller 的TZ保留用于设置组织范围的默认值。 TZ接受 IANA/Olson 时区名称(例如UTC、Asia/Shanghai、Asia/Kolkata)。如果名称无效,controller 进程会回退到 UTC(当无法加载TZ时,Gotime.Local为 UTC),因此所有未设置spec.timeZone的 ScheduledTrigger 都会在 UTC 中触发并渲染其占位符。
随时间管理 ScheduledTrigger
- 更新调度频率:编辑资源(
kubectl edit或应用新清单)以更改spec.schedule或spec.timeZone。controller 会根据status.lastScheduleTime(如果 ScheduledTrigger 尚未运行,则为创建时间)、新的调度和时区计算下一次运行时间。如果新调度的一个或多个时间点位于上次运行与编辑之间,则它可能会立即为其中最近的时间点创建一次运行;之后将遵循新的调度。例如,某个 ScheduledTrigger 的0 2 * * *上次在 02:00 运行,并在 10:00 更改为0 9 * * *,则会立即针对错过的 09:00 时间点启动一次运行。 - 轮换参数:修改
spec.params,以更新环境名称、功能标志或接收者等静态值。 - 切换模板:将
spec.triggerTemplate.ref指向新模板,或更新内联 spec。后续执行会立即使用新逻辑。 - 暂停或移除:删除 ScheduledTrigger 以停止后续运行。如果需要恢复调度,之后可以使用相同名称重新创建。
内联模板示例
时区感知的每周示例
建议设置
启用时机。当工作必须按照日历运行,而不是响应事件运行时(例如扫描和报告),请使用 ScheduledTrigger。在集群级别设置一次时区,以便每个未设置自身 spec.timeZone 的 ScheduledTrigger 都按照同一时钟触发。
建议值。按照在集群范围内设置 controller 默认时区中的说明,通过 TZ 中的 controller TektonConfig 变量设置一次组织范围的默认时区,并仅在必须遵循不同区域的调度中设置 spec.timeZone。要撤销默认值,请从 TektonConfig 中 manager 容器的 env 列表移除 TZ 条目,例如使用 kubectl edit tektonconfig config,并保留 tektoncd-enhancement-controller 的其他选项;随后 operator 会从 controller 中移除 TZ 并将其回滚。在 TriggerTemplate 所在的 namespace 中为每个作业创建一个 ScheduledTrigger,并为该作业选择调度频率。在 spec.params 中显式传递模板所需的每个值,包括 $(context.date) 或 $(context.datetime) 占位符,以便识别每次运行:
应用后,确认 Last Schedule Time(.status.lastScheduleTime)在每个时间点推进,并确认 Scheduled 事件出现,如分步配置下第 5 步“验证资源”所示。
先决条件。设置 controller TZ 会更改 TektonConfig,并需要集群管理员权限。ScheduledTrigger controller(tektoncd-enhancement-controller)必须正在运行,并且被引用的 TriggerTemplate 必须存在于 ScheduledTrigger 所在的 namespace 中。它运行的 Pipeline 或 Task 必须存在于创建运行的 namespace 中:即 ScheduledTrigger 所在的 namespace,除非资源模板设置了自己的 metadata.namespace。Kubernetes RBAC 必须允许 controller 解析并执行该模板。如果创建运行的 namespace 中的准入策略拒绝不来自 Tekton Pipelines controller 的 TaskRun 创建请求,例如使用 Kyverno 限制 Tekton Pipeline 执行中的 deny-standalone-taskrun 规则,则除非该策略排除 ScheduledTrigger controller 的 ServiceAccount(由 TektonConfig spec.targetNamespace 设置的 namespace 中的 tektoncd-enhancement-controller,默认为 tekton-pipelines),否则创建 TaskRun 的模板会被拒绝。时区名称必须是有效的 IANA 时区名称;controller 二进制文件自带一份 IANA 时区数据库副本。Cron 表达式必须使用标准的五字段格式;请参阅ScheduledTrigger 概念。