CronJobs is generally available (GA) in Google Kubernetes Engine (GKE) version 1.21 and later. This document explains how to run CronJobs in GKE. CronJobs are a built-in feature of Kubernetes. For more details, see the Kubernetes documentation about CronJobs.
CronJobs create Kubernetes Jobs on a repeating schedule. CronJobs allow you to automate regular tasks like making backups, creating reports, sending emails, or cleanup tasks.
A CronJob creates a Job each time it runs. 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
Before you start, make sure you have performed the following tasks:
- Ensure that you have enabled the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- Ensure that you have installed the Cloud SDK.
Set up default
gcloud settings using one of the following methods:
gcloud init, if you want to be walked through setting defaults.
gcloud config, to individually set your project ID, zone, and region.
Using gcloud init
If you receive the error
One of [--zone, --region] must be supplied: Please specify
location, complete this section.
gcloud initand follow the directions:
If you are using SSH on a remote server, use the
--console-onlyflag to prevent the command from launching a browser:
gcloud init --console-only
Follow the instructions to authorize
gcloudto use your Google Cloud account.
- Create a new configuration or select an existing one.
- Choose a Google Cloud project.
- Choose a default Compute Engine zone for zonal clusters or a region for regional or Autopilot clusters.
Using gcloud config
- Set your default project ID:
gcloud config set project PROJECT_ID
- If you are working with zonal clusters, set your default compute zone:
gcloud config set compute/zone COMPUTE_ZONE
- If you are working with Autopilot or regional clusters, set your default compute region:
gcloud config set compute/region COMPUTE_REGION
gcloudto the latest version:
gcloud components update
Creating a CronJob
You can create a CronJob using a manifest file. For example, the following YAML manifest prints the current time and a string once every minute, while retaining the default values for CronJob parameters:
# cronjob.yaml apiVersion: batch/v1 kind: CronJob metadata: name: hello spec: schedule: "*/1 * * * *" concurrencyPolicy: Allow startingDeadlineSeconds: 100 suspend: false successfulJobsHistoryLimit: 3 failedJobsHistoryLimit: 1 jobTemplate: spec: template: spec: containers: - name: hello image: busybox args: - /bin/sh - -c - date; echo "Hello, World!" restartPolicy: OnFailure
To create this CronJob, save the YAML manifest to a file and apply it to the cluster:
kubectl apply -f PATH_TO_FILE
PATH_TO_FILE with the path to the YAML manifest.
Configuring a CronJob
You can specify the following parameters when you create a CronJob:
- When the CronJob runs
- What the CronJob does
- The deadline for the CronJob to start
- Whether concurrent Jobs are allowed for the CronJob
- Whether new Jobs are suspended
- How many executions the CronJob saves in its history
Specifying when the CronJob runs
spec.schedule field defines when, and how often, the CronJob runs, using
format. All CronJob times are in UTC. There are five fields, separated by spaces.
These fields represent the following:
- Minutes (between 0 and 59)
- Hours (between 0 and 23)
- Day of the month (between 1 and 31)
- Month (between 1 and 12)
- Day of the week (between 0 and 6 starting on Sunday)
You can use the following special characters in any of the
?is a wildcard value that matches a single character.
*is a wildcard value that matches zero or more characters.
/allows you to specify an interval for a field. For example, if the first field (the minutes field) has a value of
*/5, it means "every 5 minutes". If the fifth field (the day-of-week field) is set to
0/5, it means "every fifth Sunday".
Specifying what the CronJob runs
spec.jobTemplate describes what the CronJob does, including its container
images, the commands the containers execute, and the restart policy for the
CronJob. For more details on what to include in the
the Kubernetes CronJob documentation.
Specifying a deadline
startingDeadlineSeconds field indicates the maximum number of
seconds the CronJob can take to start 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/v1 kind: CronJob metadata: name: hello spec: schedule: "*/1 * * * *" startingDeadlineSeconds: 100 jobTemplate: spec: ...
Specifying a concurrency policy
spec.concurrencyPolicy field specifies how to treat concurrent
executions of a Job created by the CronJob controller. If you do not set a
value, multiple concurrent Jobs are allowed by default.
concurrencyPolicy accepts the following values:
||Concurrent Jobs are allowed. This is the default.|
||Concurrent Jobs are forbidden, and new Jobs can't start until previous ones have completed or timed out.|
||Concurrent Jobs are forbidden, and old Jobs are cancelled in favor of new ones.|
Suspending subsequent executions
spec.suspend field, when set to
true, prevents new Jobs from
being run, but allows current executions to finish.
Specifying history limits
A CronJob creates a Pod each time it runs. Viewing the termination status of a CronJob's recent executions, as well as the logs of an individual Pod, are covered in Viewing CronJob history.
You can configure the number of successful and failed CronJob executions that
are saved by specifying values for
spec.failedJobsHistoryLimit. By default,
successfulJobsHistoryLimit is set
to 3 and
failedJobsHistoryLimit is set to 1.
To disable retention of data about successful or failed jobs, set the respective value to 0. However, debugging failures may be more difficult.
Inspecting a CronJob
To check a CronJob's configuration, use
kubectl describe cronjob CRONJOB_NAME
CRONJOB_NAME with the name of the CronJob to
Viewing CronJob history
A CronJob runs within a Pod. By default, Kubernetes preserves the logs for terminated Pods representing the last three successful runs of a CronJob and the most recent failed Job. You can change or disable these defaults by changing the CronJob history limits.
To view a CronJob's history, first list all Pods. Completed CronJobs are shown
with a status of
Completed, and failed Jobs have a status of
CrashLoopBackOff, or another status indicating a failure.
NAME READY STATUS RESTARTS AGE hello-1556555640-9bc5r 0/1 Completed 0 3m6s hello-1556555700-cm6wk 0/1 Completed 0 2m6s hello-1556555760-62wf5 0/1 Completed 0 66s hello-1556555820-rl8kl 0/1 Completed 0 5s hello-failed-1556555820-wrvt2 0/1 RunContainerError 1 5s
To view the logs for a specific CronJob, run the following command:
kubectl logs POD_NAME
POD_NAME with the name of the Pod you want to
The output is similar to the following:
container_linux.go:247: starting container process caused "exec: \"/in/sh\": stat /in/sh: no such file or directory"
Deleting a CronJob
To delete a CronJob, run the following command:
kubectl delete cronjob CRONJOB_NAME
When you delete a CronJob, the Kubernetes garbage collector deletes the associated Jobs and prevents new Jobs from starting.