Syntax

The cron.yaml file should reside in the same directory as your Go source
code.
cron.yaml configures scheduled tasks for your Go application.
For more information about the YAML format, see
the YAML website.

Cron job definitions

Element

Description

description

Optional. The description is visible in the GCP Console and
the development server's admin interface. Surround the
description value in quotes.

retry_parameters

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.

The target string is prepended to your app's hostname. It
is usually the name of a service. The cron job will be routed to the
version of the named service that is configured for traffic.

Warning: Be careful if you run a cron job with
traffic splitting enabled. The request from the cron job is always
sent from the same IP address, so if you've specified IP address
splitting, the logic will route the request to the same version every
time. If you've specified cookie splitting, the request will not be
split at all, because there is no cookie accompanying the
request.

If the service name that is specified for target is not
found, then the Cron request is routed to either the
default service, or to the version of your app that is
configured to receive traffic.For more information about routing, see
How Requests are Routed.

If you use a
dispatch file, your job might be re-routed. For example, given the
following cron.yaml and dispatch.yaml files,
the job will run in service2, even though its target is
service1:

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

url

Required.
The url field specifies a URL in your application that will
be invoked by the Cron Service. See Securing URLs for Cron for more
information.

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 at 00:00, and waits for the specified duration of time
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
00:00.

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:

Starts running every day at 00:00 and waits 5 minutes in between
each job. After each job ends, the Cron service waits 5 minutes
before running the next job:

schedule: every 5 minutes

Starts running every day at 00:00 and waits 30 minute in between
each job. 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.

[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:

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

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.

Here is a sample cron.yaml file 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.

Cron retries syntax

The retry parameters are described in the table below.

Element

Description

job_retry_limit

The maximum number of retry attempts for a failed cron job not to exceed
'5'. If specified with `job_age_limit`, App Engine retries the cron job
until both limits are reached. When omitted from the parameters, the
limit is set to '5' by default.

job_age_limit

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
job_retry_limit, App Engine retries the cron job until both limits are
reached.

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.

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.

Deadlines

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