使用 ScheduledTrigger 运行 Pipeline

TIP

有关 ScheduledTrigger 的架构、动机和设计背景,请参阅 ScheduledTrigger Concepts 页面。

概述

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 的形式存在。

资源类型描述
PipelineRunPipeline 运行实例
TaskRunTask 运行实例
CustomRun自定义任务运行实例,例如 ApprovalTask(请参阅 Manual Approval Gate)

典型工作流

  1. 确认要定期运行的 TriggerTemplate(可复用引用或内联 spec)。
  2. 确定自动化所需的周期、时区和任何上下文参数。
  3. 创建一个将模板绑定到调度的 ScheduledTrigger 清单。
  4. 应用清单并监控资源状态/事件,以确保执行正常发生。

基本清单结构

apiVersion: tekton.alaudadevops.io/v1alpha1
kind: ScheduledTrigger
metadata:
  name: nightly-security-scan
spec:
  schedule: "0 2 * * *"                # Cron expression
  timeZone: "Asia/Shanghai"            # Optional, defaults to controller time
  params:                               # Optional static/context parameters
    - name: scan_date
      value: "$(context.date)"
    - name: severity
      value: "high"
  triggerTemplate:
    ref: security-scan-template         # Reference an existing TriggerTemplate

分步配置

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. 应用清单

# Replace with your namespace and file name which contains the ScheduledTrigger manifest
kubectl -n <namespace> apply -f <scheduled-trigger-file>

将目标命名空间设为 TriggerTemplate 所在的命名空间。Kubernetes RBAC 必须允许 controller 解析并执行该模板。

5. 验证资源

# Replace with your ScheduledTrigger name and namespace
kubectl get scheduledtrigger <scheduled-trigger-name> -n <namespace>
# NAME                    AGE
# nightly-security-scan   10s

# Replace with your ScheduledTrigger name and namespace
kubectl describe scheduledtrigger <scheduled-trigger-name> -n <namespace>
# Right after creation, there is no Last Schedule Time and no event yet.
# After the first run at 02:00 Asia/Shanghai (18:00 UTC), the output includes:
# Status:
#   Last Schedule Time:  2025-11-25T18:00:00Z
# Events:
#   Type    Reason     Age   From               Message
#   ----    ------     ----  ----               -------
#   Normal  Scheduled  5s    scheduled-trigger  Scheduled security-scan-template for 2025-11-25T18:00:00Z

检查 .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 和渲染占位符时使用相同的有效时区,因此触发器的触发时间与其注入的时间戳始终一致。时区按以下顺序解析:

  1. ScheduledTrigger 上的 spec.timeZone(如果已设置)。该设置优先级最高,是控制单个触发器的推荐方式。
  2. controller 的进程时区(如果未设置 spec.timeZone)。
  3. UTC,这是 controller 开箱即用的默认设置。

例如,在未设置 spec.timeZone 且使用 controller 默认时区时,$(context.datetime) 会解析为 UTC 时间戳,例如 2025-11-25T07:42:00Z。

在整个集群范围内设置 controller 默认时区

ScheduledTrigger controller 开箱即用时以 UTC 运行。要更改未设置自身 spec.timeZone 的所有 ScheduledTrigger 的默认时区,请通过 TektonConfig 选项向 controller 注入 TZ 环境变量。operator 会以追加方式应用此设置,并且不会在协调时将其还原:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    options:
      deployments:
        tektoncd-enhancement-controller:
          spec:
            template:
              spec:
                containers:
                  - name: manager
                    env:
                      - name: TZ
                        value: Asia/Shanghai

将示例保存为 tektonconfig-tz.yaml,并将其合并到现有的 TektonConfig 中:

kubectl patch tektonconfig config --type merge --patch-file tektonconfig-tz.yaml

合并补丁会整体替换列表:如果 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。

NOTE
  • 直接编辑 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 时,Go time.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 以停止后续运行。如果需要恢复调度,之后可以使用相同名称重新创建。

内联模板示例

apiVersion: tekton.alaudadevops.io/v1alpha1
kind: ScheduledTrigger
metadata:
  name: refresh-demo-data
spec:
  schedule: "0 */6 * * *"
  params:
    - name: run_timestamp
      value: "$(context.datetime)"
  triggerTemplate:
    spec:
      params:
        - name: target_cluster
          default: "demo"
        - name: run_timestamp
          description: Timestamp passed from ScheduledTrigger
      resourcetemplates:
        - apiVersion: tekton.dev/v1
          kind: PipelineRun
          metadata:
            generateName: refresh-demo-
          spec:
            pipelineRef:
              name: refresh-pipeline
            params:
              - name: cluster
                value: "$(tt.params.target_cluster)"
              - name: timestamp
                value: "$(tt.params.run_timestamp)"

时区感知的每周示例

apiVersion: tekton.alaudadevops.io/v1alpha1
kind: ScheduledTrigger
metadata:
  name: monday-report
spec:
  schedule: "0 9 * * 1"
  timeZone: "America/New_York"
  params:
    - name: report_date
      value: "$(context.date)"
  triggerTemplate:
    ref: weekly-report-template

建议设置

启用时机。当工作必须按照日历运行,而不是响应事件运行时(例如扫描和报告),请使用 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) 占位符,以便识别每次运行:

apiVersion: tekton.alaudadevops.io/v1alpha1
kind: ScheduledTrigger
metadata:
  name: nightly-security-scan
  namespace: <namespace>
spec:
  schedule: "0 2 * * *"
  params:
    - name: scan_date
      value: "$(context.date)"
    - name: severity
      value: "high"
  triggerTemplate:
    ref: security-scan-template

应用后,确认 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 概念。

参考链接