Scheduling jobs with cron.yaml

The App Engine Cron Service allows you to configure regularly scheduled tasks that operate at defined times or regular intervals. These tasks are commonly known as cron jobs. These cron jobs are automatically triggered by the App Engine Cron Service. For instance, you might use this to send out a report email on a daily basis, to update some cached data every 10 minutes, or to update some summary information once an hour.

A cron job makes a scheduled HTTP GET request to the specified endpoint in the same app where the cron job is configured. The handler for that endpoint executes the logic when it is called.

The App Engine Cron Service cannot be used to call web endpoints outside the App Engine host app. It cannot be used to call App Engine endpoints from other apps besides the host app.

Cron job requests are subject to the same limits as other HTTP requests . Free applications can have up to 20 scheduled tasks. Paid applications can have up to 250 scheduled tasks.

To deploy or update schedules, your account requires one of the following Identity and Access Management roles:

Owner
Editor
Cloud Scheduler Admin (roles/cloudscheduler.admin)

You can set the permission on the IAM page in the Google Cloud console.

About the `cron` configuration file

For all runtimes except for Java, a cron.yaml file in the root directory of your application (alongside app.yaml) configures scheduled tasks for your app.

For the Java, a cron.yaml file in the WEB-INF directory of your application (alongside apppengine-web.xml) configures scheduled tasks for your app.

The following is an example cron.yaml file:

cron:
- description: "daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
- description: "monday morning mailout"
  url: /mail/weekly
  schedule: every monday 09:00
  timezone: Australia/NSW
- description: "new daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
  target: beta

The cron.yaml file uses the YAML syntax and consists of definitions for each of your cron jobs. A job definition must have a url and a schedule. You can also optionally specify a description, timezone, target, and retry_parameters:

url

Required. The URL in your app to which you want the Cron service to send job requests.

schedule

Required. Defines the schedule of when you want the job to run, see the syntax below.

description

Optional. Describes your cron job, which is visible from within the Google Cloud console and the local development server's admin interface.

timezone

Optional. The name of the time zone, or "zoneinfo", that you want to use for your job schedule. If you don't specify a time zone, the schedule uses UTC, which is also known asGMT.

target

Optional. The name of a specific service in your app. When target is specified, the Cron service targets the job request to that service in your app. The job requests are routed to the versions in the specified service that are configured for traffic. Learn how requests are routed.

Important considerations for target:

If you have traffic splitting enabled, your job requests will not be split between the versions that you have configured:
- IP address splitting: Job requests from the Cron service are always sent from the same IP address and therefore, get routed to the same version every time.
- Cookie splitting: Job requests do not include a cookie with the request and therefore, do not get routed to any other versions.
If you use a dispatch file, your jobs can get re-routed when the same URL is also configured in the dispatch.yaml. For example, if the /tasks/hello_service2 URL is defined in both of the following cron.yaml and dispatch.yaml files, the job requests are sent to service2, even though target: service1 is specified:
cron.yaml:
```
cron:
- description: "test dispatch vs target"
  url: /tasks/hello_service2
  schedule: every 1 mins
  target: service1
```
dispatch.yaml:
```
dispatch:
- url: '*/tasks/hello_service2'
  service: service2
```

retry_parameters

Optional. Specifies to rerun failed jobs, see the syntax below.

Defining the cron job `schedule`

Cron jobs are scheduled on reoccurring intervals and are specified using a simple English-like format. You can define a schedule so that your job runs multiple times a day, or runs on specific days and months.

Sub-daily intervals

Use a sub-daily interval to run a job multiple times a day on a repetitive schedule. You can define either an end-time interval, or a start-time interval:

End-time interval: Defines the time between the "end time" of a job and when the next job starts, where the "end time" is either the time at which the job completes or times out . The Cron service runs jobs in this type of interval throughout the 24 hour day, starting one interval after the job creation/update time, and waits for the specified interval between each job.
Example: For the every 5 minutes schedule, the job is run daily using a 5-minute interval. If one instance of a job that is running on this schedule complete at 02:01, then the next job waits 5 minute and starts again at 02:06.
Start-time interval: Defines a regular time interval for the Cron service to start each job. Unlike the end-time interval, the start-time interval runs each job independent of when the prior job completes or times-out. You can set a time range within which you want your job to run, or run jobs 24 hours a day, starting at the beginning of your specified time range.
Because the start time of a job is strict, if an instance of a job runs longer than the defined time interval, then the Cron service can skip a job. An individual start time in the interval can be skipped if the prior job has not completed or times out .

Example: For the every 5 minutes from 10:00 to 14:00 schedule, the first job starts running at 10:00, and then every 5 minutes thereafter. If that first job runs for 7 minutes, then the 10:05 job is skipped, and therefore, the Cron service does not run another instance of this job until 10:10.

Custom interval

You can use a custom interval to define a schedule where your job can run once per day on one or more select days, and in one or more select months. Jobs that run on a custom schedule run year-round, only at the specific time on the select days and months.

Example: For the 1,2,3 of month 07:00 schedule, the job runs one time at 07:00 on the first three days of each month.

Important considerations for schedule:

You must decide if you want to use either a sub-daily interval or a custom interval. You cannot mix and use elements from the various interval types. The following is an example of an invalid schedule definition: schedule: every 6 hours mon,wed,fri.
Only a single instance of a job should run at any time. The Cron service is designed to provide "at least once" delivery; that is, if a job is scheduled, App Engine sends the job request at least one time. In some rare circumstances, it is possible for multiple instances of the same job to be requested, therefore, your request handler should be idempotent, and your code should ensure that there are no harmful side-effects if this occurs.

Formatting the `schedule`

To specify when your job runs, you must define the schedule element using the following syntax:

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

Choose an interval type to define your schedule element:

End-time interval

[TYPE]: Daily intervals must include the every prefix.
Example: schedule: every 12 hours
[INTERVAL_VALUE]: An integer value and the corresponding unit of time. Valid values for the unit of time:
- minutes or mins
- hours
[INTERVAL_SCOPE]: Not applicable. To set a specific start time or range within which you want your jobs to run, see the syntax for either the Start-time interval or Custom interval.

End-time interval examples

Use the following examples to help you understand how to define job schedules that use an end-time interval:

Waits 5 minutes after deployment to run the first time. After each job ends, the Cron service waits 5 minutes before running the next job:
```
schedule: every 5 minutes
```
Waits 30 minutes after deployment to run the first time. After each job ends, the Cron service waits 30 minutes before running the next job:
```
schedule: every 30 mins
```

Start-time interval

[TYPE]: Daily intervals must include the every prefix.
Example: schedule: every 12 hours
[INTERVAL_VALUE]: An integer value and the corresponding unit of time. Valid values for the unit of time:
- minutes or mins
- hours
[INTERVAL_SCOPE] Specifies a clause that corresponds with the [INTERVAL_VALUE]. You can define a custom time range or use the 24 hr synchronized option.
- Include the from [HH:MM] to [HH:MM] clause to define a specific start time and range within which you want to run jobs.
  You must specify the time values in the 24 hour format, HH:MM, where:
  - HH are integers from 00 to 23.
  - MM are integers from 00 to 59.
- Use synchronized to specify a 24 hour time range (from 00:00 to 23:59) that is evenly divided by the [INTERVAL_VALUE] value.
  Important: The [INTERVAL_VALUE] must divide 24 into an integer, otherwise the an error occurs. Valid values for [INTERVAL_VALUE] include: 1, 2, 3, 4, 6, 8, 12, or 24.

Start-time interval examples

Use the following examples to help you understand how to define job schedules that use a start-time interval:

Runs every 5 minutes from 10:00 to 14:00, every day:
```
schedule: every 5 minutes from 10:00 to 14:00
```
Runs once every hour from 08:00 to 16:00, every day:
```
schedule: every 1 hours from 08:00 to 16:00
```
Runs once every two hours, every day starting at 00:00:
```
schedule: every 2 hours synchronized
```

Custom interval

[TYPE]: Custom intervals can include the every prefix to define a repetitive interval, or you can define a specific list of days in a month:
- To define a repetitive interval you can use the every prefix.
  Examples:
```
schedule: every day 00:00
schedule: every monday 09:00
```
- To define specific days, you must use ordinal numbers. Valid values are from the 1st day of a month, through to the maximum number of days in that month, for example:
  - 1st or first
  - 2nd or second
  - 3rd or third
  - And up to: 31st or thirtyfirst
  Example:
```
schedule: 1st,3rd tuesday
schedule: 2nd,third wednesday of month 09:00
```
[INTERVAL_VALUE]: Custom intervals include a list of the specific days that you want the job to run. The list must be defined in a comma-separated list and can include either of the following values:
- The integer value of the day in the month through to a maximum of 31 days, for example:
  - 1
  - 2
  - 3
  - And up to: 31
- The name of the day in a mix of any of the following long or abbreviated values:
  - monday or mon
  - tuesday or tue
  - wednesday or wed
  - thursday or thu
  - friday or fri
  - saturday or sat
  - sunday or sun
  - Use day to specify all days of the week.
Examples:
```
schedule: 2nd monday,thu
schedule: 1,8,15,22 of month 09:00
schedule: 1st mon,wednesday,thu of sep,oct,nov 17:00
```
[INTERVAL_SCOPE]: Specifies a clause that corresponds with the specified [INTERVAL_VALUE]. Custom intervals can include the of [MONTH] clause, which specifies a single month in a year, or a comma-separated list of multiple months. You must also define a specific time for when you want the job to run, for example: of [MONTH] [HH:MM].
By default, if the of clause is excluded, the custom interval is run every month.
- [MONTH]: You must specify the months in a comma-separated list and can include a mix of the following long or abbreviated values:
  - january or jan
  - february or feb
  - march or mar
  - april or apr
  - may
  - june or jun
  - july or jul
  - august or aug
  - september or sep
  - october or oct
  - november or nov
  - december or dec
  - Use month to specify all months in the year.
- [HH:MM]: You must specify the time values in the 24 hour format, HH:MM, where:
  - HH are integers from 00 to 23.
  - MM are integers from 00 to 59.

Custom interval examples

Use the following examples to help you understand how to define job schedules that use a custom interval:

Runs every day at 00:00:
```
schedule: every day 00:00
```
Runs every Monday at 09:00:
```
schedule: every monday 09:00
```
Runs one time on the second Wednesday in March at 17:00:
```
schedule: 2nd wednesday of march 17:00
```
Runs six times in May. During the first two weeks, it runs one time on each Monday, Wednesday, and Friday at 10:00:
```
schedule: 1st,second mon,wed,fri of may 10:00
```
Runs once a week. Every seven days starting of the first day of every month, it runs once at 09:00:
```
schedule: 1,8,15,22 of month 09:00
```
Runs every other week. On the first and third Monday every month, it runs one time at 04:00:
```
schedule: 1st,third monday of month 04:00
```
Runs three times each year. On the first Monday of September, October, and November, it runs one time at 09:00:
```
schedule: 1st monday of sep,oct,nov 09:00
```
Runs one time each quarter. On the first day of January, April, July, and October, it runs one time at 00:00:
```
schedule: 1 of jan,april,july,oct 00:00
```

Specifying retries

If a cron job's request handler returns a status code that is not in the range 200–299 (inclusive) App Engine considers that job to have failed. By default, failed jobs are not retried. You can cause failed jobs to be retried by including a retry_parameters block in your configuration file.

Here is a sample cron.yaml file that contains a single cron job configured to retry up to five times with a starting backoff of 2.5 seconds that doubles each time.

cron:
- description: "retry demo"
  url: /retry
  schedule: every 10 mins
  retry_parameters:
    job_retry_limit: 5
    min_backoff_seconds: 2.5
    max_doublings: 5

Cron retries syntax

The retry parameters are described in the table below.

Element	Description
`job_retry_limit`	An integer that represents the maximum number of retry attempts for a failed cron job. The minimum value is `0`, and the maximum value is `5`. If you also specify `job_age_limit`, App Engine retries the cron job until it reaches both limits. The default value for `job_retry_limit` is `0`.
`job_age_limit`	The time limit for retrying a failed cron job, measured from when the cron job first runs. The value is a number followed by a unit of time, where the unit is `s`for seconds, `m`for minutes, `h` for hours, or `d` for days. For example, the value `5d` specifies a limit of five days after the cron job's first execution attempt. If you also specify `job_retry_limit`, App Engine retries the cron job until it reaches both limits.
`min_backoff_seconds`	The minimum number of seconds to wait before retrying a cron job after it fails.
`max_backoff_seconds`	The maximum number of seconds to wait before retrying a cron job after it fails.
`max_doublings`	The maximum number of times that the interval between failed cron job retries will be doubled before the increase becomes constant. The constant is: 2*(`max_doublings` - 1) `min_backoff`.

Validating cron requests

You might want to validate that requests to your cron URLs are coming from App Engine and not from another source. You can do so by validating an HTTP header and the source IP address for the request:

Requests from the Cron Service will contain the following HTTP header:
```
"X-Appengine-Cron": "true"
```
This and other headers are set internally by App Engine. If a client sends these headers, they are removed from the request.
App Engine issues Cron requests from the IP address 0.1.0.2. For Cron jobs created with older gcloud versions (earlier than 326.0.0), Cron requests will come from 0.1.0.1.

Note: If you define a firewall, you must set a firewall rule for IP address 0.1.0.2 or 0.1.0.1 to allow your app to receive requests from the Cron service.

For the Java runtimes, in Jetty or Tomcat, you might perform this validation in a filter.

Request timeout

The cron request timeout depends on the scaling type that is configured for your app:

Automatic scaling: Request timeout of 10 minutes.
Basic scaling and manual scaling: Request timeout of 24 hours.

For more information, see How instances are managed.

For more information on request timeouts per environment and scaling type, see Choose an App Engine environment.

Uploading cron jobs

To upload your cron jobs, you must specify the cron.yaml as a parameter to the following gcloud command:

gcloud app deploy cron.yaml

Deleting cron jobs

To delete all cron jobs, change the cron.yaml file to just contain:

cron:

Cron support in the Google Cloud console

You can check on scheduled cron jobs on the Google Cloud console Cron jobs page.

You can also visit the Logs page see when cron jobs were added or removed.