1. Documentation
×

Cron Jobs

Overview

A cron job builds on a regular job by allowing you to specifically schedule how the job should be run. Cron jobs are part of the Kubernetes API, which can be managed with oc commands like other object types.

A cron job creates a job object approximately once per execution time of its schedule, but there are circumstances in which it fails to create a job or two jobs might be created. Therefore, jobs must be idempotent and you must configure history limits.

Creating a Cron Job

A cron job configuration consists of the following key parts:

  • A schedule specified in cron format.

  • A job template used when creating the next job.

  • An optional deadline (in seconds) for starting the job if it misses its scheduled time for any reason. Missed jobs executions will be counted as failed ones. If not specified, there is no deadline.

  • ConcurrencyPolicy: An optional concurrency policy, specifying how to treat concurrent jobs within a cron job. Only one of the following concurrent policies may be specified. If not specified, this defaults to allowing concurrent executions.

    • Allow allows Cron Jobs to run concurrently.

    • Forbid forbids concurrent runs, skipping the next run if the previous has not finished yet.

    • Replace cancels the currently running job and replaces it with a new one.

  • An optional flag allowing the suspension of a cron job. If set to true, all subsequent executions will be suspended.

The following is an example of a CronJob resource:

apiVersion: batch/v1beta1
kind: CronJob
metadata:
  name: pi
spec:
  schedule: "*/1 * * * *"  (1)
  jobTemplate:             (2)
    spec:
      template:
        metadata:
          labels:          (3)
            parent: "cronjobpi"
        spec:
          containers:
          - name: pi
            image: perl
            command: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
          restartPolicy: OnFailure (4)

  1. Schedule for the job. In this example, the job will run every minute.

  2. Job template. This is similar to the job example.

  3. Sets a label for jobs spawned by this cron job.

  4. The restart policy of the pod. This does not apply to the job controller. See Known Issues and Limitations for details.

All cron job schedule times are based on the timezone of the master where the job is initiated.

You can also create and launch a cron job from a single command using oc run. The following command creates and launches the same cron job as specified in the previous example:

$ oc run pi --image=perl --schedule='*/1 * * * *' \
    --restart=OnFailure --labels parent="cronjobpi" \
    --command -- perl -Mbignum=bpi -wle 'print bpi(2000)'

With oc run, the --schedule option accepts schedules in cron format.

When creating a cron job, oc run only supports the Never or OnFailure restart policies (--restart).

Delete cron jobs that you no longer need:

$ oc delete cronjob/<cron_job_name>

Doing this prevents them from generating unnecessary artifacts.

Cleaning Up After a Cron Job

The .spec.successfulJobsHistoryLimit and .spec.failedJobsHistoryLimit fields are optional. These fields specify how many completed and failed jobs should be kept. By default, they are set to 3 and 1 respectively. Setting a limit to 0 corresponds to keeping none of the corresponding kind of jobs after they finish.

Cron jobs can leave behind artifact resources such as jobs or pods. As a user it is important to configure history limits so that old jobs and their pods are properly cleaned. Currently, there are two fields within cron job’s spec responsible for that:

apiVersion: batch/v1beta1
kind: CronJob
metadata:
  name: pi
spec:
  successfulJobsHistoryLimit: 3 (1)
  failedJobsHistoryLimit: 1     (2)
  schedule: "*/1 * * * *"
  jobTemplate:
    spec:
  ...
1 The number of successful finished jobs to retain (defaults to 3).
2 The number of failed finished jobs to retain (defaults to 1).