A Kubernetes CronJob creates a Job on a repeating schedule, using the same five-field syntax as Unix cron. The syntax is the easy part. Most problems come from the settings around it: which time zone the schedule uses, what happens when a run takes longer than the interval, and what happens when the controller misses a start time.
A complete manifest
apiVersion: batch/v1
kind: CronJob
metadata:
name: nightly-report
spec:
schedule: "30 2 * * *"
timeZone: "Europe/Paris"
concurrencyPolicy: Forbid
startingDeadlineSeconds: 600
successfulJobsHistoryLimit: 3
failedJobsHistoryLimit: 3
suspend: false
jobTemplate:
spec:
backoffLimit: 2
activeDeadlineSeconds: 3600
template:
spec:
restartPolicy: OnFailure
containers:
- name: report
image: registry.example.com/report:1.4.2
command: ["/app/run-report", "--yesterday"]
Apply it with kubectl apply -f cronjob.yaml. Every field except schedule and jobTemplate is optional, and the sections below explain what each one does.
restartPolicy inside the pod template must be OnFailure or Never. The default for pods, Always, is rejected for Jobs.
Schedule syntax
The schedule field takes the standard five fields: minute, hour, day of month, month, day of week.
┌──────── minute (0-59)
│ ┌────── hour (0-23)
│ │ ┌──── day of month (1-31)
│ │ │ ┌── month (1-12)
│ │ │ │ ┌ day of week (0-6, Sunday = 0)
* * * * *
Steps (*/15), lists (1,15) and ranges (1-5) work as they do in a normal crontab. If you need a refresher, see cron operators explained. The usual macros are also accepted:
| Macro | Equivalent |
|---|---|
@hourly | 0 * * * * |
@daily or @midnight | 0 0 * * * |
@weekly | 0 0 * * 0 |
@monthly | 0 0 1 * * |
@yearly or @annually | 0 0 1 1 * |
There is no seconds field, so the smallest interval is one minute. A few examples:
schedule: "*/5 * * * *" # every 5 minutes
schedule: "0 */6 * * *" # every 6 hours, on the hour
schedule: "0 9 * * 1-5" # 09:00 on weekdays
schedule: "0 0 1 * *" # midnight on the 1st of each month
Two things to keep in mind. Day-of-month and day-of-week follow the usual cron rule, where restricting both makes the job run when either matches (see the day-of-month / day-of-week rule). And the CronJob name must be 52 characters or fewer, because Kubernetes appends a timestamp to build each Job name.
Time zones
By default, the schedule is interpreted in the time zone of the kube-controller-manager process. On most clusters that is UTC, but you can't always tell from inside the cluster, and managed clusters don't let you change it. A job set for 0 9 * * * may run at 09:00 UTC, which is 10:00 or 11:00 in Paris depending on the season.
Since Kubernetes 1.27, the timeZone field is stable. Set it to an IANA name:
spec:
schedule: "0 9 * * *"
timeZone: "America/New_York"
The controller then handles daylight saving changes for you. Some practical points:
- Use IANA names such as
Europe/Paris, not abbreviations such asCET. An invalid name makes the CronJob fail validation. - Do not put the zone inside the schedule string.
CRON_TZ=Europe/Paris 0 9 * * *andTZ=...prefixes are not supported and the API server rejects them. Use thetimeZonefield. - Around a DST change, a local time that doesn't exist (02:30 on the spring-forward night) or exists twice (the fall-back night) can be skipped or run once, depending on the zone rules. If the exact time matters, schedule outside the 01:00 to 03:00 window or use UTC.
- On clusters older than 1.27 the field may be missing or behind a feature gate. There, convert the time to UTC yourself.
More on how time zones go wrong in general in time zones and cron jobs.
concurrencyPolicy
This decides what happens when it's time to start a new Job and the previous one is still running.
| Value | Behaviour |
|---|---|
Allow (default) | Start the new Job anyway. Runs overlap. |
Forbid | Skip the new run. The skipped run counts as missed. |
Replace | Delete the running Job and start a new one. |
Use Forbid for anything that writes to shared state, such as database maintenance, report generation or syncs. Use Replace when only the latest run matters and an old one is safe to kill. Allow is fine for idempotent, independent work, but it is a surprising default when a run occasionally takes longer than the interval.
startingDeadlineSeconds and missed schedules
The CronJob controller checks for missed schedules and starts them if they are within the deadline. startingDeadlineSeconds is how many seconds late a Job is still allowed to start. If it can't start within that window, the run is counted as failed and skipped.
There is also a hard limit that catches people: if the controller counts more than 100 missed schedules, it stops scheduling the CronJob and logs an error like this:
Cannot determine if job needs to be started: too many missed start times (> 100). Set or decrease .spec.startingDeadlineSeconds or check clock skew.
This happens with a CronJob that runs every minute when the controller is down for a couple of hours, or when concurrencyPolicy: Forbid keeps skipping runs because a Job is stuck. Without startingDeadlineSeconds, the controller counts misses from the last scheduled time. With it set, it only counts misses inside that window, so a modest value (a few minutes up to the schedule interval) avoids the problem. Values below 10 seconds may not work reliably, because the controller checks roughly every 10 seconds.
History, retries and timeouts
successfulJobsHistoryLimit(default 3) andfailedJobsHistoryLimit(default 1) control how many finished Jobs, and their pods, are kept. Keep a few failed ones around so you can read their logs. Setting a limit to 0 deletes them right away.backoffLimit(default 6) is how many times a failed pod is retried before the Job is marked failed. Retries back off exponentially, so a limit of 6 can take a while to give up. Lower it for jobs where a retry rarely helps.activeDeadlineSecondson the Job spec caps the total runtime. When it's reached, Kubernetes terminates the pods and marks the Job failed, whateverbackoffLimitsays. This is your protection against a hung process holding a slot forever, particularly withForbid.suspend: truestops new Jobs from being created. Jobs that are already running aren't affected. Pause and resume without editing the file:
kubectl patch cronjob nightly-report -p '{"spec":{"suspend":true}}'
kubectl patch cronjob nightly-report -p '{"spec":{"suspend":false}}'
Because Jobs can run more than once in rare cases (the docs say a CronJob creates a Job "approximately once" per schedule time), write the work to be idempotent.
Running a CronJob manually
To test a CronJob without waiting for the schedule, create a Job from it:
kubectl create job --from=cronjob/nightly-report nightly-report-manual-1
The Job gets the same pod template, so it exercises the real image, environment and secrets. Delete it when you're done:
kubectl delete job nightly-report-manual-1
Debugging a CronJob that does nothing
Start with the CronJob itself:
kubectl get cronjob nightly-report
NAME SCHEDULE TIMEZONE SUSPEND ACTIVE LAST SCHEDULE AGE
nightly-report 30 2 * * * Europe/Paris False 0 14h 9d
If LAST SCHEDULE is empty, the CronJob has never fired. Check SUSPEND, check the time zone, and read the events:
kubectl describe cronjob nightly-report
Events at the bottom show messages such as SuccessfulCreate, SawCompletedJob, MissSchedule or the "too many missed start times" error above.
If Jobs are being created but fail, follow the chain from Job to pod to logs:
kubectl get jobs -l job-name --sort-by=.metadata.creationTimestamp
kubectl get pods --selector=job-name=nightly-report-29012345
kubectl logs job/nightly-report-29012345
kubectl describe pod nightly-report-29012345-abcde
In describe pod, look for ImagePullBackOff, OOMKilled, a failing readiness of a mounted secret, or Error with an exit code. Pods that are Pending usually mean no node has the resources, or a node selector or taint doesn't match.
Finally, remember that a CronJob's pod has none of your shell environment. Environment variables, mounted config and the working directory come from the manifest alone, which is the same lesson as in why a cron job doesn't run.
Before you commit a schedule, you can paste it into the decoder to confirm it means what you think it does. To stop runs from stacking up outside Kubernetes, see preventing overlapping cron jobs.