ScheduledTrigger

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

术语说明

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

为什么需要 ScheduledTrigger

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

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

ScheduledTrigger 的帮助方式

ScheduledTrigger 将调度和流水线执行保留在同一系统中:

  1. 单一定义 – 在一个 manifest 中声明执行频率、时区和模板。
  2. 事件一致性 – TriggerTemplate 的运行方式与由 EventListener 调用时完全相同,因此下游工具、RBAC 和可观测性表现一致。
  3. 上下文感知 – 每次运行都会接收结构化时间戳,从而支持确定性的命名、报告或数据分区。
  4. 内置补偿执行 – 如果控制器重启,它可以在合理的限制内重放错过的触发时间点,从而减少手动干预。

优势

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

适用场景

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

约束和限制

  • ScheduledTrigger 接受 robfig/cron 支持的 cron 表达式(标准五字段格式)。
  • TriggerTemplate 仅支持字符串参数;传递复杂数据前,请先将其转换为字符串。
  • 为防止积压执行集中爆发给集群带来压力,错过的触发次数会被有意限制。
  • 时区名称必须与控制器容器内可用的 TZ 数据库中的条目匹配。
  • ScheduledTrigger 专注于执行 TriggerTemplate。对于不包含 Tekton 上下文的通用 Pod,Kubernetes CronJobs 可能仍是更合适的选择。

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 应共享相同行为时,请使用引用;对于自包含作业,或希望在单个清单中包含所有配置时,请使用内嵌规范。

参考资料