CronJobs

This page explains how to run CronJobs in Kubernetes Engine.

Overview

You can create CronJobs to perform finite, time-related tasks that run once or repeatedly at a time that you specify. CronJobs can be used for timely automatic tasks, such as backups, reporting, and sending emails.

CronJobs use Job objects to complete their tasks. CronJobs create a Job object about once per execution time of its schedule.

CronJobs are created, managed, scaled, and deleted in the same way as Jobs. For more information about Jobs, see Running a Job.

Before you begin

To prepare for this task, perform the following steps:

  • Ensure that you have installed the Cloud SDK.
  • Set your default project ID:
    gcloud config set project [PROJECT_ID]
  • Set your default compute zone:
    gcloud config set compute/zone [COMPUTE_ZONE]
  • Update all gcloud commands to the latest version:
    gcloud components update

Creating a CronJob

The following is an example of a CronJob which prints the current time and a string every minute:

config.yaml

apiVersion: batch/v1beta1
kind: CronJob
metadata:
  name: hello
spec:
  schedule: "*/1 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: hello
            image: busybox
            args:
            - /bin/sh
            - -c
            - date; echo "Hello, World!"
          restartPolicy: OnFailure

CronJobs use the required jobTemplate field, which contains a Job specification, jobTemplate: spec, for the Job(s) it creates. The Job specification contains a Pod specification, spec: template: spec, for the Pod(s) it creates to carry out the tasks you specify.

CronJobs use the required schedule field, which accepts a time in the Unix standard crontab format:

  • The first value indicates the minute (between 0 and 59)
  • The second value indicates the hour (between 0 and 23)
  • The third value indicates the day of the month (between 1 and 31)
  • The fourth value indicates the month (between 1 and 12)
  • The fifth value indicates the day of the week (between 0 and 6)

schedule also accepts * and ? as wildcard values. Combining / with ranges specifies that the task should repeat at a regular interval. In the example above, */1 * * * * indicates that the task should repeat every minute of every day of every month.

To create this CronJob, save the above manifest as config.yaml, then run the following command:

kubectl apply -f config.yaml

Alternatively, to create a CronJob without creating a manifest file, use kubectl run:

kubectl run hello --schedule="*/1 * * * *" --restart OnFailure \
--image busybox -- /bin/sh -c "date; echo Hello, World\!"

Specifying a deadline

The optional startingDeadlineSeconds field indicates the deadline (in seconds) for starting the CronJob if it misses its scheduled time for any reason. Missed CronJobs are considered failures.

To specify a deadline, add the startingDeadlineSeconds value to the CronJob's spec field in the manifest file. For example, the following manifest specifies that the CronJob has 100 seconds to begin:

apiVersion: batch/v1beta1
kind: CronJob
metadata:
  name: hello
spec:
  schedule: "*/1 * * * *"
  startingDeadlineSeconds: 100
  jobTemplate:
    spec:
    ...

If you do not specify a startingDeadlineSeconds value, no deadline is used.

Specifying a concurrency policy

The optional concurrencyPolicy field specifies how to treat concurrent executions of a Job created by the CronJob controller. You specify concurrencyPolicy in the CronJob's spec field.

concurrencyPolicy accepts the following values:

  • Allow: Allows concurrent Jobs. Default.
  • Forbid: Forbids concurrent Jobs and skips the next run if the previous run hasn't finished yet.
  • Replace: Cancels currently-running Job and replaces it with a new one.

Suspending subsequent executions

The optional suspend field, when set to true, suspends all subsequent executions. It does not suspend current executions. You specify suspend in the CronJob's spec field.

The default value of suspend is false.

Specifying history limits

The optional successfulJobsHistoryLimit and failedJobsHistoryLimit specify the number of completed and failed Jobs that should be kept. You specify these fields in the CronJob's spec field.

By default, successfulJobsHistoryLimit is set to 3 and failedJobsHistoryLimit is set to 1. Setting the value of either of these fields to 0 causes none of the Jobs to be kept after they finish.

Inspecting a CronJob

To check a CronJob's status, run the following command:

kubectl describe cronjob my-job

To view all Pod resources in your cluster, including Pods created by the CronJob which have completed, run:

kubectl get pods -a

The -a flag specifies that all resources of the type specified (in this case, Pods) should be shown.

Deleting a CronJob

To delete a CronJob, run the following command:

kubectl delete cronjob [CRON_JOB]

When you delete a CronJob, the Kubernetes garbage collector automatically deletes the associated jobs, and no new jobs are started.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Kubernetes Engine