Alauda DevOps Pipelines Docs
  • 简体中文

    • 使用 ScheduledTrigger 运行 Pipeline

    TIP

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

    目录

    概述支持的资源类型典型工作流基本清单结构逐步配置1. 选择调度周期和时区2. 指向 TriggerTemplate3. 传递参数4. 应用清单5. 验证资源上下文参数的时区解析在集群范围内设置 controller 默认时区随时间管理 ScheduledTrigger内联模板示例感知时区的每周示例参考链接

    概述

    ScheduledTrigger 允许你在不依赖入站 webhook 的情况下，按类 cron 的节奏执行 TriggerTemplate。每次调度触发时，都会渲染模板、注入任何静态参数或基于时间的参数，并创建你定义的 Tekton 资源（例如 PipelineRuns）。本操作指南将带你完成准备前提条件、编写清单以及端到端验证自动化流程。

    支持的资源类型

    ScheduledTrigger 当前支持 TriggerTemplate 中的以下 Tekton Pipelines 资源：

    建议：对以下资源使用 tekton.dev/v1；tekton.dev/v1beta1 仍然受支持，但已弃用，并将在未来版本中移除。

    Resource TypeDescription
    PipelineRunPipeline run 实例
    TaskRunTask run 实例

    典型工作流

    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>
# Status:
#   Last Schedule Time:  2025-11-25T07:42:00Z
# Events:
#   Type    Reason     Age      From               Message
#   ----    ------     ----     ----               -------
#   Normal  Scheduled  5s       scheduled-trigger  Scheduled security-scan-template for 2025-11-25T07:42:00Z

    检查 LAST SCHEDULETIME 列（或 .status.lastScheduleTime 字段）以确认 controller 正在触发。kubectl describe 显示的 Kubernetes 事件会指示成功运行或调度错误（例如 cron 表达式无效或缺少模板）。

    如果执行仍未按预期开始，请查阅 ScheduledTrigger 故障排查指南 以获取详细的调查步骤。

    上下文参数的时区解析

    $(context.date) 和 $(context.datetime) 占位符会使用调度的有效时区进行渲染。同一个有效时区既用于评估 cron schedule，也用于渲染这些占位符，因此 trigger 的触发时间与注入的时间戳始终保持一致。时区按以下顺序解析：

    1. ScheduledTrigger 上的 spec.timeZone（如果已设置）。这优先于其他所有设置，是控制单个 trigger 的推荐方式。
    2. 当省略 spec.timeZone 时，使用 controller 进程的时区。
    3. UTC，这是 controller 的开箱即用默认值。

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

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

    ScheduledTrigger controller 开箱即用运行在 UTC。如果要为所有未设置自身 spec.timeZone 的 ScheduledTrigger 更改默认值，可以通过 TektonConfig 选项向 controller 注入一个 TZ 环境变量。operator 会以增量方式应用该设置，并且不会在 reconcile 时将其还原：

    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

    应用更改后，operator 会滚动更新 controller。后续运行会使用配置的时区渲染上下文占位符——例如，对于 Asia/Shanghai，$(context.datetime) 会变为 2025-11-25T15:42:00+08:00。

    NOTE
    • 直接编辑 controller Deployment（例如使用 kubectl set env）会在几分钟内被 operator 还原。务必通过 TektonConfig 配置 TZ，以确保更改可持久保存。
    • 单个 trigger 的 spec.timeZone 始终会覆盖此集群级默认值。建议对单个调度优先使用 spec.timeZone，将 controller 的 TZ 保留用于设置组织级默认值。
    • TZ 接受 IANA/Olson 时区名称（例如 UTC、Asia/Shanghai、Asia/Kolkata）。无效名称会使 controller 保持在其先前时区。

    随时间管理 ScheduledTrigger

    • 更新调度周期：编辑资源（kubectl edit 或应用新的清单）以更改 spec.schedule 或 spec.timeZone。下一次触发会自动重新计算。
    • 轮换参数：修改 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

    参考链接