ScheduledTrigger 未按计划触发

问题描述

创建 ScheduledTrigger 后,在预期时间没有出现 PipelineRun(或 TriggerTemplate 中的其他资源)。

根本原因分析

常见原因包括:

  1. cron 表达式或可选的 timeZone 无效,或者下一个触发时间在预期的地域中尚未到达。
  2. 引用的 TriggerTemplate(或内联模板内容)无法解析,通常是因为名称/命名空间错误或缺少权限。
  3. 渲染成功,但由于 RBAC 问题或模板中的验证错误,创建 Tekton 资源失败。

有关 ScheduledTrigger spec 各字段的详细说明,请参阅 ScheduledTrigger API 和重要参数说明。

问题排查

始终从以下命令开始:

# Replace with your ScheduledTrigger name and namespace
kubectl describe scheduledtrigger <name> -n <namespace>
# Events:
#   Type     Reason                  Age               From               Message
#   ----     ------                  ----              ----               -------
#   Warning  UnknownTriggerTemplate  2s (x11 over 7s)  scheduled-trigger  failed to resolve TriggerTemplate: error getting TriggerTemplate missing-trigger-template: TriggerTemplate.triggers.tekton.dev "missing-trigger-template" not found

Events 部分会显示 UnknownTriggerTemplate 或 FailedCreate 等警告。根据这些事件类型,从下面的部分中选择适当的修复方法。

按照以下检查步骤缩小问题范围:

验证计划和时区

  1. 使用 kubectl get scheduledtrigger <name> -n <namespace> -o jsonpath='{.spec.schedule}' 检查计划,并确认它是预期的 cron 表达式(分钟、小时、月份中的日期、月份、星期几)。
  2. 如果已设置 spec.timeZone,请确认它是有效的时区(例如 Asia/Shanghai)。创建或更新 ScheduledTrigger 时,未知时区或无效的 cron 表达式会被拒绝,因此创建或 apply 命令会报告错误;修正值后重新 apply。
  3. 将 kubectl get scheduledtrigger <name> -n <namespace> -o jsonpath='{.status.lastScheduleTime}' 与当前时间进行比较,以确认最近一次运行是否确实已逾期。请记住,cron 表达式会在所选时区中计算,而不是根据查看者的本地时钟计算。如果到目前为止每次运行创建都失败,lastScheduleTime 会保持为空,命令不会输出任何内容;请改用上面的 kubectl describe 事件。
  4. 如果运行时间已到,但 lastScheduleTime 没有变化,并且 kubectl describe 没有显示新事件,请检查 ScheduledTrigger 控制器是否正在运行。这需要对 tekton-pipelines 中的 Pod 具有读取权限,通常需要集群管理员执行:kubectl get pods -n tekton-pipelines -l app=tektoncd-enhancement-controller 必须列出一个处于 Running 状态的 Pod。tekton-pipelines 是 TektonConfig spec.targetNamespace 的默认值;如果你的安装使用其他命名空间,请在命令中替换该值。

确认 TriggerTemplate 引用

  1. 使用 spec.triggerTemplate.ref 时,请确保被引用的 TriggerTemplate 存在于同一命名空间中:kubectl get triggertemplate <ref> -n <namespace>。
  2. 对于内联模板,admission webhook 会在创建或更新 ScheduledTrigger 时检查模板,并拒绝无效模板,因此创建或 apply 命令会报告错误,例如 admission webhook "vscheduledtrigger-v1alpha1.kb.io" denied the request: missing field(s): spec.resourcetemplates。修正模板后重新 apply。
  3. 仅在 spec.params 中使用 $(context.datetime) 等上下文占位符,并通过 $(tt.params.<name>) 在 TriggerTemplate 中引用它们。直接写入 TriggerTemplate 的上下文占位符不会被替换:运行仍会按计划创建,不会记录警告事件,并且字段会保留字面文本 $(context.datetime)。在 script 步骤中,shell 随后会将该文本视为命令替换,因此值为空。如果某次运行显示字面量 $(context.<name>) 值,请将占位符移至 spec.params。

检查 apply 或权限失败的事件

  1. 运行 kubectl describe scheduledtrigger <name> -n <namespace> 并查看 Events 部分。FailedCreate 或 RBAC forbidden 等消息表明控制器尝试触发,但被阻止。
  2. FailedCreate 警告通常意味着 Tekton 拒绝了渲染后的资源。检查消息,调整模板,然后重新 apply ScheduledTrigger。
  3. 若要隔离模板问题,请尝试直接从 TriggerTemplate 内容实例化 PipelineRun、TaskRun 或 CustomRun。手动将每个 $(tt.params.<name>) 占位符替换为具体值,apply 资源,并确认其是否能够成功创建。

其他提示

  • 调试时,可以暂时将 spec.schedule 更改为每分钟运行一次(例如 */1 * * * *),以确认调整后是否开始执行。

  • spec.triggerTemplate.ref 在 ScheduledTrigger 所在的命名空间中指定一个 TriggerTemplate;无法引用其他命名空间中的 TriggerTemplate。当运行时间到达但在该命名空间中找不到模板时,控制器会记录警告事件 UnknownTriggerTemplate,并且不会创建运行。

  • 使用 tekton.alaudadevops.io/scheduled-trigger-name 标签列出由 ScheduledTrigger 创建的所有资源。例如:

    # Replace with your ScheduledTrigger name and namespace
    kubectl get pipelinerun -n <namespace> -l tekton.alaudadevops.io/scheduled-trigger-name=<scheduled-trigger-name>
    # NAME          SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
    # demo-pr-225j6    True        Succeeded   19h         19h
    # demo-pr-22j8w    True        Succeeded   151m        151m
    # demo-pr-22jxp    True        Succeeded   4h39m       4h39m
    
    # Replace with your ScheduledTrigger name and namespace
    kubectl get taskrun -n <namespace> -l tekton.alaudadevops.io/scheduled-trigger-name=<scheduled-trigger-name>
    # NAME          SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
    # demo-tr-hbbk8    True        Succeeded   40d         40d
    # demo-tr-jddk2    True        Succeeded   14d         14d
    # demo-tr-kdq5w    True        Succeeded   14d         14d

    将 <scheduled-trigger-name> 替换为资源名称,以列出该 ScheduledTrigger 仍然存在的 PipelineRuns 或 TaskRuns。Pruner 或用户删除的运行不会列出,因此仅凭空列表无法说明 ScheduledTrigger 未触发。对于生成 CustomRun 的模板,请使用相同的标签运行 kubectl get customrun。对于生成 PipelineRun 的模板,taskrun 和 customrun 查询也会列出该 PipelineRun 的运行,因为 Tekton 会将 PipelineRun 标签复制到这些运行中。若只想列出 ScheduledTrigger 自身创建的运行,请使用 !tekton.dev/pipelineRun 将这些运行排除:

    kubectl get taskrun -n <namespace> -l 'tekton.alaudadevops.io/scheduled-trigger-name=<scheduled-trigger-name>,!tekton.dev/pipelineRun'