# Kubernetes CronJob Time Zones: spec.timeZone, CRON_TZ, and DST

By Dan Ochoa · Published 2026-11-16 · Updated 2026-11-16
Canonical: https://cronradar.com/blog/kubernetes-cronjob-timezone

> Set a Kubernetes CronJob time zone with spec.timeZone: IANA names, the tz database, why CRON_TZ in the schedule is rejected, DST, and matching your monitor.

**Set `.spec.timeZone` on the CronJob to an IANA name such as `America/New_York` or `Etc/UTC`; Kubernetes then reads `.spec.schedule` in that zone.** Without it, kube-controller-manager reads the schedule in its own local time zone, which you may not control or even see. `CRON_TZ=` or `TZ=` inside the schedule string isn't supported and fails validation on new CronJobs.

This guide covers `batch/v1` CronJobs on Kubernetes 1.27 and later, where `timeZone` is stable, checked against the [CronJob documentation](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#time-zones) and the API server's validation source on November 16, 2026.

## The Default: The Controller's Local Zone

The CronJob controller runs inside kube-controller-manager. For a CronJob "with no time zone specified," it "interprets schedules relative to its local time zone." That's the zone of the controller-manager process, set by its container image and environment, not the zone of your laptop, your nodes, or the Pods the CronJob creates.

On a self-managed cluster you can find out; on a managed service the control plane is hidden and the zone is whatever the provider chose. Either way, a CronJob without `timeZone` depends on a setting outside the manifest, and it can change when the control plane is rebuilt. Set the field on every CronJob, even when the answer is UTC:

```yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: morning-digest
spec:
  schedule: '0 7 * * 1-5' # 07:00 on weekdays...
  timeZone: 'America/New_York' # ...in New York, through DST changes
  concurrencyPolicy: Forbid
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: Never
          containers:
            - name: digest
              image: registry.example.com/morning-digest:2.0.1
```

Check what a CronJob has and when it last ran:

```bash
kubectl get cronjob morning-digest -o jsonpath='{.spec.schedule}  {.spec.timeZone}{"\n"}'
kubectl get cronjob morning-digest -o jsonpath='{.status.lastScheduleTime}{"\n"}'
```

`lastScheduleTime` is printed in UTC (`2026-11-16T12:00:00Z` for 07:00 in New York in winter), so convert before deciding the schedule is wrong.

## What timeZone Accepts

The field takes a name from the [IANA time zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones): `Europe/Berlin`, `Asia/Kolkata`, `Etc/UTC`. The API server's validation ([validation.go](https://github.com/kubernetes/kubernetes/blob/master/pkg/apis/batch/validation/validation.go)) checks three things:

- **The shape of the name.** Each `/`-separated part may use only letters, digits, `.`, `-`, `_`, and `+`, up to 14 characters, and may not start with `-` or be `.` or `..`. An empty string is rejected.
- **Not `Local`.** `timeZone: Local` is rejected with "timeZone must be an explicit time zone as defined in https://www.iana.org/time-zones". The field exists to make the zone explicit.
- **That the zone loads.** The API server calls Go's `time.LoadLocation` on the name, so a misspelling like `America/NewYork` fails when you apply the manifest.

Windows zone IDs such as `Eastern Standard Time` fail the name check (spaces aren't allowed), and abbreviations aren't zones: `PST` doesn't load, and `EST` loads only as a fixed UTC−5 offset with no daylight saving time. Use the `Area/City` form. Fixed-offset names like `Etc/GMT+5` exist, but their sign is inverted (`Etc/GMT+5` is UTC−5) and they never observe daylight saving time, so prefer a city.

### Where the Zone Data Comes From

Kubernetes reads zone rules from the time zone database on the system running each component. The docs add: "A time zone database from the Go standard library is included in the binaries and used as a fallback in case an external database is not available on the system." On a host or image without a system database, the embedded copy is used, and it's only as current as the Go release Kubernetes was built with.

That matters when a government changes its rules. A cluster whose embedded database predates the change computes the old offset until the control plane is upgraded. Validation and scheduling also happen in different processes, the API server and the controller manager, which can be on different versions during an upgrade. If the controller can't load a zone the API server accepted, it records an `UnknownTimeZone` warning event (`invalid timeZone: ...`) and doesn't start the Job ([cronjob_controllerv2.go](https://github.com/kubernetes/kubernetes/blob/master/pkg/controller/cronjob/cronjob_controllerv2.go)).

## Why CRON_TZ and TZ in the Schedule Fail

robfig/cron, the Go library Kubernetes parses schedules with, accepts a prefix such as `CRON_TZ=Europe/Berlin 0 2 * * *`, after cronie's `CRON_TZ` variable. Kubernetes never supported it officially, and the docs say so: specifying a time zone with `CRON_TZ` or `TZ` "inside `.spec.schedule` is **not officially supported** (and never has been)," and Kubernetes "will fail to create or update the resource with a validation error" ([unsupported TimeZone specification](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#unsupported-timezone-specification)).

The validation code has two cases:

| Situation                                                  | Result                                                                                                            |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| New CronJob, or an existing one whose schedule had no `TZ` | Rejected: "cannot use TZ or CRON_TZ in schedule, use timeZone field instead"                                      |
| Existing CronJob that already had `TZ` in its schedule     | Updates allowed, but not together with `timeZone`: "cannot use both timeZone field and TZ or CRON_TZ in schedule" |

The check is a substring match for `TZ` anywhere in the schedule. If an old CronJob still carries a `CRON_TZ=` prefix, migrate it in one update: remove the prefix from `schedule` and put the zone in `timeZone`.

### Changing the Zone on a Running CronJob

Adding or changing `timeZone` on an existing CronJob changes when its next runs fall, and the controller's catch-up logic still applies. The controller looks for scheduled times it missed between the last scheduled time and now. If the new zone puts one of those times in the past, for example moving a `0 9 * * *` job from UTC to `Asia/Tokyo` in the afternoon, expect a run to start right away, unless `startingDeadlineSeconds` is short enough to rule it out. Apply the change just after a run, set a starting deadline first, or accept one extra run. Check `lastScheduleTime` and the CronJob's events after applying it.

## The Pod's Clock Is Separate

`timeZone` decides when the Job is created. It doesn't set `TZ` in the container, change the node's clock, or affect what `date` prints inside the Pod. A job scheduled for 07:00 New York time whose code computes "today" in UTC will, in the evening hours, process the wrong date, and logs from the Pod show UTC timestamps if that's the image's default.

If the job needs local time, set it explicitly in the container, and make sure the image has zone data (many slim and distroless images don't):

```yaml
containers:
  - name: digest
    image: registry.example.com/morning-digest:2.0.1
    env:
      - name: TZ
        value: 'America/New_York'
```

Better still, have the job take its reporting window from the scheduled time rather than the clock. Since Kubernetes 1.32, each Job created by a CronJob carries the annotation `batch.kubernetes.io/cronjob-scheduled-timestamp`, the originally scheduled time in RFC 3339 format.

## Daylight Saving Time

With a zone that observes daylight saving time, some local times don't exist once a year and others happen twice. Kubernetes computes run times with robfig/cron, and [cron and daylight saving time](https://cronradar.com/blog/cron-daylight-saving-time) traces its source for both cases:

- **Spring forward.** A schedule inside the skipped hour, such as `30 2 * * *` in New York on March 14, 2027, has no 02:30 that night, and the next run is the following day. That night's run is lost.
- **Fall back.** A schedule inside the repeated hour, such as `30 1 * * *` on November 7, 2027, matches both 01:30s, so the CronJob creates two Jobs an hour apart. `concurrencyPolicy: Forbid` stops the second only if the first is still running.

Times outside 01:00 to 03:00 are unaffected in zones that change at 02:00. The simplest rules: schedule local-time jobs outside the transition window, or schedule in UTC and accept that the local hour shifts twice a year. Check the transition time for each zone you use; not every zone changes at 02:00.

## Keep the Monitor on the Same Clock

A heartbeat monitor computes when each run is due from the same cron expression. If the CronJob reads `0 7 * * 1-5` in New York and the monitor reads it in UTC, the monitor expects the run five hours early in winter and four in summer, alerts before the run has started, and recovers when it arrives. Whatever monitor you use, it has to evaluate the schedule in the CronJob's zone.

CronRadar evaluates schedules in the application's time zone, an IANA name such as `America/New_York` set in the application's settings; an unset or unrecognized name means UTC, so check the spelling. There's no CronRadar Kubernetes integration, so each CronJob reports over HTTP, and the schedule it sends is read in that zone. Two setups work:

1. **Same zone in both places.** Set the CronRadar application's zone to the CronJob's `timeZone` and send the schedule unchanged.
2. **UTC in both places.** Use `timeZone: 'Etc/UTC'` on the CronJob and leave the application on UTC.

One application has one zone, so CronJobs in different zones go in different applications, or are all written in the application's zone. For setup 1, the container's report function sends the CronJob's own expression:

```sh
report() {
  event=$1
  shift
  curl --fail --silent --show-error --max-time 5 --output /dev/null \
    --request POST --get --user "$CRONRADAR_API_KEY:" \
    --data-urlencode "schedule=0 7 * * 1-5" \
    --data-urlencode "run_id=$RUN_ID" \
    "$@" "https://cron.life/api/v1/ping/morning-digest/$event" || true
}
```

The [Kubernetes CronJob monitoring](https://cronradar.com/blog/kubernetes-cronjob-monitoring) guide has the full container command, which reports start, runs the job, reports complete or fail, and exits with the job's own code.

On transition nights, CronRadar and robfig/cron agree on most schedules and differ on the hour that moves. For a time skipped by spring forward, CronRadar expects the run at the first valid minute after the gap; the CronJob doesn't run that night, so no report arrives and the monitor alerts. That alert is accurate: the run really didn't happen. For a repeated time, CronRadar expects one run, at the first instance; the CronJob's second Job reports as an extra run and doesn't cause a missed-run alert. If neither is acceptable, move the schedule out of the transition window.

## Frequently Asked Questions

### What time zone does a Kubernetes CronJob use by default?

The local time zone of the kube-controller-manager process, which runs the CronJob controller. That's set by the control plane, not by your nodes or Pods, and may be UTC or something else. Set `.spec.timeZone` so the manifest decides.

### Can I use CRON_TZ in a Kubernetes CronJob schedule?

No. Kubernetes rejects `CRON_TZ` or `TZ` in `.spec.schedule` when you create a CronJob, with "cannot use TZ or CRON_TZ in schedule, use timeZone field instead." An older CronJob that already has the prefix can be updated, but not with `timeZone` at the same time. Move the zone to `.spec.timeZone`.

### Does spec.timeZone change the time inside the container?

No. It only decides when Jobs are created. The container's clock and its `TZ` come from the image and the Pod spec; set a `TZ` environment variable if the job needs local time, and make sure the image has zone data.

### How do Kubernetes CronJobs handle daylight saving time?

A run scheduled inside the skipped spring-forward hour doesn't happen that night, and a run inside the repeated fall-back hour happens twice. Schedule outside the transition window, usually 01:00 to 03:00 local time, or use UTC.

### Which Kubernetes version supports CronJob timeZone?

`.spec.timeZone` has been stable since Kubernetes 1.27. On 1.27 and later you can rely on it without feature gates.
