Create a CronJob with History Limits and a Deadline

Original Prepium guide · Written for Kubernetes v1.35 and checked against the official documentation on 6 October 2026. Use a disposable practice cluster.

CronJobs are three objects deep: put each field at the right level

A CronJob does not run containers. It creates a Job on a schedule, and the Job creates Pods. Each layer owns different settings, and most CronJob mistakes on the exam are a correct field placed one level too high or too low. kubectl's default strict validation rejects a field that does not exist at that level, but some names, such as activeDeadlineSeconds, exist at two levels and mean different things.

CronJob .spec            schedule, timeZone, concurrencyPolicy, startingDeadlineSeconds,
  |                      successfulJobsHistoryLimit, failedJobsHistoryLimit, suspend
  '-- jobTemplate.spec   activeDeadlineSeconds, backoffLimit
        '-- template.spec  containers, restartPolicy (Never or OnFailure)

1. Read the schedule before you write it

The schedule has five fields: minute, hour, day of month, month, day of week (0 is Sunday). 15 2 * * 1-5 means 02:15 on weekdays. A step after an asterisk repeats through the whole range, so */20 in the minute field fires at :00, :20 and :40. Macros such as @hourly and @daily also work. Without .spec.timeZone, the schedule follows the kube-controller-manager's local time zone; putting TZ= or CRON_TZ= inside the schedule string is rejected by validation.

2. A manifest with every layer visible

apiVersion: batch/v1
kind: CronJob
metadata:
  name: ledger-report
  namespace: prepium-tutorial
spec:
  schedule: "15 2 * * 1-5"
  concurrencyPolicy: Forbid
  startingDeadlineSeconds: 600
  failedJobsHistoryLimit: 4
  jobTemplate:
    spec:
      activeDeadlineSeconds: 120
      backoffLimit: 2
      template:
        spec:
          restartPolicy: OnFailure
          containers:
          - name: report
            image: busybox:1.36
            command: ["sh", "-c", "date; echo ledger totals ready"]

What each choice does:

• concurrencyPolicy: Forbid skips a new run if the previous Job is still going. The default, Allow, lets runs overlap; Replace cancels the running Job and starts the new one.
• startingDeadlineSeconds is about starting late: if the controller could not create the Job within 600 seconds of its slot, that run is skipped and counted as failed. Unset means no deadline.
• activeDeadlineSeconds on the Job is about running long: after 120 seconds, however many Pods were tried, running Pods are terminated and the Job fails with reason DeadlineExceeded. It beats backoffLimit if it is hit first.
• History limits default to 3 successful and 1 failed Job. Only the failed one is overridden here, so successful runs still keep 3.
• restartPolicy must be Never or OnFailure. With OnFailure the kubelet re-runs the container inside the same Pod; with Never every failure leaves a failed Pod behind and the Job controller creates a fresh one, which keeps logs of each attempt.

3. Test it now instead of waiting until 02:15

kubectl create namespace prepium-tutorial
kubectl apply -f ledger-report.yaml
kubectl create job ledger-manual --from=cronjob/ledger-report -n prepium-tutorial
kubectl -n prepium-tutorial wait --for=condition=Complete job/ledger-manual --timeout=90s
kubectl -n prepium-tutorial logs job/ledger-manual

--from=cronjob/ copies the CronJob's job template into a one-off Job, so it proves the Pod spec, command and image without touching the schedule. You can also generate a starting manifest with kubectl create cronjob NAME --image=... --schedule="..." --restart=OnFailure --dry-run=client -o yaml -- COMMAND and add the remaining fields by hand.

4. Confirm the stored values

kubectl -n prepium-tutorial get cronjob ledger-report -o yaml
kubectl explain cronjob.spec.jobTemplate.spec.activeDeadlineSeconds

Read back the YAML and check that defaults were filled in where you left fields out. kubectl explain with the full path settles any doubt about which level a field belongs to.

Common mistakes

• activeDeadlineSeconds placed in the Pod template instead of the Job spec. It is accepted, but it limits each Pod, not the Job.
• restartPolicy left out of a hand-written template, or set to Always. Jobs only accept the two values above, so the object is rejected.
• Confusing the two deadlines: startingDeadlineSeconds never stops a slow Job, and activeDeadlineSeconds never rescues a late start.
• A CronJob name over 52 characters. The controller appends 11 characters to build Job names, so longer names are not allowed.

Cleanup: kubectl delete namespace prepium-tutorial. References: CronJob, Jobs, kubectl create job. Next, try choosing the right workload controller.