ScheduledTrigger

ScheduledTrigger 为 Tekton Triggers 添加类似 cron 的自动化功能。无需等待外部 webhook,您可以让平台按重复计划渲染 TriggerTemplate,并可选择遵循特定时区,将与时间相关的参数注入每次运行。

术语说明

术语描述
ScheduledTrigger一种 Kubernetes 自定义资源,用于定义 TriggerTemplate 按计划运行的时间和方式。
TriggerTemplate用于创建 PipelineRuns、TaskRuns 或其他资源的 Tekton 模板。
Schedule描述所需执行频率(分钟、小时、日期、月份、星期几)的 cron 表达式。
TimeZone可选的 Olson 时区字符串(例如 Asia/Shanghai),用于调整 cron 表达式的计算方式。
上下文参数内置占位符($(context.date) 和 $(context.datetime)),在 TriggerTemplate 运行前解析为计划触发时间。

为什么需要 ScheduledTrigger

基于时间的自动化面临的挑战

  • 团队通常需要将 Tekton 与临时 CronJob、shell 脚本或外部调度器配合使用,才能触发定期流水线。
  • 运维任务(每晚扫描、每周清理、月末报告)需要一致的时间安排和可见性。
  • 相互重叠的 cron 作业和手动脚本会增加维护成本,并使审计变得困难。

ScheduledTrigger 如何提供帮助

ScheduledTrigger 将调度和流水线执行置于同一个系统中:

  1. 单一定义 – 在一个清单中声明执行频率、时区和模板。
  2. 相同的模板格式 – ScheduledTrigger 渲染 Tekton Triggers TriggerTemplate,并使用相同的 $(tt.params.<name>) 替换机制。ScheduledTrigger 控制器会创建这些资源,并为其添加标签 tekton.alaudadevops.io/scheduled-trigger-name 和 tekton.alaudadevops.io/scheduled-trigger-id,而不是 EventListener 添加的 triggers.tekton.dev/* 标签。
  3. 上下文感知 – 运行会通过使用 $(context.date) 或 $(context.datetime) 的参数接收计划时间,从而支持确定性命名、报告或数据分区。
  4. 内置追赶机制 – 如果控制器重启,它可以为最近一次错过的触发时刻创建一次运行,从而减少手动干预。更早错过的触发时刻不会被重放。

优势

  • 使用 Kubernetes 原生 CRD 进行声明式调度。
  • 时区控制确保每晚作业在世界任何地方都与业务时间一致。
  • 通过上下文占位符和用户定义的参数实现一致的参数化。
  • 减少胶水代码,因为无需额外的 CronJob 或 webhook 适配层。
  • 统一的可观测性:事件、状态和日志与其他 Tekton 资源并存。
  • 得益于对错过执行的受控追赶行为,实现更安全的重试。

适用场景

  1. 每晚回归测试或安全扫描,即使没有 Git 活动也必须运行。
  2. 维护工作流,例如缓存清理、资产轮换或数据库导出。
  3. 合规与审计作业,必须按照固定的日历周期触发。
  4. 混合自动化,即使用定期基线运行来补充 webhook 触发的流水线。
  5. 环境同步任务,使 staging 或 demo 环境保持最新。

约束和限制

  • ScheduledTrigger 接受 robfig/cron 支持的 cron 表达式(标准五字段格式)。
  • TriggerTemplate 仅支持字符串参数;传递复杂数据前,请将其转换为字符串。
  • 错过的触发时刻不会逐一重放:控制器最多创建一次追赶运行,针对最近一次错过的触发时刻。对于 47,48 * * * * 等不均匀间隔,此运行可能会被跳过。
  • 时区名称必须是有效的 IANA 时区名称;控制器二进制文件携带自己的 IANA 时区数据库副本。
  • ScheduledTrigger 专注于 TriggerTemplate 执行。对于没有 Tekton 上下文的通用 Pod,Kubernetes CronJob 可能仍然更合适。

ScheduledTrigger 的工作原理

  1. 定义调度 – 提供 cron 表达式和(可选的)时区。控制器根据这些值计算下一次触发时间。
  2. 关联 TriggerTemplate – 引用现有模板,或直接内嵌一个模板。每次触发时,都会使用最新的规范渲染模板,因此更新会自动生效。
  3. 传递参数 – 使用静态值或上下文占位符。$(context.date) 解析为 YYYY-MM-DD,而 $(context.datetime) 解析为计划执行时间的 RFC3339 时间戳。
  4. 控制器执行 – 每次触发时,控制器都会创建 TriggerTemplate 中定义的资源,并在资源状态中记录上次调度时间。
  5. 可观测性 – Kubernetes 事件会报告成功或失败,从而支持使用标准工具(kubectl、仪表板)跟踪计划运行。

配置示例

基本 ScheduledTrigger

apiVersion: tekton.alaudadevops.io/v1alpha1
kind: ScheduledTrigger
metadata:
  name: nightly-security-scan
  namespace: cicd
spec:
  schedule: "0 2 * * *"          # Every day at 02:00
  triggerTemplate:
    ref: security-scan-template
  params:
    - name: scan_date
      value: "$(context.date)"
    - name: environment
      value: "production"

时区感知的调度

apiVersion: tekton.alaudadevops.io/v1alpha1
kind: ScheduledTrigger
metadata:
  name: weekly-cleanup
spec:
  schedule: "30 3 * * 1"         # Mondays at 03:30
  timeZone: "Europe/Paris"
  triggerTemplate:
    ref: cleanup-template

内嵌 TriggerTemplate

apiVersion: tekton.alaudadevops.io/v1alpha1
kind: ScheduledTrigger
metadata:
  name: refresh-demo-data
spec:
  schedule: "0 */6 * * *"        # Every 6 hours
  triggerTemplate:
    spec:
      params:
        - name: target_cluster
          default: "demo"
      resourcetemplates:
        - apiVersion: tekton.dev/v1
          kind: PipelineRun
          metadata:
            generateName: refresh-demo-
          spec:
            pipelineRef:
              name: refresh-pipeline
            params:
              - name: cluster
                value: "$(tt.params.target_cluster)"

重要参数说明

schedule

使用标准 cron 格式 minute hour day-of-month month day-of-week。此字段的值遵循 Cron 语法。

# ┌───────────── minute (0 - 59)
# │ ┌───────────── hour (0 - 23)
# │ │ ┌───────────── day of the month (1 - 31)
# │ │ │ ┌───────────── month (1 - 12)
# │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
# │ │ │ │ │                                   OR sun, mon, tue, wed, thu, fri, sat
# │ │ │ │ │
# │ │ │ │ │
# * * * * *

例如,0 3 * * 1 表示此任务计划于每周一凌晨 3 点运行。

该格式还包含扩展的“Vixie cron”步长值。正如 FreeBSD 手册中所述:

步长值可以与范围结合使用。在范围后添加 /<number>,可指定按该数字的值在范围内跳过。比如,0-23/2 可用于小时字段,以指定每隔一个小时执行一次命令(V7 标准中的替代写法是 0,2,4,6,8,10,12,14,16,18,20,22)。星号后也允许使用步长,因此如果要表示“每两小时一次”,只需使用 */2 即可。

调度中的问号(?)与星号 * 含义相同,即表示给定字段的任意可用值。

除了标准语法外,还可以使用一些宏,例如 @monthly:

条目描述等价于
@yearly(或 @annually)每年 1 月 1 日午夜运行一次0 0 1 1 *
@monthly每月第一天午夜运行一次0 0 1 * *
@weekly每周日早晨午夜运行一次0 0 * * 0
@daily(或 @midnight)每天午夜运行一次0 0 * * *
@hourly每小时开始时运行一次0 * * * *

timeZone

对于未指定时区的 ScheduledTrigger,控制器会根据其本地时区解释调度。

你可以将 .spec.timeZone 设置为有效时区的名称,为 ScheduledTrigger 指定时区。 例如,设置 .spec.timeZone: "Etc/UTC" 后,调度将按照协调世界时进行解释。

二进制文件中包含 Go 标准库提供的时区数据库;如果系统上没有可用的外部数据库,则使用该数据库作为备用。

params

传递给 TriggerTemplate 的键值列表。其行为与 Tekton Trigger 参数完全相同,因此可以通过 $(tt.params.<name>) 在模板中使用每个条目。将静态值与上下文占位符结合使用,可使运行信息自描述。

上下文占位符

你可以在 spec.params 中使用以下上下文占位符:

  • $(context.date) → YYYY-MM-DD
  • $(context.datetime) → RFC3339 时间戳,例如 2006-01-02T15:04:05Z

无论控制器实际何时处理事件,都可以使用它们生成一致的标签、制品名称或日期分区。

triggerTemplate

可以引用可复用的 TriggerTemplate(ref),也可以嵌入完整模板(spec)。当多个 ScheduledTrigger 应共享相同行为时,请使用引用;对于自包含作业,或希望将所有配置放在单个清单中时,请使用内嵌规范。

参考资料