A Kubernetes CronJob creates and manages short-lived Jobs on a scheduled, repeating basis. It is the Kubernetes equivalent of a standard Unix crontab file, making it ideal for periodic tasks like database backups, report generation, or maintenance scripts.
Minimal Example Manifest
apiVersion: batch/v1
kind: CronJob
metadata:
name: nightly-backup
spec:
schedule: "0 2 * * *" # Runs every day at 02:00 UTC
timeZone: "Etc/UTC" # Optional: set preferred timezone (Kubernetes 1.27+)
concurrencyPolicy: Forbid
startingDeadlineSeconds: 100
successfulJobsHistoryLimit: 3
failedJobsHistoryLimit: 1
jobTemplate:
spec:
template:
spec:
containers:
- name: backup-task
image: alpine:latest
command:
- /bin/sh
- -c
- echo "Running database backup..."; sleep 5
restartPolicy: OnFailure
Schedule Syntax Quick Reference
The schedule field uses standard cron syntax with 5 fields:
minute hour day-of-month month day-of-week
Schedule Format Interpretation
* * * * * Every minute
*/15 * * * * Every 15 minutes
0 0 * * * Every day at midnight
0 9 * * 1 Every Monday at 9:00 AM
Critical Settings
- concurrencyPolicy: Controls how overlapping executions are handled when a previous run hasn't finished:
- Allow (default): Runs concurrent jobs simultaneously.
- Forbid: Skips the new job if the previous one is still running.
- Replace: Cancels the currently running job and starts the new one.
- startingDeadlineSeconds: The deadline (in seconds) for starting a job if it missed its scheduled time (e.g., cluster was temporarily down).
- successfulJobsHistoryLimit / failedJobsHistoryLimit: Number of completed or failed Job/Pod records to keep for auditing before automatic cleanup.
- restartPolicy: Must be set on the pod template spec to either OnFailure or Never (Always is invalid for Jobs).
Helpful kubectl Commands
Task Command
==== ========
List CronJobs kubectl get cronjobs
Inspect configuration kubectl describe cronjob <name>
Manually trigger immediately kubectl create job --from=cronjob/<cronjob-name> <manual-job-name>
Pause schedule kubectl patch cronjob <name> -p '{"spec": {"suspend":true}}'
View logs of latest run kubectl logs job/<job-name>
CronJobs Inner Mechanism
Under the hood, Kubernetes CronJobs rely on a decentralized control loop pattern. They are not handled by a traditional Linux cron daemon running on a single server, but rather by the Kubernetes Control Plane through cascading controllers.
How CronJobs Are Implemented
The implementation follows a 3-tier hierarchical model:
CronJob Object --> Job Object --> Pod(s)
Rather than running code directly, a CronJob acts as a factory for Job objects, which in turn manage the Pods where your container actually executes.
┌─────────────────────────────────────────────────────────┐
│ kube-controller-manager │
│ │
│ ┌───────────────────┐ Creates ┌─────────┐ │
│ │ CronJob Controller│ ─────────────────> │ Job │ │
│ └───────────────────┘ └─────┬───┘ │
└──────────────────────────────────────────────────┼──────┘
│
Creates
│
▼
┌─────────┐
│ Pod │
└─────────┘
The Control Loop Mechanism
- Synchronization Loop: The CronJob Controller runs inside kube-controller-manager. Every ~10 seconds, it iterates through all CronJob objects defined in the cluster.
- Schedule Checking: The controller parses the schedule field (e.g., 0 * * * *) and compares the current time against the last time the job was executed.
- Job Spawning: If a run is due, the CronJob controller reads the embedded jobTemplate and creates an actual Job resource.
- Execution: The cluster's separate Job Controller detects the newly created Job resource and spawns one or more Pods to execute your container workload to completion.
- Garbage Collection: Depending on successfulJobsHistoryLimit and failedJobsHistoryLimit, the CronJob controller periodically deletes old completed Job objects (and their associated logs/pods).
Who Controls Them?
Control over CronJobs is split between system components (automation) and users/roles (permissions).
System Component Control
- kube-controller-manager: The core control plane component where the CronJob controller code actually executes. If this component is down, scheduled triggers will pause until it recovers.
- kube-apiserver: Stores the desired state in etcd and validates user manifests.
- kube-scheduler: Assigns the individual Pods spawned by the resulting Jobs to healthy worker nodes.
User & Permission Control (RBAC)
Human administrators and automated service accounts control CronJobs via Kubernetes Role-Based Access Control (RBAC):
Role / Action Required API Permissions (batch/v1)
============= ==============================
Manage Schedules create, update, patch, delete on cronjobs
View Status get, list, watch on cronjobs
Manual Trigger create permissions on jobs (to invoke kubectl create job --from=cronjob/...)
Example RBAC Role for CronJob Operators:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
namespace: prod
name: cronjob-operator
rules:
- apiGroups: ["batch"]
resources: ["cronjobs", "jobs"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
Technical Considerations
- At-Least-Once Execution: Kubernetes schedules are designed around at-least-once execution semantics. Due to control loop timing or network hiccups, a scheduled job might occasionally run twice or run slightly late. Workloads should always be designed to be idempotent.
- Timezones: Controller clocks default to UTC or the local time of kube-controller-manager unless explicit timezones are passed via spec.timeZone (supported in K8s 1.27+).
CronJob is a controller object
In Kubernetes, a controller is a control loop that watches the state of your cluster through the API server and makes changes attempting to move the current state toward the desired state.
Here is how a CronJob fits into the controller pattern:
Why CronJob is a Controller
- Custom Resource / Spec & Status Model: Like Deployment, ReplicaSet, and Job, a CronJob has an API object schema (spec defining desired behavior, status tracking execution state).
- Control Loop Execution: The CronJob implementation runs as a control loop inside the kube-controller-manager component.
- Cascading Controller Pattern: CronJob sits at the top of a controller hierarchy:
CronJob Controller --[creates/manages]--> Job Controller --[creates/manages]--> Pods
- The CronJob Controller reconciles the CronJob spec: it checks the schedule, creates Job resources when a execution is due, cleans up old jobs based on history limits, and handles concurrency policies.
- The Job Controller reconciles those created Job resources to manage individual Pods to completion.
Summary Table
Controller API Group What it Watches What it Creates/Manages
======== ========= ============= ===================
CronJob Controller batch/v1 CronJob specs Job objects
Job Controller batch/v1 Job specs Pod objects
Deployment Controller apps/v1 Deployment specs ReplicaSet objects
