Creating and configuring cron jobs

Note: Make sure you have set up your environment for use with Cloud Scheduler.

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 Cloud 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.

Note: Cloud Scheduler provides headers that can help with job request deduplication, thus making the request handler idempotent. In particular, the job request can be uniquely identified using the name of the job and the time it is scheduled.

Cloud Scheduler is intended for repeated jobs. If you need to run a job only once, consider using Cloud Tasks, which can schedule a task up to 30 days in advance.

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.

   

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. Describe the schedule on which the job is to run, using a configuration string. For example, the string 0 1 * * 0 runs the job once a week at 1 am every Sunday morning. The string you supply here can be any unix-cron compatible string.

   For more information, see Configuring Job Schedules.

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

7. Specify the target:

   • HTTP

   • Pub/Sub

   • App Engine HTTP

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

Gcloud

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

• HTTP
• Pub/Sub
• App Engine HTTP

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.

OK

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.

   Note: If you are not using the default service the target URL displayed in the Google Cloud Console UI is of the form SERVICE.PROJECT-ID.r.appspot.com/*. The same URL displayed in your terminal window using the CLI is of the form https://SERVICE-dot-PROJECT-ID.r.appspot.com/. The two forms are equivalent.

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 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 Console.

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

6. Optionally, specify the data to be sent to the target. This data is sent in the body of the request as bytes 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.

OK

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 as bytes 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

Note: To set headers on your request, use either gcloud or the API directly.

Targeted HTTP endpoints must be publicly accessible.

Note: When using an HTTP target, Cloud Scheduler may report a request failed error even though the target successfully returned. This can happen when there is a mismatch between the timeout settings of the target service and that of Cloud Scheduler. See the Job description for setting the attempt_deadline field.

OK

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 unix-cron compatible string. You can also use the legacy App Engine cron syntax to describe the schedule.

For more information, see Configuring Job Schedules.

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

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.

3. 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 1 * * 0" --topic cron-topic --message-body "Hello"

OK

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 unix-cron compatible string. You can also use the legacy App Engine cron syntax to describe the schedule.

For more information, see Configuring Job Schedules.

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 Console.

3. Optionally, 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 Console.

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

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

7. 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

8. 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 1 * * 0" --relative-url "/cron-handler"

Note: If you are not using the default service the target URL returned to your terminal window is of the form https://SERVICE-dot-PROJECT-ID.r.appspot.com/. The same URL displayed in the Google Cloud Console UI is of the form SERVICE.PROJECT-ID.r.appspot.com/*. The two forms are equivalent.

OK

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 unix-cron compatible string. You can also use the legacy App Engine cron syntax to describe the schedule.

For more information, see Configuring Job Schedules.

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

2. Optionally, 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 as bytes when either the POST or PUT HTTP method is selected.

4. 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

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

6. 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 1 * * 0" --uri "http://myproject/my-url.com" --http-method GET

Note: When using an HTTP target, Cloud Scheduler may report a request failed error even though the target successfully returned. This can happen when there is a mismatch between the timeout settings of the target service and that of Cloud Scheduler. See the Job description for setting the attempt_deadline field.

OK

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.