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 will invoke a URL, using an HTTP GET request, at a given time of day. An HTTP request invoked by cron can run for up to 10 minutes, but is subject to the same limits as other HTTP requests.
Free applications can have up to 20 scheduled tasks. Paid applications can have up to 100 scheduled tasks.
- About cron.yaml
- The schedule format
- Securing URLs for cron
- Cron and app versions
- Uploading cron jobs
- Cron support in the Admin Console
- Cron support in the development server
About cron.yaml
A
cron.yaml
file in the root directory of your application (alongside
app.yaml
) configures scheduled tasks for your Go application. 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 syntax of
cron.yaml
is the YAML format. For more information about this syntax, see
the YAML website
for more information.
A
cron.yaml
file consists of a number of job definitions. A job definition must have a
url
and a
schedule
. You can also optionally specify a
description
,
timezone
, and a
target
. The description is visible in the Admin Console and the development server's admin interface.
The
url
field specifies a URL in your application that will be invoked by the Cron Service. See
Securing URLs for Cron
for more. The format of the schedule field is covered in
The Schedule Format
.
The
timezone
should be the name of a standard
zoneinfo
time zone name. If you don't specify a timezone, the schedule will be in UTC (also known as GMT).
The
target
string is prepended to your app's hostname. It is usually the name
of a module. The cron job will be routed to the default version of the named
module. Note that if the default version of the module changes, the job will run
in the new default version.
If there is no module with the name assigend to
target
, the name is assumed to
be an app version, and App Engine will attempt to route the job to that version.
See
Go Application Configuration
for more information about application versions.
If you use a dispatch file , your job may be re-routed. For example, given the following cron.yaml and dispatch.yaml files, the job will run in module2, even though its target is module1:
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
The 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
2nd,third mon,wed,thu of march 17:00
every monday 09:00
1st monday of sep,oct,nov 17:00
every day 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" as a synonym for from 00:00 to 23:59 :
every 2 hours synchronized
If you want more specific timing, 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.
Securing URLs for cron
A cron handler is just a normal handler defined in
app.yaml
. You can prevent users from accessing URLs used by scheduled tasks by restricting access to administrator accounts. Scheduled tasks can access admin-only URLs. You can restrict a URL by adding
login: admin
to the handler configuration in
app.yaml
.
An example might look like this in
app.yaml
:
application: hello-cron
version: 1
runtime: go
api_version: go1
handlers:
- url: /report/weekly
script: _go_app
login: admin
For more information see Go Application Configuration: Requiring Login or Administrator Status .
To test a cron job, sign in as an administrator and visit the URL of the handler in your browser.
Requests from the Cron Service will also 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, except for requests from logged in administrators of the application, who are allowed to set the header for testing purposes.
Google App Engine issues Cron requests from the IP address
0.1.0.1
.
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.
Uploading cron jobs
You can use
appcfg.py
to upload cron jobs and view information about the defined cron jobs. When you upload your application to App Engine using
appcfg.py update
, the Cron Service is updated with the contents of
cron.yaml
. You can update just the cron configuration without uploading the rest of the application using
appcfg.py update_cron
.
To delete all cron jobs, change the
cron.yaml
file to just contain:
cron:
You can display the parsed version of your cron jobs, including the times the jobs will run, using the
appcfg.py cron_info
command.
Note that
appcfg.py cron_info
will not correctly compute schedules if a timezone different than UTC is specified.
Cron support in the Admin Console
The Admin Console allows you to view the state of your cron jobs. Select the "Cron Jobs" link from the side menu to view the state of the jobs, including the last time the job was run and the result of the job.
You can also see when cron jobs are added or removed by selecting the "Admin Logs" page from the Admin Console menu.
Cron support in the development server
When using the Go 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.