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 for each scheduled time, 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

The following is an example of a CronJob resource:

apiVersion: batch/v1beta1
kind: CronJob
metadata:
  name: pi
spec:
  schedule: "*/1 * * * *"       (1)
  concurrencyPolicy: "Replace"  (2)
  startingDeadlineSeconds: 200  (3)
  suspend: false                (4)
  successfulJobsHistoryLimit: 3 (5)
  failedJobsHistoryLimit: 1     (6)
  jobTemplate:                  (7)
    spec:
      template:
        metadata:
          labels:               (8)
            parent: "cronjobpi"
        spec:
          containers:
          - name: pi
            image: perl
            command: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
          restartPolicy: OnFailure (9)
1 The schedule field for the job is specified in cron format. In this example, the job runs every minute.
2 Optional: The concurrency policy specifies how the job controller treats concurrent jobs within a cron job. Only one of the following policies can be specified:

  • Allow allows multiple instances of the job to run concurrently. Allow is the default value.

  • Forbid prevents multiple instances of the job from running concurrently. Scheduled runs are skipped if the previous run has not finished.

  • Replace cancels a currently running instance of the job and replaces the job with a new instance.
3 Optional: The starting deadline specifies a deadline (in seconds) for starting the job if a scheduled run is missed for any reason. After the deadline, the cron job does not start the job. Missed job runs are counted as failed jobs. By default, jobs have no deadline. Be aware that when this field is set, the cron job controller counts the number of missed jobs that occur in the interval between the value for the deadline and the current moment. For example, if startingDeadlineSeconds is set to 200, the controller counts the number of missed jobs in the last 200 seconds. For more information, see the limitations for cron jobs in the Kubernetes documentation for cron job concepts.
4 Optional: The suspend field is used to prevent subsequent runs of the cron job. If set to true, then all subsequent runs are prevented from starting. By default, the value is false, and jobs are run.
5 Optional: The successful jobs history limit specifies the number of finished jobs to retain. By default, three jobs are retained.
6 Optional: The failed jobs history limit specifies the number of failed jobs to retain. By default, one job is retained.
7 The job template specifies the job to run. The field is similar to the job example.
8 Optional: The labels field specifies a label to set for jobs that are started by the cron job. In this example, jobs receive the label parent=cronjobpi.
9 Optional: The restart policy for pods that are started to run the job. The policy can be set to Always, OnFailure, or Never. By default, containers are always restarted. Be aware that this field does not apply to the job controller. See Known Limitations for details.

For more information about the CronJob specification, see the Kubernetes documentation for writing a cron job specification.

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 are 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 and 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. The default value is 3.
2 The number of failed finished jobs to retain. The default value is 1.