This page explains how to run CronJobs in Google Kubernetes Engine. CronJobs are a native feature of Kubernetes; for more details, see the Kubernetes documentation about CronJobs.
Overview
You can use CronJobs to run tasks at a specific time or interval. CronJobs are a good choice for automatic tasks, such as backups, reporting, sending emails, or cleanup tasks.
CronJobs use Job objects to complete their tasks. A CronJob creates a Job object 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:
- Using
gcloud init
, if you want to be walked through setting defaults. - Using
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.
-
Run
gcloud init
and follow the directions:gcloud init
If you are using SSH on a remote server, use the
--console-only
flag to prevent the command from launching a browser:gcloud init --console-only
-
Follow the instructions to authorize
gcloud
to 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.
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 regional clusters, set your default compute region:
gcloud config set compute/region COMPUTE_REGION
- Update
gcloud
to the latest version:gcloud components update
Creating a CronJob
This CronJob prints the current time and a string once per minute:
# cronjob.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
To create this CronJob, you can save the YAML manifest to a file and apply it to the cluster using the following command:
kubectl apply -f filename
The next sections provide more details about specifying when the CronJob runs and what actually runs.
Specifying when the CronJob runs
The spec.schedule
field defines when, and how often, the CronJob runs, using
Unix standard
crontab
format. All CronJob times are in UTC. There are 5 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)
You can use the following special characters in any of the spec.schedule
fields:
?
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 instance, 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 to0/5
, it means "every fifth Sunday".
Specifying what the CronJob runs
The 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 spec.jobTemplate
, see
the Kubernetes CronJob documentation.
Specifying a deadline
The optional 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/v1beta1
kind: CronJob
metadata:
name: hello
spec:
schedule: "*/1 * * * *"
startingDeadlineSeconds: 100
jobTemplate:
spec:
...
If you do not specify a startingDeadlineSeconds
value, the CronJob never
times out. This could lead to the same CronJob running multiple times
simultaneously. To prevent this type of problem, see
Specifying a concurrency policy.
Specifying a concurrency policy
The optional 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:
Value | Meaning |
---|---|
Allow |
Concurrent Jobs are allowed. This is the default. |
Forbid |
Concurrent jobs are forbidden, and new Jobs can't start until previous ones have completed or timed out. |
Replace |
Concurrent jobs are forbidden, and old jobs are cancelled in favor of new ones. |
Suspending subsequent executions
The optional 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.successfulJobsHistoryLimit
and
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
:
kubectl describe cronjob cronjob-name
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 single last failed job. You can change or disable these defaults.
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
RunContainerError
, CrashLoopBackOff
, or another status indicating a failure.
kubectl get pods
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, use kubectl logs pod-name
:
kubectl logs hello-failed-1556555820-wrvt2
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, use kubectl delete
:
kubectl delete cronjob cronjob-name
When you delete a CronJob, the Kubernetes garbage collector deletes the associated Jobs and prevents new Jobs from starting.
What's next
- Read the Kubernetes documentation for CronJobs.
- Learn how to run a Job.