Creating and Configuring Cron Jobs

You use Cloud Scheduler to set up scheduled units of work, known as cron jobs, that are sent to targets on some recurring schedule, also called the job interval or frequency. You can create these jobs using either GCP Console or the gcloud command line tool.

Only a single instance of a job should be run at any time. Also, be aware that Cloud Scheduler is designed to provide "at least once" delivery; that is, if a job is scheduled, Cloud Scheduler sends the job request at least once. In some rare circumstances, it is possible for multiple instances of the same job to be requested. As a result, your request handler should be idempotent, and your code should ensure that there are no harmful side-effects if this occurs.

Creating Jobs

To create a job you can use either the console or the gcloud command line. Click on the appropriate tab:

Console

  1. Visit the Cloud Scheduler console page.

    Cloud Scheduler

  2. Click Create job.

    screenshot

  3. Supply a name for the job. It must be unique in the project. Note that you can re-use a job name in a project after you delete its associated job.

  4. Optionally, supply a brief description of the job, such as a reminder of what the job does. This description appears in the console next to the job name.

  5. Specify the frequency, or job interval, at which the job is to run, using a configuration string. For example, the string 0 */3 * * * runs the job every 3 hours. The string you supply here can be any crontab compatible string. Developers familiar with the legacy App Engine cron format can also use App Engine Cron syntax.

    For more information, see Configuring Job Schedules.

  6. From the dropdown list, choose the timezone to be used for the job frequency.

  7. Specify the target:

  8. Click Create to create and save the job. The job will now run at the specified frequency.

Gcloud

When you create a jobs using the gcloud command line, you use different commands for each target type. For sample command lines, click on the target links below:

Pub/Sub target

If you choose the Pub/Sub target,

  1. Specify the name of the topic to which the job will publish. This is a Pub/Sub topic that you have already set up in your project.

  2. Specify a message to be sent to the topic. This is sent as the data parameter within the pub/sub message. For an example that does this, see the Quickstart.

Cloud Scheduler will publish messages to this topic as a Google APIs service account. Notice that Pub/Sub target configuration does not provide options for setting retries, because Pub/Sub provides its own retry mechanism and policy.

App Engine target

If you choose the App Engine HTTP target, you must use the App Engine app associated with the current project. If you want to use some other App Engine app outside of your current project, choose HTTP as the target, not App Engine HTTP.

Set the form as follows:

  1. Specify the relative URL of the App Engine endpoint that the job will contact. If you use the default value /, then the job will use PROJECT-ID.appspot.com where PROJECT-ID is your current project ID.

  2. Specify the name of the App Engine service that is running the handler for the Cloud Scheduler job. If omitted, the default service is assumed. If you want to set it, you can find the service names in the Google Cloud Platform Console.

  3. Set the HTTP method you want to use when the job executes. The default is POST.

  4. Optionally, specify the version. If left unset, the currently serving version is used. You can find available versions in the Google Cloud Platform Console.

  5. Optionally, specify the instance. If left unset, any available instance may be used. You can find available versions in the Google Cloud Platform Console.

  6. Optionally, specify the data to be sent to the target. This data is sent in the body of the request when either the POST or PUT HTTP method is selected.

Targeted App Engine endpoints must be in the same project and can be secured with login: admin on the handlers element in the app.yaml file.

HTTP target

If you choose the HTTP target,

  1. Specify the fully qualified URL of the endpoint the job will contact.

  2. Specify the HTTP method. The default is POST.

  3. Optionally, specify the data to be sent to the target. This data is sent in the body of the request when either the POST or PUT HTTP method is selected.

  4. To create an HTTP target job that requires authentication, see Using Authentication with HTTP Targets

Targeted HTTP endpoints must be publicly accessible.

Pub/Sub target

You must use a Pub/Sub topic that you have already set up in your project. Cloud Scheduler will publish messages to this topic as a Google APIs service account.

Syntax

gcloud scheduler jobs create pubsub JOB --schedule=SCHEDULE --topic=TOPIC (--message-body=MESSAGE_BODY | --message-body-from-file=MESSAGE_BODY_FROM_FILE) [optional flags]

To use the Pub/Sub target in the command line:

  1. For JOB, Specify a name for the job. It must be unique in the project. Note that you cannot re-use a job name in a project even if you delete its associated job.

  2. Specify the schedule, also called frequency, or job interval, at which the job is to run, for example, `every 3 hours". The string you supply here can be any Crontab compatible string. Alternatively, developers familiar with legacy App Engine cron can use App Engine Cron syntax.

    For more information, see Configuring Job Schedules.

  3. Specify the name of the topic to which the job will publish.

  4. Specify a message to be sent to the topic. This is sent as the data parameter within the pub/sub message. For an example that does this, see the Quickstart.

  5. Other optional parameters are available, such as timezone, attributes, and other parameters, which are described in the gcloud command line reference

Notice that Pub/Sub target configuration does not provide options for setting retries, because Pub/Sub provides its own retry mechanism and policy.

Sample command line:

    gcloud scheduler jobs create pubsub myjob --schedule "0 */3 * * *" --topic cron-topic --message-body "Hello"

App Engine target

The App Engine HTTP target is available only for the App Engine app associated with the current project. If you want to use some other App Engine app outside of your current project, choose HTTP as the target, not App Engine HTTP.

App Engine endpoints can be secured with login: admin on the handlers element in the app.yaml file.

Syntax

gcloud scheduler jobs create app-engine JOB --schedule=SCHEDULE [optional flags]

To use the App Engine HTTP target:

  1. For JOB, Specify a name for the job. It must be unique in the project. Note that you cannot re-use a job name in a project even if you delete its associated job.

  2. Specify the schedule, also called frequency, or job interval, at which the job is to run, for example, `every 3 hours". The string you supply here can be any Crontab compatible string. Alternatively, developers familiar with legacy App Engine cron can use App Engine Cron syntax.

    For more information, see Configuring Job Schedules.

  3. Specify the relative URL of the App Engine endpoint that the job will contact. If you use the default value /, then the job will use PROJECT-ID.appspot.com where PROJECT-ID is your current project ID.

  4. Specify the name of the App Engine service that is running the handler for the Cloud Scheduler job. If omitted, the default service is assumed. If you want to set it, you can find the service names in the Google Cloud Platform Console.

  5. Optionally, set the HTTP method you want to use when the job executes. The default is POST.

  6. Optionally, specify the version. If left unset, the currently serving version is used. You can find available versions in the Google Cloud Platform Console.

  7. Optionally, specify the instance. If left unset, any available instance may be used. You can find available versions in the Google Cloud Platform Console.

  8. Optionally, specify the data to be sent to the target. This data is sent in the body of the request when either the POST or PUT HTTP method is selected.

  9. Optionally set the retry values, which specify how the App Engine job is to be retried in case of failure. In most cases, the defaults will be sufficient. For more information, see the gcloud command line reference

  10. Other optional parameters are available, such as timezone, description, and other parameters, which are described in the gcloud command line reference

Sample command line

 gcloud scheduler jobs create app-engine my-appengine-job --schedule "0 */3 * * *" --relative-url "/cron-handler"

HTTP target

You can send a request to any HTTP or HTTPS endpoint. Targeted HTTP endpoints must be publicly accessible.

Syntax

gcloud scheduler jobs create http JOB --schedule=SCHEDULE --uri=URI [optional flags]

To use the HTTP target:

  1. For JOB, Specify a name for the job. It must be unique in the project. Note that you cannot re-use a job name in a project even if you delete its associated job.

  2. Specify the schedule, also called frequency, or job interval, at which the job is to run, for example, `every 3 hours". The string you supply here can be any Crontab compatible string. Alternatively, developers familiar with legacy App Engine cron can use App Engine Cron syntax.

    For more information, see Configuring Job Schedules.

  3. Specify the fully qualified URL of the endpoint the job will contact.

  4. Optionally, Specify the HTTP method. The default is POST.

  5. Optionally, specify the data to be sent to the target. This data is sent in the body of the request when either the POST or PUT HTTP method is selected.

  6. Optionally set the retry values, which specify how the App Engine job is to be retried in case of failure. In most cases, the defaults will be sufficient. For more information, see the gcloud command line reference

  7. Other optional parameters are available, such as timezone, description, and other parameters, which are described in the gcloud command line reference

  8. To create an HTTP Target job that requires authentication, see Using Authentication with HTTP Targets

Sample command line

 gcloud scheduler jobs create http my-http-job --schedule "0 */3 * * *" --uri "http://myproject/my-url.com" --http-method GET

Deleting a Job

To delete a job:

Console

  1. Visit the Cloud Scheduler console page.

    Cloud Scheduler

  2. Select the job to be deleted.

  3. Click DELETE JOB

Gcloud

  1. Open a terminal window on the machine where you installed the Cloud SDK.

  2. Invoke the command

    gcloud scheduler jobs delete [my-job]
    

    replacing [my-job] with the name of the job to be deleted.

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

Send feedback about...

Cloud Scheduler Documentation