A CronJob turns a schedule into Jobs

Fri, 17 Dec 2027 00:00:00 +0000

A CronJob combines a Job template with a recurring schedule. The CronJob controller creates Jobs; each Job manages the Pods that perform the work. A run can involve retries, replacement Pods, or parallel workers, depending on the Job specification. There need not be a dedicated application process waiting between runs, although completed Jobs and Pods may remain for inspection.

Scheduling is approximate. Duplicate Jobs and missed occurrences are both possible, so do not promise unconditional at-least-once delivery for every scheduled time. Make repeated execution safe and record which business periods actually completed. Idempotency prevents duplicate effects; a separate completeness check detects work that never ran.

Scheduling is approximate, not a durable queue or a promise that every tick completes. startingDeadlineSeconds limits start lateness, not run duration. Source commands were not rerun; example execution remains blocked.

A schedule makes a Job

The five schedule fields describe minute, hour, day of month, month, and day of week. Ranges, steps, and macros such as @daily are supported. */10 * * * * requests ten-minute intervals; it does not guarantee that a Pod starts precisely on those boundaries. Resource shortages and image pulls can delay execution after Job creation.

Set spec.timeZone explicitly when wall-clock interpretation matters. Without it, the controller manager’s local time zone applies; moving machines only changes behavior if that configuration changes. Use the timeZone field rather than putting TZ or CRON_TZ inside the schedule. Daylight-saving transitions and application reporting periods still need a deliberate policy.

Keep the CronJob name within 52 characters because generated Job names need an appended suffix. Since Kubernetes 1.32, generated Jobs carry batch.kubernetes.io/cronjob-scheduled-timestamp. Compare that intended time with creation and start timestamps to investigate delays. The annotation helps diagnosis; it is not the sole possible audit trail or evidence that the business operation finished.

Concurrency is scoped to one CronJob

The default Allow policy permits overlapping Jobs. Forbid declines a new start while an earlier Job remains active; the skipped time counts as missed, and a later eligible start still depends on its deadline. Replace requests deletion before creating a replacement; asynchronous deletion does not prove the old Pods have stopped. These policies do not coordinate separate CronJobs or external workers touching the same data.

A task consistently longer than its interval can fail to complete under Replace. Forbid trades overlap avoidance for missed starts, rather than providing a durable queue. Use application-level deduplication or coordination where overlapping effects would be harmful, including interruption during replacement. A lock alone does not prove that a partially committed operation can safely resume.

Deadlines, suspension and history

startingDeadlineSeconds limits the lateness of a start, not execution duration. Without it, occurrences have no individual starting deadline. The concept guide describes refusing catch-up beyond 100 missed schedules. However, the reviewed 1.34.0 scheduling helper emits a warning and returns the most recent eligible time; it does not reject solely for that count. Verify the server version instead of inferring a permanent stop from the warning. A configured deadline limits the counting window, and values below ten seconds can miss controller checks.

Suspension stops new Jobs without stopping existing ones. Suspended schedule times count as missed, so resuming can trigger immediate catch-up subject to the other rules. Do not treat that as a promise to replay one Job for every missed tick. Keep a durable work ledger if every reporting period must be processed.

History limits retain completed Job objects, with defaults of three successes and one failure. They do not cap concurrent running Jobs or replace execution deadlines. Updating the template affects future Jobs; already-started Jobs retain their own specifications.

When it breaks

A twenty-five-minute task on a ten-minute schedule can overlap under Allow and duplicate writes. Inspect actual ownership, active Pods, and completion records before attributing duplicate business effects to a schedule. A missed-start deadline should reflect how late the result remains useful, rather than an arbitrary attempt to hide controller warnings.

A long gap in lastScheduleTime can also be intentional: suspension, Forbid, a sparse calendar expression, or a changed time zone may explain it. Events expire, and successful Job creation does not establish successful backups. Alert on the last verified usable result as well as scheduling health.

Check it quickly

In the intended read-only context and namespace, inspect an existing nightly-report. These commands were retained from the earlier article and were not rerun against a cluster in this review.

kubectl get cronjob nightly-report -o jsonpath='{.spec.schedule} {.spec.concurrencyPolicy} {.spec.startingDeadlineSeconds}{"\n"}'
kubectl get cronjob nightly-report -o jsonpath='{.status.lastScheduleTime}{"\n"}'
kubectl get jobs --sort-by=.metadata.creationTimestamp -o custom-columns=NAME:.metadata.name,START:.status.startTime,SUCCEEDED:.status.succeeded
kubectl get events --field-selector involvedObject.kind=CronJob --sort-by=.lastTimestamp | tail -5

The Jobs listing includes unrelated Jobs in the namespace; correlate owner references before drawing conclusions. START timestamps alone cannot prove overlap, and an empty SUCCEEDED field does not prove a Job is still running. Check active/failed counts and conditions alongside each scheduled timestamp. Interpret gaps against the actual calendar and policy, and use controller logs when retained Events lack the explanation.

Sources

Kubernetes CronJob, schedule syntax, concurrency policy, the 100-missed-schedule rule and history limits, checked 2026-10-15.
CronJob v1 API reference, field-level definition of the CronJob spec, checked 2026-10-15.
Kubernetes 1.34.0 CronJob scheduling helper, mostRecentScheduleTime and nextScheduleTime select the latest missed time and warn above 100, checked 2026-10-15.
CronJob job control (v1.34.0), DeleteJob uses background propagation; replacement is not a Pod-termination barrier, checked 2026-10-18.