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 a cron job to send out an email report on a daily basis, or to update some cached data every 10 minutes, or refresh 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.
A cron job request is subject to the same limits as those for push task queues.
Before you begin
To deploy or update schedules, your account requires one of the following IAM roles:
You can set the permission on the IAM page in the Google Cloud console.
Creating a cron job
- Create the
cron.yamlfile in the root directory of your application (alongside
Add one or more
<cron>entries to your file and define the necessary elements for your job, including the required
<schedule>elements. Review the cron.yaml syntax and options for more details about the elements of the
The following example creates a basic cron job that runs daily:
cron: - description: "daily summary job" url: /tasks/summary target: beta schedule: every 24 hours
The target specification is optional and is the name of a service/version. If present, the target is prepended to your app's hostname, causing the job to be routed to that service/version. If no target is specified, the job will run in the versions of the
defaultservice that are configured for traffic.
Create a handler for the cron job URL. The handler should execute any tasks that you want scheduled. The handler should respond with an HTTP status code between 200 and 299 (inclusive) to indicate success. Other status codes can be returned and can be used to retry the cron job.
Testing cron jobs in the development server
The local development server doesn't automatically run your cron jobs. You can make requests directly to your cron job's URL to test your functionality. You can use your local cron or scheduled tasks interface to trigger the URLs of your jobs with curl or a similar tool.
You can use the admin interface of the local development server to
view your cron jobs at
Retrying cron jobs that fail
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 unless a 503 status code is returned, in which case it is retried every minute until it succeeds or returns a 200-299 status code.
To set failed jobs to be retried:
- Include a
retry_parametersblock in your
Choose and set the retry parameters in the
For example, this sample
cron.yamlfile contains a single cron job that is configured to retry up to five times (the default) with a starting backoff of 2.5 seconds that doubles each time.
cron: - description: "retry demo" url: /retry schedule: every 10 mins retry_parameters: min_backoff_seconds: 2.5 max_doublings: 5
Deploying cron jobs
To deploy the cron jobs specified in your
cron.yaml configuration file,
run the following command:
gcloud app deploy cron.yaml
Deleting all cron jobs
To delete all cron jobs:
Edit the contents of the
cron.yamlfile to App Engine.
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
An example might look like this in
For more information see how to require login or admin status in the app.yaml reference.
runtime: php55 api_version: 1 handlers: - url: /report/weekly script: weekly.php login: admin
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 header is set internally by 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.
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
Calling Google Cloud Endpoints
You cannot specify a Google Cloud Endpoint in
url field of a cron job.
If you want your cron job to call a Google Cloud Endpoint,
issue a request to a target that is served by a handler in
your app, and call the endpoint class and method from the handler code.
Viewing cron jobs in the Google Cloud console
You can view scheduled cron jobs in Cloud Scheduler's App Engine Cron Jobs tab.
You can also view logs to see when cron jobs were added or removed.
See detailed information about defining cron jobs in the cron.yaml Reference.