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:

MacroEquivalent
@hourly0 * * * *
@daily or @midnight0 0 * * *
@weekly0 0 * * 0
@monthly0 0 1 * *
@yearly or @annually0 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 as CET. An invalid name makes the CronJob fail validation.
  • Do not put the zone inside the schedule string. CRON_TZ=Europe/Paris 0 9 * * * and TZ=... prefixes are not supported and the API server rejects them. Use the timeZone field.
  • 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.

ValueBehaviour
Allow (default)Start the new Job anyway. Runs overlap.
ForbidSkip the new run. The skipped run counts as missed.
ReplaceDelete 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) and failedJobsHistoryLimit (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.
  • activeDeadlineSeconds on the Job spec caps the total runtime. When it's reached, Kubernetes terminates the pods and marks the Job failed, whatever backoffLimit says. This is your protection against a hung process holding a slot forever, particularly with Forbid.
  • suspend: true stops 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.