首页/云/Kubernetes 速查/CronJob 时区设置 spec.timeZone

CronJob 时区设置 spec.timeZone

较新版本支持为 CronJob 指定 IANA 时区(如 Asia/Shanghai),不再依赖控制面节点时区,跨时区调度更可控。

Kubernetes 速查云更新于 2026-10-13

时区决定时间表按谁算

CronJob 的 schedule 用 cron 表达式描述时间点,但这个表达式按哪个时区展开取决于 timeZone 字段:设置之后就按指定时区解释(例如 Asia/Shanghai),未设置则按控制面组件的本地时区,常见部署下是 UTC。跨时区团队协作、或与业务时间强相关的任务(比如每天上午九点出报表)必须显式声明时区,否则就会出现「时间对不上」的偏差。

基本信息

适用对象支持该字段的较新版本 CronJob
关键字段spec.timeZone,取值为 IANA 时区名称
未设置时按控制面组件所在的本地时区解释,常见为 UTC
版本约束较老版本遇到该字段会校验失败
验证方式查看 spec 与 status 中的最近调度时间

典型使用场景

  • 业务时刻对齐:报表、结算、推送类任务必须在本地时间某刻执行
  • 跨时区团队:多地协作时统一用业务所在地时区描述调度
  • 迁移集群:从自建迁到云上时保持原有触发时刻不变
  • 排查时间偏差:确认任务实际执行时刻与预期是否一致
  • 多地部署:不同地域集群各自按本地区时区调度

配置示例

配置示例
apiVersion: batch/v1
kind: CronJob
metadata:
  name: report
  namespace: prod
spec:
  schedule: "0 9 * * 1-5"        # 工作日 09:00
  timeZone: "Asia/Shanghai"       # 按上海时间解释上面的表达式
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: Never
          containers:
            - name: report
              image: registry.example.com/report:1.3

验证

验证
kubectl get cronjob report -n prod -o jsonpath='{.spec.timeZone}{"\n"}{.spec.schedule}'
kubectl describe cronjob report -n prod | grep -i -A2 -E 'schedule|last'
kubectl get jobs -n prod | grep report            # 对照 Job 的创建时间
kubectl get cronjob report -n prod -o jsonpath='{.status.lastScheduleTime}'

配置方式与影响

配置解释方式注意
显式设置时区按指定时区展开表达式推荐做法,跨时区协作必备
未设置时区按控制面本地时区集群迁移或重建后可能整体偏移
夏令时地区的时区一年中存在时刻跳变上线前对跳变日实测验证
较老版本集群字段校验失败升级后再使用该字段
不设置时区时行为依赖控制面配置:集群迁移或更换部署形态后,原本准点运行的任务可能整体偏移若干小时,现象很隐蔽。
使用带夏令时的时区时,一年中的某些凌晨时刻会出现跳变,涉及具体时刻的任务要实测验证而不是靠推断。

易错点

  • 不写时区就上线:任务实际按 UTC 执行,业务侧看到的是时间对不上的问题
  • 在较老版本集群直接使用该字段:创建请求被拒绝,报错里提示字段未知
  • 只改时区不看历史运行记录:切换瞬间可能出现漏跑或重复跑
  • 关键任务使用带夏令时的时区:跳变日的实际执行时刻与常规日不同,需要提前验证

数据来源与参考

  • Kubernetes 官方文档 · CronJob(Time zones)
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌