#ScheduledTrigger

ScheduledTrigger 为 Tekton Triggers 添加了类似 cron 的自动化功能。您无需等待外部 webhook，可以让平台按照重复的计划渲染 TriggerTemplate，支持指定时区，并在每次运行时注入与时间相关的参数。

#术语说明

#为什么需要 ScheduledTrigger

#基于时间的自动化挑战

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

#ScheduledTrigger 的优势

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

1. 单一定义 – 在一个清单中声明节奏、时区和模板。
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 * * *"          # 每天凌晨 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"         # 每周一 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 * * *"        # 每 6 小时一次
  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 语法。

# ┌───────────── 分钟 (0 - 59)
# │ ┌───────────── 小时 (0 - 23)
# │ │ ┌───────────── 日 (1 - 31)
# │ │ │ ┌───────────── 月 (1 - 12)
# │ │ │ │ ┌───────────── 星期 (0 - 6) (周日到周六)
# │ │ │ │ │                                   或 sun, mon, tue, wed, thu, fri, sat
# │ │ │ │ │
# │ │ │ │ │
# * * * * *

例如，0 3 * * 1 表示该任务计划在每周一凌晨 3 点运行。

该格式还支持扩展的 “Vixie cron” 步进值。正如 FreeBSD 手册 中解释：

步进值可与范围结合使用。范围后跟 /<数字> 表示在范围内按数字间隔跳过。例如，0-23/2 可用于小时字段，表示每隔一小时执行一次命令（V7 标准的替代写法是 0,2,4,6,8,10,12,14,16,18,20,22）。步进也允许跟在星号后面，因此如果想表示“每两小时”，只需使用 */2。

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

除标准语法外，还支持一些宏命令，如 @monthly：

#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 需要共享相同行为时，使用引用；对于自包含作业或希望所有配置集中在一个清单中的情况，使用内联规范。

#参考资料

• TriggerTemplate Documentation
• CronJob