cron.yaml Reference

The cron.yaml defines scheduled tasks for your application. This topic provides details on the options available to you. See Scheduling Tasks with Cron for how-to information related to cron jobs.

Example

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

Syntax

A cron.yaml file in the root directory of your application (alongside app.yaml ) configures scheduled tasks for your Python application.

Cron job definitions

# cron.yaml
cron:
- description: "test dispatch vs target"
  url: /tasks/hello_module2
  schedule: every 1 mins
  target: module1

# dispatch.yaml:
dispatch:
- url: '*/tasks/hello_module2'
  module: module2

Schedule format

Cron schedules are specified using a simple English-like format.

The following are examples of schedules:

every 12 hours
every 5 minutes from 10:00 to 14:00
every day 00:00
every monday 09:00
2nd,third mon,wed,thu of march 17:00
1st monday of sep,oct,nov 17:00
1 of jan,april,july,oct 00:00

If you don't need to run a recurring job at a specific time, but instead only need to run it at regular intervals, use the form:

every N (hours|mins|minutes) ["from" (time) "to" (time)]

The brackets are for illustration only, and quotes indicate a literal.

• N specifies a number.
• hours or minutes (you can also use mins) specifies the unit of time.
• time specifies a time of day, as HH:MM in 24 hour time.

By default, an interval schedule starts the next interval after the last job has completed. If a from...to clause is specified, however, the jobs are scheduled at regular intervals independent of when the last job completed. For example:

every 2 hours from 10:00 to 14:00

This schedule runs the job three times per day at 10:00, 12:00, and 14:00, regardless of how long it takes to complete.

You can use the literal synchronized to specify simple intervals, for example:

every 2 hours synchronized

where the interval used evenly divides 24 hours. If the interval used with synchronized doesn't evenly divide 24 hours, it is invalid and you'll get an error.

If you want more specific timing than is provided for by synchronized, you can specify the schedule as:

("every"|ordinal) (days) ["of" (monthspec)] (time)

Where:

• ordinal specifies a comma separated list of "1st", "first" and so forth (both forms are ok)
• days specifies a comma separated list of days of the week (for example, "mon", "tuesday", with both short and long forms being accepted); "every day" is equivalent to "every mon,tue,wed,thu,fri,sat,sun"
• monthspec specifies a comma separated list of month names (for example, "jan", "march", "sep"). If omitted, implies every month. You can also say "month" to mean every month, as in "1,8,15,22 of month 09:00".
• time specifies the time of day, as HH:MM in 24 hour time.

Cron requests

Request headers

Requests from the Cron Service will contain a HTTP header:

X-Appengine-Cron: true

The X-Appengine-Cron header is set internally by Google App Engine. If your request handler finds this header it can trust that the request is a cron request. If the header is present in an external user request to your app, it is stripped. The exception being requests from logged in administrators of the application, who are allowed to set the header for testing purposes.

Originating IP address

Google App Engine issues Cron requests from the IP address 0.1.0.1.

Cron retries

If a cron job's request handler returns a status code that is not in the range 200–299 (inclusive) App Engine considers the 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.

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

Cron retries syntax

The retry parameters are described in the table below.

Cron and app versions

If the target parameter has been set for a job, the request is sent to the specified version. Otherwise Cron requests are sent to the default version of the application.

Cron support in the Cloud Platform Console

The Cloud Platform Console Task queues page has a tab that shows the tasks that are running cron jobs.

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

Cron support in the development server

When using the Python SDK, the dev_appserver has an admin interface that allows you to view cron jobs at http://localhost:8000/cron.

The development server doesn't automatically run your cron jobs. You can use your local desktop's cron or scheduled tasks interface to trigger the URLs of your jobs with curl or a similar tool.

Deadlines

The cron timeout deadline depends on the instance class and scaling type that is configured for your app:

Automatic scaling

Timeout is about 10 minutes.

Basic scaling and manual scaling

Timeout can be up to 24 hours.

For more information, see Scaling types and instance classes

Limits

Free applications can have up to 20 scheduled tasks. Paid applications can have up to 250 scheduled tasks.