cron.xml 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.
The following is an example
<?xml version="1.0" encoding="UTF-8"?> <cronentries> <cron> <url>/recache</url> <description>Repopulate the cache every 2 minutes</description> <schedule>every 2 minutes</schedule> </cron> <cron> <url>/weeklyreport</url> <description>Mail out a weekly report</description> <schedule>every monday 08:30</schedule> <timezone>America/New_York</timezone> </cron> <cron> <url>/weeklyreport</url> <description>Mail out a weekly report</description> <schedule>every monday 08:30</schedule> <timezone>America/New_York</timezone> <target>version-2</target> </cron> </cronentries>
For an XSD describing the format, check the file
docs/cron.xsd in the SDK.
cron.xmlfile should reside in the
WEB-INFdirectory of your application alongside
cron.xmlconfigures scheduled tasks for your Java application.
Cron job definitions
||Optional. The description is visible in the GCP Console and the development server's admin interface.|
Optional. If a cron job's request handler returns a HTTP 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.
See the Cron retries section for more information.
Required. Cron schedules are specified using a simple English-like
format, such as
If there is no service with the name assigned to
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
You can use either the full weekday name or the short form (sun, mon, tue, wed, thu, fri, sat). 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
If you want more specific timing than is provided for by
synchronized, you can
specify the schedule as:
("every"|ordinal) (days) ["of" (monthspec)] (time)
- 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.
Requests from the Cron Service will contain a HTTP header:
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.
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
block in your configuration file.
cron.xmlfile that contains a single cron job configured to retry up to five times (the default) with a starting backoff of 2.5 seconds that doubles each time.
<cronentries> <cron> <url>/retry</url> <description>Retry on jsdk</description> <schedule>every 10 minutes</schedule> <retry-parameters> <min-backoff-seconds>2.5</min-backoff-seconds> <max-doublings>5</max-doublings> </retry-parameters> </cron> </cronentries>
Cron retries syntax
The retry parameters are described in the table below.
The maximum number of retry attempts for a failed cron job not to exceed
'5'. If specified with `
The time limit for retrying a failed cron job, measured from when the
cron job was first run. 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 specified with
||The minimum number of seconds to wait before retrying a cron job after it fails.|
||The maximum number of seconds to wait before retrying a cron job after it fails.|
The maximum number of times that the interval between failed cron job
retries will be doubled before the increase becomes constant. The
Cron and app versions
target parameter has been set for a job, the request is sent to the
specified version. Otherwise, Cron requests are sent to the version of your
app that is configured to receive traffic.
Cron support in the GCP Console
The GCP 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
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.
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
Free applications can have up to 20 scheduled tasks. Paid applications can have up to 250 scheduled tasks.
Deploying cron jobs
You can use the
tool to deploy your cron jobs to App Engine.
- Option 1: Upload your whole application
To upload your whole application, which also updates the Cron Service with the entries from your
cron.xmlfile, run the following command:
./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update [YOUR_APP_DIR]
- Option 2: Upload only your cron updates
To update just the cron configuration without uploading the rest of the application, run the following command:
./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update_cron [YOUR_APP_DIR]
Deleting all cron jobs
To delete all cron jobs:
Edit the contents of the `cron.xml` file to:
<?xml version="1.0" encoding="UTF-8"?> <cronentries/>
cron.xmlfile to App Engine.