If you only remember one paragraph, make it the next one.

A CronJob is a Kubernetes object that creates a new Job again and again on a repeating schedule that you write in a short text pattern. A Job is a one-time task that runs a container until it finishes successfully. So a CronJob is a timetable, and each tick of the timetable produces one fresh Job, which in turn starts a pod to do the actual work. The word cron comes from the classic Unix scheduling tool that has existed since the 1970s, and its name comes from the Greek word for time.

The three words you must know

Where CronJobs fit among Kubernetes workloads

Kubernetes has different objects for different kinds of work. A Deployment runs programs that should stay alive forever, such as a website. A Job runs a task once until it succeeds. A CronJob runs a task again and again on a timetable. A DaemonSet runs one helper on every machine. Choosing the right one is the first design decision, and using a Deployment for a task that should run at night is a classic beginner mistake.

A short history

The idea of a scheduled task is very old. Unix computers have had a cron program since the 1970s, and administrators used a single file on a single server to list their timetable. That was simple, but if the server died, the timetable died with it, and nobody could easily see what ran where. Kubernetes arrived with a better idea: keep the timetable as an object in the cluster, run each task in a fresh, isolated pod on any healthy machine, and let the cluster handle the retries. The feature first appeared around 2016 under the name ScheduledJob, was renamed CronJob soon afterwards, and became fully stable in Kubernetes 1.21.

A CronJob is the top of a small ladder. Understanding each rung makes the top one obvious.

A Kubernetes cluster is a group of computers working as one. Some computers make decisions and form the control plane, while others run applications and are called worker nodes. Whatever you run ends up as a container inside a pod on a worker node. The CronJob sits at the top of a chain that reaches down to that container.

flowchart TB
    CJ["CronJob: the timetable"] -->|"creates at each scheduled time"| J1["Job for Monday 02:00"]
    CJ -->|"creates at each scheduled time"| J2["Job for Tuesday 02:00"]
    CJ -->|"creates at each scheduled time"| J3["Job for Wednesday 02:00"]
    J3 -->|"creates"| P1["Pod attempt 1"]
    P1 -->|"runs"| C1["Container does the work"]
    J3 -.->|"if attempt 1 fails, creates"| P2["Pod attempt 2"]
    P2 --> C2["Container does the work"]

What a Job promises

The Job is where most of the useful behaviour lives, so let us look at it closely. A Job says: “run this pod until it has finished successfully, and try again if it fails”. You can set how many successful completions are needed, how many pods may run at the same time, and how many retries are allowed before giving up. That retry limit is called backoffLimit and its default is six. Between retries, Kubernetes waits longer each time, starting near ten seconds and doubling until it reaches a ceiling of about six minutes. This is called exponential backoff, and it prevents a broken task from hammering the cluster.

Two special rules for job pods

Every pod created by a Job must have a restart policy of either Never or OnFailure. With Never, a failed pod stays in place as evidence and a new pod is created for the retry. With OnFailure, the failed container is restarted inside the same pod. The usual Always policy, which suits websites, is not allowed, because a task that is supposed to finish would then restart forever.

Splitting big work into many pods

Two settings shape how much work a single Job does. completions says how many pods must finish successfully before the Job counts as done. parallelism says how many of those pods may run at the same moment. If you set completions to ten and parallelism to two, Kubernetes runs pods two at a time until ten have succeeded. This is useful for chopping a big task into slices, such as processing ten batches of customer records.

An indexed Job goes one step further by giving every pod a number, from zero upwards, so each pod knows which slice of the work belongs to it and does not need any coordination. Most CronJobs keep the defaults of one and one, but knowing these settings lets you grow a nightly task from a single pod into a small team without changing how it is scheduled.

The schedule looks like a puzzle at first. It is really five small boxes read from left to right.

The five fields

A schedule is five values separated by spaces. Reading from the left, they are the minute, the hour, the day of the month, the month, and the day of the week. A star means “every possible value”. A slash means “every so many”. A comma builds a list. A dash builds a range.

Examples in plain words

Kubernetes also accepts handy shortcuts. The word @hourly means the start of every hour, @daily means midnight each day, @weekly means midnight on Sunday, @monthly means midnight on the first of the month, and @yearly means midnight on the first of January.

Common schedule mistakes

The first trap is the meaning of a star. Writing a star in the minute field with a fixed hour, such as a star followed by 3, does not mean “once at three o’clock”. It means “every minute during the three o’clock hour”, which is sixty runs. To run once, put a specific minute such as 0 in the first field. The second trap concerns the day fields. In classic cron behaviour, when both the day of the month and the day of the week are restricted, a match on either one is enough to run the job, not both together. So a schedule that names the 15th and also names Fridays will run on every 15th and on every Friday. If you want only Fridays that fall on the 15th, you must check the date inside the job itself.

The third trap is the five-versus-six confusion. Some tools use a sixth field for seconds, but Kubernetes does not. If you copy a schedule from another system, count the fields, and remember that the smallest step is one minute.

Time zones: the quiet source of surprises

By default, the schedule is read in the time zone of the control plane program that manages CronJobs, which is usually Coordinated Universal Time, or UTC, on cloud clusters. So “0 9 * * *” might mean 9:00 in London in winter but 14:30 in India. Since Kubernetes 1.27, you can state a timeZone field with a proper name from the international time zone database, such as Asia/Kolkata or America/New_York, and the schedule is then read in that zone. Do not put time zone words inside the schedule text itself, because recent versions reject that.

Who watches the clock? A small loop inside the control plane, doing a very simple job again and again.

Inside the control plane there is a program called the controller manager, which bundles many small watchers named controllers. One of them is the CronJob controller. Like every Kubernetes controller, it follows a loop: look at the desired state, look at the real state, and fix any gap. Here the desired state is “a Job should exist for every scheduled time that has arrived”, and the real state is the list of Jobs that actually exist.

What happens on every check

Good to know about the design

The controller does not run your task itself. It only creates Job records through the API server. From there, the Job controller creates pods, the scheduler chooses a machine for each pod, and the kubelet on that machine starts the containers. This division of labour means each component is simple. It also means that if the control plane briefly stops, running pods keep going, and when it returns, the controller catches up by reading the recorded last schedule time.

What the controller remembers

Every CronJob has a status section that the controller keeps up to date. It contains the time of the last scheduled run, the time of the last successful run in newer versions, and a list of the Jobs that are active at this moment. These few facts are all the controller needs to rebuild its picture after any restart. They also give you a quick way to answer the questions “when did it last run?” and “is anything running right now?” without reading logs. Monitoring tools read the same fields, as you will see in a later chapter.

Imagine a nightly backup that normally takes twenty minutes, but one night takes ninety. What should happen when the next schedule time arrives?

Each CronJob has a setting called concurrencyPolicy that answers this question. There are three choices, and picking the right one protects your data.

flowchart TD
    T["Scheduled time arrives"] --> Q{"Is the previous Job still running?"}
    Q -->|"No"| N["Create the new Job"]
    Q -->|"Yes"| P{"concurrencyPolicy"}
    P -->|"Allow"| A["Create the new Job too, both run together"]
    P -->|"Forbid"| F["Skip this run and count it as missed"]
    P -->|"Replace"| R["Stop the old Job, then create the new Job"]

Choosing a concurrency policy: a quick guide

Ask three questions about your task. First, does a second copy running at the same time cause harm, such as two writers changing the same records? If yes, avoid Allow. Second, is an old result still useful once a newer one is due? If not, prefer Replace, because the freshest answer is all that counts. Third, is it acceptable to skip a run entirely? If the task must eventually complete every period, Forbid could leave gaps, so pair it with a reasonable deadline and an alert. Writing the answers next to the CronJob description in your repository helps the next engineer understand the choice.

Clusters are not perfect. Sometimes the moment passes before anything can act. Kubernetes gives you settings to decide how late is too late.

What is a missed run?

A run is missed when its scheduled time has passed but no Job was created. This can happen because the control plane was down, because the CronJob was suspended, or because a Forbid policy skipped it. When the controller returns, it looks at the missed times and decides whether to create a Job now or to let them go.

startingDeadlineSeconds: the lateness allowance

The setting startingDeadlineSeconds says how many seconds after the scheduled moment a run may still begin. If the controller is late by more than that, it counts the run as failed to start and skips it. If you do not set it, there is no deadline, and the controller will start the latest missed run whenever it finally notices, but only that latest one, not every one in the backlog.

The limit of one hundred

The controller is careful not to flood the cluster after a long outage. If it finds more than one hundred missed schedules since the last recorded run, it refuses to start the Job and logs an error. This happens mostly with schedules that fire every minute after a long break, or when a deadline setting is very generous. Setting a deadline shortens the window it needs to look back and avoids the problem.

Suspending a CronJob

There is a simple switch named suspend. When set to true, the controller stops creating new Jobs, but Jobs already running are left alone. It is the polite way to pause work during maintenance or while investigating a problem, without deleting the CronJob and losing its settings. Be aware that the runs that pass while suspended are counted as missed, so when you resume, the most recent one may start immediately unless a deadline says it is too late.

Things go wrong at three in the morning. A good CronJob expects that, retries sensibly, and leaves the cluster tidy.

The safety nets for a single run

Keeping history under control

Every run leaves behind a Job and its pods. Without cleanup, a job that runs every minute would create more than fourteen hundred Job records a day and slowly clog the control plane database, which is only meant for small records. Kubernetes gives you two kinds of cleanup.

The history limits keep the most recent records so that you can read the logs of the last few runs. The time-based setting removes each Job on a timer, which is useful when you ship logs elsewhere and do not need the pod to linger. Many teams use both: a small history limit for quick inspection and a time limit as a safety net.

Different kinds of failure

It helps to separate failures into three kinds. A program failure happens when your own code exits with an error, perhaps because a database is unreachable. A pod failure happens when the container is killed from outside, for example because it used more memory than its limit, or because its node was drained for maintenance or ran out of resources. A Job failure happens when the retries run out or the active deadline passes. The Job treats program and pod failures alike by creating a replacement pod, up to the backoff limit. Reading the pod’s final state tells you which kind you have: an out-of-memory kill needs a larger memory limit, while a program error needs a fix in the code or its settings.

Newer versions of Kubernetes also let a Job follow a pod failure policy, which lets you say “if the container exits with this special code, stop retrying at once”, or “if the pod was lost because its node was removed, do not count this against the retry limit”. This saves you from wasting retries on errors that will never fix themselves, such as a missing configuration file.

Let us watch one scheduled run travel through the whole system, from the clock striking to the last container exiting.

sequenceDiagram
    participant C as CronJob controller
    participant A as kube-apiserver
    participant J as Job controller
    participant S as kube-scheduler
    participant K as kubelet on chosen node
    C->>C: Clock reaches scheduled time
    C->>A: Create Job from the CronJob template
    A-->>C: Job saved
    J->>A: Watch shows new Job, create Pod
    S->>A: Watch shows Pod without a node, bind it
    K->>A: Watch shows Pod assigned to me
    K->>K: Pull image and start the container
    K->>A: Report Pod Succeeded
    J->>A: Mark Job Complete
    C->>A: Update last schedule time and prune old Jobs

The life of a single scheduled run

What you see when you list CronJobs

A listing shows a short table with the schedule, whether the job is suspended, how many Jobs are active right now, when it last ran, and how old the CronJob is. The active count is the quickest way to spot a stuck run: if it stays at one long after the expected end time, something is hanging. The last-schedule column tells you whether the timetable is still ticking at all.

Watching a run as it happens

When you test a new CronJob, it is instructive to watch the objects appear in real time. A Job record shows up first, then a pod in the Pending state while the scheduler finds it a home, then the pod moves to Running as the container starts, and finally to Completed when the exit code is zero. If the pod sits in Pending, look at the scheduler’s message. If it shows an image pull problem, check the image name and registry access. If it enters an error state and restarts, read the container’s logs first. Seeing this sequence once with your own eyes makes every later problem easier to place.

CronJobs are simple and popular, but they are not the answer to every scheduling problem. Knowing their limits saves pain.

CronJob compared with other ways to run scheduled work

Moving from an old server cron to a CronJob

Many teams begin their journey by copying a line from a crontab on an old server into a CronJob. A safe way to do this has four steps. First, package the script and its tools into a container image, so it no longer depends on whatever happened to be installed on that server. Second, move passwords out of the script and into Secrets. Third, run the CronJob in a test namespace next to the old cron for a week, and compare results. Fourth, switch off the old cron only when the new one has proved itself and alerts are in place. This gradual path removes the fear of change, and it often reveals hidden assumptions, such as a script that quietly relied on a file that only existed on the old machine.

A task that runs for a few minutes a day still needs room on the cluster when it starts. Planning that room is part of the design.

Give every task honest resource numbers

Every container can declare a request, the amount of processor and memory it needs reserved, and a limit, the ceiling it may not cross. The scheduler places the pod using the request. If a nightly job asks for too much, the pod may sit Pending because no machine has enough room. If it asks for too little, it may be slowed down or killed when it runs out of memory. Measure a few real runs and set numbers close to what you saw.

Passing settings and data to a job

A scheduled task rarely works alone. It needs settings, credentials, and a place to read and write data. Settings that are not secret go in a ConfigMap, and secret values go in a Secret. Both can be handed to the container as environment variables or as files. Data should live outside the pod, in object storage such as Amazon S3, in a database, or on a shared volume, because the pod’s own disk disappears when the run ends.

Be careful with shared volumes. Many disk types can be attached to only one node at a time. If two runs overlap on different nodes and both need the same disk, one will wait. Object storage avoids this problem and is the usual choice for backups and reports. It also helps to pass the date or time window to the job as an argument, so the task knows exactly which slice of data to handle, rather than guessing from the clock at the moment it starts.

The thundering herd

When many CronJobs are set for the same minute, especially midnight, they all start at once. Hundreds of pods appear together, all pulling images, all asking for room. This sudden crowd is called a thundering herd. It can delay the jobs, slow other applications, and trigger the node autoscaler to add machines just to handle a few minutes of work. The cure is simple: spread schedules over different minutes, and where possible keep batch work on its own group of nodes.

What happens if the control plane is down?

Running Jobs and pods keep going, because the worker nodes already know what to do. But no new Jobs are created while the CronJob controller is unavailable. When the control plane returns, the controller compares the clock with the last recorded run and starts the latest missed one, subject to the deadline you set. This is why important jobs need both a sensible startingDeadlineSeconds and an alert that tells you when a run did not happen.

A CronJob is a machine that runs code on its own, with real permissions, while nobody is watching. That deserves care.

Key protections

Why repetition raises the stakes

A vulnerable web page is attacked when someone finds it. A vulnerable CronJob is executed on schedule whether or not anyone is looking. If its image is compromised, or its script downloads code from an unknown place at each run, the harm repeats itself every night. Attackers have also abused CronJobs in hijacked clusters as a place to hide, because a small job that starts every hour looks harmless. Auditing the list of CronJobs and their images from time to time is a cheap and valuable habit.

Sharing a cluster between teams

In a shared cluster, each team usually gets its own namespace, which is a named area that keeps objects separate, like floors in an office block. Scheduled work belongs in the namespace of the team that owns it, so that permissions, quotas, and costs stay clear. Set a ResourceQuota on each namespace to cap the total processor, memory, and number of pods it may use, and a LimitRange to give sensible default requests to containers that forget to declare them. Together they stop one team’s forgotten job from starving everybody else. It also helps to label every CronJob with the owner’s name and a contact channel, so that whoever notices a problem at night knows whom to wake.

Scheduled jobs run in the dark. Good monitoring turns on the lights only when something is wrong.

Two kinds of failure to catch

What to watch

A helper called kube-state-metrics turns the state of Kubernetes objects into numbers that Prometheus, the popular monitoring system, can collect. It publishes the time of the next scheduled run, the time of the last run, the time of the last success, and how many Jobs are currently active. It also reports how many Jobs have succeeded or failed. Grafana can draw these numbers, and Alertmanager can send alerts.

flowchart LR
    CJ["CronJob and Job objects"] --> KSM["kube-state-metrics"]
    KSM --> PR["Prometheus"]
    POD["Job pods write logs to standard output"] --> LA["Log agent on each node"]
    LA --> LS["Central log store"]
    PR --> GF["Grafana dashboards"]
    PR --> AM["Alertmanager"]
    AM --> ON["On-call engineer"]
    JOBEND["Job pings a heartbeat service on success"] --> DMS["Heartbeat monitor that expects a daily signal"]
    DMS --> ON

The dead man’s switch

A powerful trick is to make each successful run send a tiny “I am alive” message to an outside monitoring service at the end of its work. That service expects the message every day. If a day passes without one, it raises an alarm. This approach catches every failure, even those where Kubernetes itself is broken, because it depends on evidence of success rather than on the absence of failure.

Reading the cluster’s own summary

Before setting up any dashboard, get comfortable with the built-in views. Listing the CronJobs in a namespace shows the schedule, the suspend flag, the count of active Jobs, the time since the last schedule, and the age. Listing the Jobs shows how many completions each achieved and how long it took. Describing one Job shows its events in plain sentences, such as pods created, pods failed, and the reason the Job ended. These three views answer ninety percent of the questions you will have at three in the morning, and knowing them well makes you faster than any tool.

Logging

Programs in a job should print messages to standard output, and a log agent should copy them to a central store before the pod is cleaned up. Include the run’s date and key numbers in the messages, such as “copied 12,340 records”. When a report looks wrong next week, those lines are the evidence you will want.

Reliable scheduled tasks share a few habits. Unreliable ones share a different set of shortcuts.

Patterns that work well

An idempotency example

Suppose a job sends a daily summary email to customers. A careless design says “send an email to everyone” every time it runs. If Kubernetes retries after a partial failure, half the customers receive two emails. A careful design keeps a small table listing which customers have already received today’s summary. The job first asks “who has not yet received today’s email?”, sends only to those, and marks each one as done immediately after sending. Now the job can be retried, duplicated, or run by hand, and the result is always the same: each customer receives exactly one email. This small habit is the single most valuable pattern in scheduled work.

Anti-patterns to avoid

These habits come from many nights of failed backups and silent reports. Copy them early and skip the pain.

Habits of a reliable CronJob

Common mistakes and fixes

CronJobs are quiet workers. Here are the tasks teams most often hand to them.

A night in the life of a backup job

To make the pieces concrete, imagine a nightly backup set for 02:17 UTC with Forbid, a start deadline of ten minutes, an active deadline of one hour, and a backoff limit of three. At 02:17 the controller creates a Job. The scheduler places its pod on a batch node, and the container starts copying data to storage. At 02:24 the database briefly refuses connections, the program exits with an error, and the Job creates a second pod after a short wait. That attempt succeeds at 02:41, the pod ends with exit code zero, and the Job is marked Complete. The CronJob records the success time, and the heartbeat message tells the outside monitor that tonight’s backup is safe.

Now imagine the control plane was down from 02:10 to 02:35. When it returns, the controller sees that 02:17 was missed by eighteen minutes. That is beyond the ten-minute deadline, so it skips the run, and the missing-success alert fires at the next check, letting a human start the backup by hand. Every setting in this story played a part, and each one was chosen in advance for a reason.

Short, plain answers to the questions beginners ask most.

Back to the bakery standing order for one last look.

A CronJob is a standing order for your cluster. You describe the task once, write the timetable as five small fields, and Kubernetes delivers a fresh Job at every tick, complete with its own pod, its own retries, and its own record. It keeps its promise most of the time, and your job is to make sure that the rare times it does not are harmless and visible. Choose the concurrency policy on purpose, set deadlines, state the time zone, keep tasks safe to repeat, and watch for the run that never came. With those habits, the humble CronJob becomes one of the most dependable tools in the whole platform.