10.20 Kubernetes CronJob Controller

Kubernetes CronJob Controller is the workload controller responsible for creating Job objects on a repeating schedule expressed using standard cron syntax, layering time-based automation on top of the Job controller's own run-to-completion semantics so that a defined task can be executed automatically at regular intervals without manual triggering.

Schedule Definition

Cron Expression Syntax

A CronJob's schedule field uses the standard five-field cron syntax, specifying minute, hour, day of month, month, and day of week values, allowing schedules ranging from simple fixed-time daily executions to complex recurring patterns tied to specific days or intervals.

Timezone Handling

CronJobs support an explicit timeZone field, allowing the schedule to be interpreted according to a specified timezone rather than defaulting to the timezone of the kube-controller-manager process, avoiding ambiguity or drift that could otherwise occur across clusters running in different regions or during daylight saving transitions.

Job Creation Mechanics

Triggering a New Job at Each Scheduled Time

At each point in time matching the configured schedule, the CronJob controller creates a new Job object using the jobTemplate embedded in its own specification, delegating all subsequent execution, retry, and completion tracking entirely to the standard Job controller logic rather than reimplementing it.

Naming and Ownership of Created Jobs

Each Job created by a CronJob is named using a combination of the CronJob's name and a timestamp-derived suffix, and carries an owner reference back to the CronJob, establishing the same ownership and garbage collection relationship seen between other layered controllers such as Deployments and ReplicaSets.

Concurrency Policy

Allow, Forbid, and Replace Options

The concurrencyPolicy field determines how the controller handles a scheduled trigger occurring while a previous Job created by the same CronJob is still running, with Allow permitting overlapping Job executions, Forbid skipping the new trigger entirely if a previous Job is still active, and Replace terminating the still-running Job before starting the new one.

Choosing an Appropriate Policy

Selecting the correct concurrency policy depends on whether the underlying task is safe to run in parallel with itself, with Forbid commonly used for tasks that would produce incorrect results or resource contention if executed concurrently, such as certain database maintenance operations.

Missed Schedule Handling

startingDeadlineSeconds

The startingDeadlineSeconds field bounds how late a Job can be started relative to its originally scheduled time before the controller considers that scheduled execution missed entirely, which matters in scenarios such as the CronJob controller being temporarily unavailable, resulting in a backlog of missed schedule times upon its return.

Avoiding a Backlog of Missed Executions

Without a deadline configured, an extended period of controller unavailability could result in the controller attempting to catch up on every missed scheduled time upon recovery, while a properly configured deadline instead causes sufficiently stale missed schedules to be skipped rather than triggering a burst of delayed, potentially redundant Job executions.

Job History Retention

successfulJobsHistoryLimit and failedJobsHistoryLimit

These fields independently control how many completed Job objects, categorized by whether they succeeded or failed, are retained for historical reference after completion, with older Jobs beyond these limits being automatically cleaned up to prevent unbounded accumulation of historical execution records.

Suspension

The suspend Field

Setting suspend to true prevents the CronJob controller from creating any new Jobs according to the schedule, without deleting the CronJob object itself or its history, providing a straightforward way to temporarily pause a recurring task while preserving its configuration and past execution history for later resumption.