app.yaml Reference

Region ID

The REGION_ID is a code that Google assigns based on the region you select when you create your app. Including REGION_ID.r in App Engine URLs is optional for existing apps and will soon be required for all new apps.

To ensure a smooth transition, we are slowly updating App Engine to use region IDs. If we haven't updated your Google Cloud project yet, you won't see a region ID for your app. Since the ID is optional for existing apps, you don't need to update URLs or make other changes once the region ID is available for your existing apps.

Learn more about region IDs.

You configure your App Engine app's settings in the app.yaml file. This file specifies how URL paths correspond to request handlers and static files. The app.yaml file also contains information about your app's code, such as the runtime and the latest version identifier.

Each service in your app has its own app.yaml file, which acts as a descriptor for its deployment. You must first create the app.yaml file for the default service before you can create and deploy app.yaml files for additional services within your app.

Directory structure

To learn more about structuring multiple services in your app, see Structuring Web Services in App Engine.

Example

The following is an example of an app.yaml file for a Python 2 application:

runtime: python27
api_version: 1
threadsafe: true

handlers:
- url: /
  script: home.app

- url: /index\.html
  script: home.app

- url: /stylesheets
  static_dir: stylesheets

- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$

- url: /admin/.*
  script: admin.app
  login: admin

- url: /.*
  script: not_found.app

A script: directive can contain either a file path ending in .py, which means the script uses CGI, or a Python module path, with package names separated by dots, which means the script uses WSGI.

Syntax

The syntax of app.yaml is the YAML format.

The YAML format supports comments. A line that begins with a pound (#) character is ignored:

# This is a comment.

URL and file path patterns use POSIX extended regular expression syntax, excluding collating elements and collation classes. Back-references to grouped matches (e.g. \1) are supported, as are these Perl extensions: \w \W \s \S \d \D.

Runtime and app elements

Element	Description
`application`	Warning: The `application` element in addition to using the `appcfg` tooling are now deprecated. See the following instructions to specify your application using the Cloud SDK tooling such as the `gcloud` command line. The recommended approach is to remove the `application` element from your `app.yaml` file and instead, use a command-line flag to specify your application ID: To use the `gcloud app deploy` command, you must specify the `--project` flag: gcloud app deploy --project [YOUR_PROJECT_ID] To use the `appcfg.py update` command, you specify the `-A` flag: appcfg.py update -A [YOUR_PROJECT_ID] For more information about using these commands, see Deploying Your App. The application ID is the Cloud Console project ID that you specified when you created the application in the Google Cloud Console.
`api_version`	Required. The version of the API in the given runtime environment that is used by your app. This field is deprecated in newer App Engine runtimes. When Google announces support for a new version of a runtime environment's API, your deployed app will continue to use the one for which it was written. To upgrade your app to a new version of the API, you change this value and then redeploy your app to App Engine. When you specify the `1` value, the latest supported runtime environment is used each time you deploy that app (currently ). At this time, App Engine has one version of the `python27` runtime environment: `1`
`auto_id_policy`	Optional. If you are setting entity identifiers automatically, you can change the method employed by setting the auto ID policy. The following are valid options: `default` Default. Uses scattered auto IDs that are large well-distributed integers that are small enough to be represented by 64-bit floats. `legacy` The legacy option will be deprecated in a future release and will eventually be removed. For more information, see the blog post announcing this change.
`builtins`	Optional. The Python 2 SDK includes a number of built-in handlers for common application functions. The `builtins` directive allows you to include specific handlers in `app.yaml`. This field is deprecated in the Python 3 runtime. The following built-in handlers are available for your use: `appstats` Enables Appstats at `/_ah/stats/`, which you can use to measure your application's performance. In order to use Appstats, you also need to install the event recorder. `deferred` Enables the deferred handler at `/_ah/queue/deferred`. This builtin allows developers to use `deferred.defer()` to simplify the creation of Task Queue tasks. Also see Background work with the deferred library. `remote_api` Enables the `remote_api` builtin at `/_ah/remote_api/`. This builtin allows remote applications with the proper credentials to access the datastore remotely. Example: builtins: - deferred: on - appstats: on The `builtins` directive is a special instance of the `includes` directive. Each `builtin` directive is equivalent, in Python, to an `includes` directive with an expanded path. For example: builtins: - name: on Is equivalent to: includes: - $PYTHON_LIB/google/appengine/ext/builtins/name/ When you use `builtins` in your `app.yaml` file, any handlers that are defined by in the built-in `include.yaml` file will supersede any handlers that you define in your `app.yaml` file. However, if you include a file that then uses `builtins` or `includes`, the handlers are added by order of the include hierarchy. In other words, the handlers of the "parent" include are added before the builtins of the "child" includes, and so on. For example, consider the following `app.yaml`, which uses the built-in `appstats` handlers: handlers: - url: /.* script: main.app builtins: - appstats: on The resulting list of handlers is: [/_ah/stats, /.] If the `app.yaml` uses an `includes` directive: includes: - included.yaml And the `included.yaml` file uses `builtins`: handlers: - url: /. script: main.app builtins: - appstats: on The resultant list of handlers is now: [/.*, /_ah/stats] The order of placement of the `builtins` clause in a `.yaml` file doesn't change the behavior.
`default_expiration`	Optional. Sets a global default cache period for all static file handlers for an application. You can also configure a cache duration for specific static file handlers. The value is a string of numbers and units, separated by spaces, where units can be d for days, h for hours, m for minutes, and s for seconds. For example, `"4d 5h"` sets cache expiration to 4 days and 5 hours after the file is first requested. If omitted, the production server sets the expiration to 10 minutes. Example: runtime: python27 api_version: 1 threadsafe: true default_expiration: "4d 5h" handlers: # ... For more information, see Static cache expiration.
`env_variables`	Optional. You can define environment variables in your `app.yaml` file to make them available to your app. Environment variables that are prefixed with `GAE` are reserved for system use and not allowed in the `app.yaml` file. These variables will be available in the `os.environ` dictionary: env_variables: DJANGO_SETTINGS_MODULE: "myapp.settings"
`error_handlers`	Optional. Used to configure custom error pages that are returned for different error types. This element can contain the following elements: `error_code` Optional. The `error_code` can be one of the following: `over_quota` Indicates the app has exceeded a resource quota `dos_api_denial` Indicates that the request was blocked by your app's DoS Protection configuration. `timeout` Served if a deadline is reached before there is a response from your app. The error_code is optional; if it's not specified, the given file is the default error response for your app. `file` Each file entry indicates a static file that should be served in place of the generic error response. If you specify a `file` element without a corresponding `error_code` element, the static file will be the default error page for your app. Warning: Make sure that the path to the error response file does not overlap with static file handler paths. The custom error data must be less than 10 kilobytes. Example error_handlers: - file: default_error.html - error_code: over_quota file: over_quota.html
`handlers`	Required. A list of URL patterns and descriptions of how they should be handled. App Engine can handle URLs by executing application code, or by serving static files uploaded with the code, such as images, CSS, or JavaScript. See the Handlers and sub-elements syntax
`includes`	Optional. The `includes` directive allows you to include the configuration file for any library or service throughout your application. For example, you might include a user administration library as follows: includes: - lib/user_admin.yaml App Engine resolves the included path in the following order: Absolute or relative path to the working directory. The specified path resolves to a file. Relative to the application's directory, which is also known as the basepath. The basepath and path resolve to a file. Relative to the file that included the current file. The location of the referring file and the include path resolve to the included file. If the `include` directive specifies a directory, then App Engine looks in that directory for a file called `include.yaml`. If the include directive is a file, then that specific file is included. Using `includes` retrieves only the following types of directives from the destination file (if present): `builtins` `includes` `handlers` `skip_files` Included `skip_files` patterns are added to those in the including `app.yaml`, or to the default list if there is no explicit list in `app.yaml`. Note that `skip_files` compares absolute paths.
`inbound_services`	Optional. Applications must enable those services before it can receive inbound requests. You can enable the service for a Python 2 app by including an `inbound_services` section in the `app.yaml` file. The following inbound services are available: `mail` Allows your application to receive mail. `warmup` Enables warmup requests. See Configuring Warmup Requests. Example: inbound_services: - mail - warmup
`instance_class`	Optional. The instance class for this service. The following values are available depending on your service's scaling: Automatic scaling `F1`, `F2`, `F4`, `F4_1G` Default: `F1` Optionally use the `automatic_scaling` element to change default settings for automatic scaling, such as minimum and maximum number of instances, latency, and concurrent connections. Note: If `instance_class` is set to `F2` or higher, you can optimize your instances by setting `max_concurrent_requests` to a value higher than the default value of 10. To determine the optimal value, gradually increase it and monitor the performance of your application. Basic and manual scaling `B1`, `B2`, `B4`, `B4_1G`, `B8` Default: `B2` Basic and manual instance classes require you to specify either the `basic_scaling` element or the `manual_scaling` element.
`libraries`	Optional. The Python 2.7 runtime includes some third-party libraries. Some of these are available by default; others are only available if configured. You can specify which version you want to use by specifying the `name` and `version` values. This field is deprecated in the Python 3 runtime. libraries: - name: PIL version: "1.1.7" - name: webob version: "latest" Note than when you specify `latest`, the SDK determines the latest library version at deployment time. Once deployed, the library version will not change. The only way to get a different version of the library is to deploy again. If you're developing an application that doesn't have users yet: you don't need to track new versions. But if your application is being actively used, beware: you might be surprised that your application starts using a new not-backward-compatible library version. For a list of the included third-party libraries, see Third-party Libraries. You can use additional pure-python third-party libraries by installing them into a local directory. If you are using the flexible environment, see Using Python libraries in the flexible environment.
`module`	Note: Modules are now named Services. To manage your app with the `gcloud` tool, use the service element instead. To use the `appcfg` tool, services must be declared in `app.yaml` files as modules, for example: module: service-name Warning: The `module` element in addition to using the `appcfg` tooling are now deprecated. See the following instructions to specify your application using the Cloud SDK tooling such as the `gcloud` command line. Required if creating a service. Optional for the `default` service. Each service and each version must have a name. A name can contain numbers, letters, and hyphens. Combined length of service and version cannot be longer than 63 characters and cannot start or end with a hyphen. Choose a unique name for each service and each version. Don't reuse names between services and versions.
`runtime`	Required. The name of the runtime environment that is used by your app. To specify Python 2.7, use: runtime: python27
`service`	Services were formerly known as Modules. Supported only by the `gcloud` tool or Cloud SDK-based plugins, for example: `gcloud app deploy` . To use the `appcfg` tool, see module. Required if creating a service. Optional for the `default` service. Each service and each version must have a name. A name can contain numbers, letters, and hyphens. Combined length of service and version cannot be longer than 63 characters and cannot start or end with a hyphen. Choose a unique name for each service and each version. Don't reuse names between services and versions. Example: service: service-name Note: The `gcloud app deploy` command is backwards compatible and supports existing `app.yaml` files that include services declared as modules, for example: module: service-name
`skip_files`	Optional. The `skip_files` element specifies which files in the application directory are not to be uploaded to App Engine. The value is either a regular expression, or a list of regular expressions. Any filename that matches any of the regular expressions is omitted from the list of files to upload when the application is uploaded. Filenames are relative to the project directory. The `skip_files` has the following default: skip_files: - ^(./)?#.#$ - ^(./)?.~$ - ^(./)?.\.py[co]$ - ^(./)?./RCS/.$ - ^(./)?\..$ The default pattern excludes Emacs backup files with names of the form `#...#` and `...~`, `.pyc` and `.pyo` files, files in an `RCS` revision control directory, and Unix hidden files with names beginning with a dot (`.`). To extend the above regular expression list, copy and paste the above list into your `app.yaml` and add your own regular expressions. For example, to skip files whose names end in `.bak` in addition to the default patterns, add an entry like this for `skip_files`: skip_files: - ^(./)?#.#$ - ^(./)?.~$ - ^(./)?.\.py[co]$ - ^(./)?./RCS/.$ - ^(./)?\..$ - ^(./)?.\.bak$ To skip a full directory, add the directory name to the list. For example, to skip a directory named `logs`, add the following line to the previously described ones: skip_files: - logs/
`threadsafe`	Required. Configures your application to use concurrent requests. If using Python's threading library, the thread-local data, as returned by `threading.local()`, is cleared after each request. This field is deprecated in the Python 3 runtime. threadsafe: [true \| false] Note: The `threadsafe` directive is required for Python 2.7 applications. `threadsafe: true` requires that all script handlers be WSGI ones. That is, each script must be specified in a `script:` directive a using Python module path, with package names separated by dots. The last component of a `script:` directive using a Python module path is the name of a global variable in the `service:` that variable must be a WSGI app, and is usually called `app` by convention.
`version`	The recommended approach is to remove the `version` element from your `app.yaml` file and instead, use a command-line flag to specify your version ID: To use the `gcloud app deploy` command, you specify the `-v` flag: gcloud app deploy -v [YOUR_VERSION_ID] To use the `appcfg.py update` command, you specify the `-V` flag: appcfg.py update -V [YOUR_VERSION_ID] Warning: The `appcfg` tool is now deprecated. You should use the Cloud SDK tooling such as the `gcloud` command line. For more information about using these commands, see Deploying Your App. An identifier for the version of your application code that you deploy to App Engine. The version ID can contain lowercase letters, digits, and hyphens. It cannot begin with the prefix `ah-` and the names `default` and `latest` are reserved and cannot be used. Note: Version names should begin with a letter, to distinguish them from numeric instances which are always specified by a number. This avoids the ambiguity with URLs like `123-dot-my-service.uc.r.appspot.com`, which can be interpreted two ways: If version "123" exists, the target will be version "123" of the given service. If that version does not exist, the target will be instance number 123 of the default version of the service. Each version of an application retains its own copy of `app.yaml`. When an application is uploaded, the version mentioned in the `app.yaml` file being uploaded is the version that gets created or replaced by the upload. An administrator can change which version of the application is serving traffic by using the Google Cloud Console, and can also test other versions before configuring them to receive traffic.
`vpc_access_connector`	Optional. Configures your application to use a Serverless VPC Access connector, enabling the application to send requests to internal resources in your VPC network. Specify the fully-qualified name of a connector in the `name` field: vpc_access_connector: name: "projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]" For more information, see Connecting to internal resources in a VPC network.

Handlers element

The handlers element is a required element in the app.yaml configuration file. The element provides a list of URL patterns and descriptions of how they should be handled. App Engine can handle URLs by executing application code, or by serving static files uploaded with the code, such as images, CSS, or JavaScript.

Patterns are evaluated in the order they appear in the app.yaml file, from top to bottom. The first mapping whose pattern matches the URL is the one used to handle the request.

The following table lists the subelements of the handlers element that control the behavior for scripts, static files, static directories, and other settings.

Element	Description
`application_readable`	Optional. Boolean. By default, files declared in static file handlers are uploaded as static data and are only served to end users. They cannot be read by an application. If this field is set to true, the files are also uploaded as code data so your application can read them. Both uploads are charged against your code and static data storage resource quotas. This field is deprecated in newer App Engine runtimes.
`auth_fail_action`	Optional. Describes the action taken when the `login` element is specified for a handler and the user is not logged in. Has two possible values: `redirect` Default. The user is redirected to the Google sign-in page, or `/_ah/login_required` if OpenID authentication is used. The user is redirected back to the application URL after signing in or creating an account. `unauthorized` The request is rejected with an `HTTP 401` status code and an error message. If an application needs different behavior, the application itself can implement the handling of user logins. See the Users API for more information. The following example requires a login for the `/profile/` directory and an administrator login for the `/admin/` directory: handlers: - url: /profile/.* script: user_profile.app login: required - url: /admin/.* script: admin.app login: admin - url: /.* script: welcome.app You can configure a handler to refuse access to protected URLs when the user is not signed in, instead of redirecting the user to the sign-in page, by adding `auth_fail_action: unauthorized` to the handler's configuration: handlers: - url: /secure_api/.* script: api_handler.app login: required auth_fail_action: unauthorized
`expiration`	Optional. The length of time a static file served by this handler should be cached by web proxies and browsers. The value is a string of numbers and units, separated by spaces, where units can be `d` for days, `h` for hours, `m` for minutes, and `s` for seconds. For example, `"4d 5h"` sets cache expiration to 4 days and 5 hours after the file is first requested. If omitted, the application's `default_expiration` is used. See Static cache expiration for more details.
`http_headers`	Optional. You can set HTTP headers for responses of your static file or directory handlers. If you need to set HTTP headers in your `script` handlers, you should instead do that in your app's code. Example handlers: - url: /images static_dir: static/images http_headers: X-Foo-Header: foo X-Bar-Header: bar value # ... CORS Support One important use of this feature is to support cross-origin resource sharing (CORS), such as accessing files hosted by another App Engine app. For example, you could have a game app `mygame.uc.r.appspot.com` that accesses assets hosted by `myassets.uc.r.appspot.com`. However, if `mygame` attempts to make a JavaScript `XMLHttpRequest` to `myassets`, it will not succeed unless the handler for `myassets` returns an `Access-Control-Allow-Origin:` response header containing the value `http://mygame.uc.r.appspot.com`. Here is how you would make your static file handler return that required response header value: handlers: - url: /images static_dir: static/images http_headers: Access-Control-Allow-Origin: https://mygame.uc.r.appspot.com # ... Note: if you wanted to allow everyone to access your assets, you could use the wildcard `'*'`, instead of `https://mygame.uc.r.appspot.com`.
`login`	Optional. Determines whether the URL handler requires that the user is signed in. This field is not available in newer App Engine runtimes. This element has three possible values: `optional` Default. Does not require that the user is signed in. `required` If the user has signed in, the handler proceeds normally. Otherwise, the action given in `auth_fail_action` is taken. `admin` As with `required`, performs `auth_fail_action` if the user is not signed in. In addition, if the user is not an administrator for the application, they are given an error message regardless of the `auth_fail_action` setting. If the user is an administrator, the handler proceeds. When a URL handler with a `login` setting other than `optional` matches a URL, the handler first checks whether the user has signed in to the application using its authentication option. If not, by default, the user is redirected to the sign-in page. You can also use `auth_fail_action` to configure the app to simply reject requests for a handler from users who are not properly authenticated, instead of redirecting the user to the sign-in page. Note: the `admin` login restriction is also satisfied for internal requests for which App Engine sets appropriate `X-Appengine` special headers. For example, `cron` scheduled tasks satisfy the `admin` restriction, because App Engine sets an HTTP header `X-AppEngine-Cron: true` on the respective requests. However, the requests would not satisfy the `required` login restriction, because cron scheduled tasks are not run as any user.
`mime_type`	Optional. If specified, all files served by this handler will be served using the specified MIME type. If not specified, the MIME type for a file will be derived from the file's filename extension. If the same file is uploaded with multiple extensions, the resulting extension can depend on the order in which the uploads occurred. For more information about the possible MIME media types, see the IANA MIME Media Types website
`redirect_http_response_code`	Optional. `redirect_http_response_code` is used with the `secure` setting to set the HTTP response code returned when performing a redirect required by how the `secure` setting is configured. `redirect_http_response_code` element has the following possible values: `301` Moved Permanently response code. `302` Found response code. `303` See Other response code. `307` Temporary Redirect response code. Example handlers: - url: /youraccount/.* script: accounts.app login: required secure: always redirect_http_response_code: 301 When a user's request is redirected, the HTTP status code will be set to the value of the `redirect_http_response_code` parameter. If the parameter is not present, 302 will be returned.
`script`	Optional. Specifies the path to the script from the application root directory: handlers: # The root URL (/) is handled by the WSGI application named # "app" in home.py. No other URLs match this pattern. - url: / script: home.app # The URL /index.html is also handled by the home.py script. - url: /index\.html script: home.app # A regular expression can map parts of the URL to the # path of the script. - url: /browse/(books\|videos\|tools) script: \1.catalog.app # All other URLs use the WSGI application named in "app" # in not_found.py. - url: /.* script: not_found.app A `script:` directive must be a python import path, for example, `package.module.app` that points to a WSGI application. The last component of a `script:` directive using a Python module path is the name of a global variable in the module: that variable must be a WSGI app, and is usually called `app` by convention. Note: just like for a Python `import` statement, each subdirectory that is a package must contain a file named `__init__.py`. In newer App Engine runtimes, the the behavior of this field has changed.
`secure`	Optional. Any URL handler can use the `secure` setting, including script handlers and static file handlers. The `secure` element has the following possible values: `optional` Both HTTP and HTTPS requests with URLs that match the handler succeed without redirects. The application can examine the request to determine which protocol was used, and respond accordingly. This is the default when `secure` is not provided for a handler. `never` Requests for a URL that match this handler that use HTTPS are automatically redirected to the HTTP equivalent URL. When a user's HTTPS request is redirected to be an HTTP request, the query parameters are removed from the request. This prevents a user from accidentally submitting query data over a non-secure connection that was intended for a secure connection. `always` Requests for a URL that match this handler that do not use HTTPS are automatically redirected to the HTTPS URL with the same path. Query parameters are preserved for the redirect. Example handlers: - url: /youraccount/.* script: accounts.app login: required secure: always The development web server does not support HTTPS connections. It ignores the `secure` parameter, so paths intended for use with HTTPS can be tested using regular HTTP connections to the development web server. To target a specific version of your app using the `REGION_ID.r.appspot.com` domain, you replace the periods that would usually separate the subdomain components of the URL with the string "`-dot-`", for example: `https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com` To use custom domains with HTTPS, you must first activate and configure SSL certificates for that domain. Google Accounts sign-in and sign-out are always performed using a secure connection, unrelated to how the application's URLs are configured.
`static_dir`	Optional. The path to the directory containing the static files, from the application root directory. Everything after the end of the matched `url` pattern is appended to `static_dir` to form the full path to the requested file. Each file in the static directory is served using the MIME type that corresponds with its filename extension unless overridden by the directory's `mime_type` setting. All of the files in the given directory are uploaded as static files, and none of them can be run as scripts. All files in this directory are uploaded with your app as static files. App Engine stores and serves static files separately from your app's files. Static files are not available in the app's file system by default. This can be changed by setting the `application_readable` option to true. Example: handlers: # All URLs beginning with /stylesheets are treated as paths to # static files in the stylesheets/ directory. - url: /stylesheets static_dir: stylesheets # ...
`static_files`	Optional. A static file pattern handler associates a URL pattern with paths to static files uploaded with the application. The URL pattern regular expression can define regular expression groupings to be used in the construction of the file path. You can use this instead of `static_dir` to map to specific files in a directory structure without mapping the entire directory. Example: handlers: # All URLs ending in .gif .png or .jpg are treated as paths to # static files in the static/ directory. The URL pattern is a # regular expression, with a grouping that is inserted into the # path to the file. - url: /(.\.(gif\|png\|jpg))$ static_files: static/\1 upload: static/.\.(gif\|png\|jpg)$ # ... App Engine stores and serves static files separately from application files. Static files are not available in the application's file system by default. This can be changed by setting the `application_readable` option to true. Static files cannot be the same as application code files. If a static file path matches a path to a script used in a dynamic handler, the script will not be available to the dynamic handler.
`upload`	Optional. A regular expression that matches the file paths for all files that will be referenced by this handler. This is necessary because the handler cannot determine which files in your application directory correspond with the given `url` and `static_files` patterns. Static files are uploaded and handled separately from application files. The example above might use the following `upload` pattern: `archives/(.)/items/(.)`
`url`	Required element under `handlers`. The URL pattern, as a regular expression. The expression can contain groupings that can be referred to in the file path to the script with regular expression back-references. For example, `/profile/(.)/(.)` would match the URL `/profile/edit/manager` and use `edit` and `manager` as the first and second groupings. The URL pattern has some differences in behavior when used with the following elements: `static_dir` Uses a URL prefix. The regular express pattern should not contain groupings when used with the `static_dir` element. All URLs that begin with this prefix are handled by this handler, using the portion of the URL after the prefix as part of the file path. `static_files` A static file pattern handler associates a URL pattern with paths to static files uploaded with the application. The URL pattern regular expression can define regular expression groupings to be used in the construction of the file path. You can use this instead of `static_dir` to map to specific files in a directory structure without mapping the entire directory.

Scaling elements

The elements in following table configure how your application scales. To learn more about how App Engine apps scale, see Scaling types.

Element Description

Element	Description
`automatic_scaling`	Optional. Applicable only for applications that use an instance class of F1 or higher. Specify this element to change default settings for automatic scaling, such as setting minimum and maximum levels for number of instances, latency, and concurrent connections for a service. This element can contain the following elements: `max_instances` Optional. Specify a value between 0 and 2147483647, where zero disables the setting. This parameter specifies the maximum number of instances for App Engine to create for this module version. This is useful to limit the costs of a module. Important: If you use appcfg from the App Engine SDK for Python 2 to deploy, you cannot use this parameter in your `app.yaml`. Instead, set the parameter as described in Setting Autoscaling Parameters in the API Explorer, or by using the App Engine Admin API. `min_instances` Warning: For this feature to function properly, you must make sure that warmup requests are enabled and that your application handles warmup requests. Optional. The minimum number of instances for App Engine to create for this module version. These instances serve traffic when requests arrive, and continue to serve traffic even when additional instances are started up as required to handle traffic. Specify a value from 0 to 1000. You can set the parameter to the value 0 to allow scaling to 0 instances to lower costs when no requests are being served. Note that you are charged for the number of instances specified whether they are receiving traffic or not. Important: If you use appcfg from the App Engine SDK for Python 2 to deploy, you cannot use this parameter in your `app.yaml`. Instead, set the parameter as described in Setting Autoscaling Parameters in the API Explorer, or by using the App Engine Admin API. `max_idle_instances` Optional. The maximum number of idle instances that App Engine should maintain for this version. Specify a value from 1 to 1000, or `automatic`. The default value is `automatic`. Keep the following in mind: A high maximum reduces the number of idle instances more gradually when load levels return to normal after a spike. This helps your application maintain steady performance through fluctuations in request load, but also raises the number of idle instances (and consequent running costs) during such periods of heavy load. A low maximum keeps running costs lower, but can degrade performance in the face of volatile load levels. Note: When settling back to normal levels after a load spike, the number of idle instances can temporarily exceed your specified maximum. However, you will not be charged for more instances than the maximum number you've specified. `min_idle_instances` Warning: For this feature to function properly, you must make sure that warmup requests are enabled and that your application handles warmup requests. The number of instances to be kept running and ready to serve traffic. Note that you are charged for the number of instances specified whether they are receiving traffic or not. This setting only applies to the version that receives most of the traffic. Keep the following in mind: A low minimum helps keep your running costs down during idle periods, but means that fewer instances might be immediately available to respond to a sudden load spike. A high minimum allows you to prime the application for rapid spikes in request load. App Engine keeps the minimum number of instances running to serve incoming requests. You are charged for the number of instances specified, whether or not they are handling requests. If you set a minimum number of idle instances, pending latency will have less effect on your application's performance. Because App Engine keeps idle instances in reserve, it is unlikely that requests will enter the pending queue except in exceptionally high load spikes. You will need to test your application and expected traffic volume to determine the ideal number of instances to keep in reserve. `target_cpu_utilization` Optional. Specify a value between 0.5 and 0.95. The default is `0.6`. This parameter specifies the CPU usage threshold at which new instances will be started to handle traffic, enabling you to balance between performance and cost, with lower values increasing performance and increasing cost, and higher values decreasing performance but also decreasing cost. For example, a value of 0.7 means that new instances will be started after CPU usage reaches 70 percent. Important: If you use the appcfg tool from the App Engine SDK for Python 2 to deploy, you cannot use this parameter in your `app.yaml`. Instead, set the parameter as described in Setting Autoscaling Parameters in the API Explorer, or by using the App Engine Admin API. `target_throughput_utilization` Optional. Specify a value from 0.5 to 0.95. The default is `0.6`. Used with `max_concurrent_requests` to specify when a new instance is started due to concurrent requests. When the number of concurrent requests reaches a value equal to `max_concurrent_requests` times `target_throughput_utilization`, the scheduler tries to start a new instance. Important: If you use the appcfg tool from the App Engine SDK for Python 2 to deploy, you cannot use this parameter in your `app.yaml`. Instead, set the parameter as described in Setting Autoscaling Parameters in the API Explorer, or by using the App Engine Admin API. `max_concurrent_requests` Optional. The number of concurrent requests an automatic scaling instance can accept before the scheduler spawns a new instance (Default: 10, Maximum: 80). Used with `target_throughput_utilization` to specify when a new instance is started due to concurrent requests. When the number of concurrent requests reaches a value equal to `max_concurrent_requests` times `target_throughput_utilization`, the scheduler tries to start a new instance. We recommend you do not set `max_concurrent_requests` to less than 10 unless you need single threading. A value of less than 10 is likely to result in more instances being created than you need for a threadsafe app, and that may lead to unnecessary cost. If this setting is too high, you might experience increased API latency. Note that the scheduler might spawn a new instance before the actual maximum number of requests is reached. `max_pending_latency` The maximum amount of time that App Engine should allow a request to wait in the pending queue before starting additional instances to handle requests so that pending latency is reduced. When this threshold is reached, it is a signal to scale up, and results in an increase in the number of instances. The default value is `30ms`. A low maximum means App Engine will start new instances sooner for pending requests, improving performance but raising running costs. A high maximum means users might wait longer for their requests to be served (if there are pending requests and no idle instances to serve them), but your application will cost less to run. This element works together with the `min_pending_latency` element to determine when App Engine creates new instances. If pending requests are in the queue: Less than `min_pending_latency`, App Engine will not create new instances. More than `max_pending_latency`, App Engine will try to create new instance. Between the time specified by `min_pending_latency` and `max_pending_latency`, App Engine will try to reuse an existing instance. If no instances are able to process the request before `max_pending_latency`, App Engine will create a new instance. `min_pending_latency` The minimum amount of time that App Engine should allow a request to wait in the pending queue before starting a new instance to handle it. When this threshold is reached, it is a signal to scale down, and results in a decrease in the number of instances. The default value is `30ms`. A low minimum means requests must spend less time in the pending queue when all existing instances are active. This improves performance but increases the cost of running your application. A high minimum means requests will remain pending longer if all existing instances are active. This lowers running costs but increases the time users must wait for their requests to be served. Example service: my-service runtime: python27 api_version: 1 instance_class: F2 automatic_scaling: target_cpu_utilization: 0.65 min_instances: 5 max_instances: 100 min_pending_latency: 30ms # default value max_pending_latency: automatic max_concurrent_requests: 50
`basic_scaling`	Applications that use an instance class of B1 or higher must specify either this element or `manual_scaling`. This element enables basic scaling of instance classes B1 and higher, can contain the following elements: `max_instances` Required. The maximum number of instances for App Engine to create for this service version. This is useful to limit the costs of a service. `idle_timeout` Optional. The instance will be shut down this amount of time after receiving its last request. The default is 5 minutes (`5m`). Example service: my-service runtime: python27 api_version: 1 instance_class: B8 basic_scaling: max_instances: 11 idle_timeout: 10m
`manual_scaling`	Applications that use an instance class of B1 or higher must specify either this element or `basic_scaling`. This element enables manual scaling of instance classes B1 and higher, and can contain the following element: `instances` The number of instances to assign to the service at the start. Example service: my-service runtime: python27 api_version: 1 instance_class: B8 manual_scaling: instances: 5

automatic_scaling

Optional. Applicable only for applications that use an instance class of F1 or higher.

Specify this element to change default settings for automatic scaling, such as setting minimum and maximum levels for number of instances, latency, and concurrent connections for a service.

This element can contain the following elements:

max_instances

Optional. Specify a value between 0 and 2147483647, where zero disables the setting.

This parameter specifies the maximum number of instances for App Engine to create for this module version. This is useful to limit the costs of a module.

Important: If you use appcfg from the App Engine SDK for Python 2 to deploy, you cannot use this parameter in your app.yaml. Instead, set the parameter as described in Setting Autoscaling Parameters in the API Explorer, or by using the App Engine Admin API.

min_instances

Optional. The minimum number of instances for App Engine to create for this module version. These instances serve traffic when requests arrive, and continue to serve traffic even when additional instances are started up as required to handle traffic.

Specify a value from 0 to 1000. You can set the parameter to the value 0 to allow scaling to 0 instances to lower costs when no requests are being served. Note that you are charged for the number of instances specified whether they are receiving traffic or not.

max_idle_instances

Optional. The maximum number of idle instances that App Engine should maintain for this version. Specify a value from 1 to 1000, or automatic. The default value is automatic. Keep the following in mind:

A high maximum reduces the number of idle instances more gradually when load levels return to normal after a spike. This helps your application maintain steady performance through fluctuations in request load, but also raises the number of idle instances (and consequent running costs) during such periods of heavy load.
A low maximum keeps running costs lower, but can degrade performance in the face of volatile load levels.

Note: When settling back to normal levels after a load spike, the number of idle instances can temporarily exceed your specified maximum. However, you will not be charged for more instances than the maximum number you've specified.

min_idle_instances

The number of instances to be kept running and ready to serve traffic. Note that you are charged for the number of instances specified whether they are receiving traffic or not. This setting only applies to the version that receives most of the traffic. Keep the following in mind:

A low minimum helps keep your running costs down during idle periods, but means that fewer instances might be immediately available to respond to a sudden load spike.
A high minimum allows you to prime the application for rapid spikes in request load. App Engine keeps the minimum number of instances running to serve incoming requests. You are charged for the number of instances specified, whether or not they are handling requests.

If you set a minimum number of idle instances, pending latency will have less effect on your application's performance. Because App Engine keeps idle instances in reserve, it is unlikely that requests will enter the pending queue except in exceptionally high load spikes. You will need to test your application and expected traffic volume to determine the ideal number of instances to keep in reserve.

target_cpu_utilization

Optional. Specify a value between 0.5 and 0.95. The default is 0.6.

This parameter specifies the CPU usage threshold at which new instances will be started to handle traffic, enabling you to balance between performance and cost, with lower values increasing performance and increasing cost, and higher values decreasing performance but also decreasing cost. For example, a value of 0.7 means that new instances will be started after CPU usage reaches 70 percent.

Important: If you use the appcfg tool from the App Engine SDK for Python 2 to deploy, you cannot use this parameter in your app.yaml. Instead, set the parameter as described in Setting Autoscaling Parameters in the API Explorer, or by using the App Engine Admin API.

target_throughput_utilization

Optional. Specify a value from 0.5 to 0.95. The default is 0.6.

Used with max_concurrent_requests to specify when a new instance is started due to concurrent requests. When the number of concurrent requests reaches a value equal to max_concurrent_requests times target_throughput_utilization, the scheduler tries to start a new instance.

max_concurrent_requests

Optional. The number of concurrent requests an automatic scaling instance can accept before the scheduler spawns a new instance (Default: 10, Maximum: 80).

Used with target_throughput_utilization to specify when a new instance is started due to concurrent requests. When the number of concurrent requests reaches a value equal to max_concurrent_requests times target_throughput_utilization, the scheduler tries to start a new instance.

We recommend you do not set max_concurrent_requests to less than 10 unless you need single threading. A value of less than 10 is likely to result in more instances being created than you need for a threadsafe app, and that may lead to unnecessary cost.

If this setting is too high, you might experience increased API latency. Note that the scheduler might spawn a new instance before the actual maximum number of requests is reached.

max_pending_latency

The maximum amount of time that App Engine should allow a request to wait in the pending queue before starting additional instances to handle requests so that pending latency is reduced. When this threshold is reached, it is a signal to scale up, and results in an increase in the number of instances. The default value is 30ms.

A low maximum means App Engine will start new instances sooner for pending requests, improving performance but raising running costs.

A high maximum means users might wait longer for their requests to be served (if there are pending requests and no idle instances to serve them), but your application will cost less to run.

This element works together with the min_pending_latency element to determine when App Engine creates new instances. If pending requests are in the queue:

Less than min_pending_latency, App Engine will not create new instances.
More than max_pending_latency, App Engine will try to create new instance.
Between the time specified by min_pending_latency and max_pending_latency, App Engine will try to reuse an existing instance. If no instances are able to process the request before max_pending_latency, App Engine will create a new instance.

min_pending_latency

The minimum amount of time that App Engine should allow a request to wait in the pending queue before starting a new instance to handle it. When this threshold is reached, it is a signal to scale down, and results in a decrease in the number of instances. The default value is 30ms.

A low minimum means requests must spend less time in the pending queue when all existing instances are active. This improves performance but increases the cost of running your application.
A high minimum means requests will remain pending longer if all existing instances are active. This lowers running costs but increases the time users must wait for their requests to be served.

Example

service: my-service
runtime: python27
api_version: 1
instance_class: F2
automatic_scaling:
  target_cpu_utilization: 0.65
  min_instances: 5
  max_instances: 100
  min_pending_latency: 30ms  # default value
  max_pending_latency: automatic
  max_concurrent_requests: 50

basic_scaling

Applications that use an instance class of B1 or higher must specify either this element or manual_scaling.

This element enables basic scaling of instance classes B1 and higher, can contain the following elements:

max_instances: Required. The maximum number of instances for App Engine to create for this service version. This is useful to limit the costs of a service.
idle_timeout: Optional. The instance will be shut down this amount of time after receiving its last request. The default is 5 minutes (5m).

Example

service: my-service
runtime: python27
api_version: 1
instance_class: B8
basic_scaling:
  max_instances: 11
  idle_timeout: 10m

manual_scaling

Applications that use an instance class of B1 or higher must specify either this element or basic_scaling.

This element enables manual scaling of instance classes B1 and higher, and can contain the following element:

instances: The number of instances to assign to the service at the start.

Example

service: my-service
runtime: python27
api_version: 1
instance_class: B8
manual_scaling:
  instances: 5

Static cache expiration

Unless told otherwise, web proxies and browsers retain files they load from a website for a limited period of time.

You can define a global default cache period for all static file handlers for an application by including the top-level default_expiration element. You can also configure a cache duration for specific static file handlers.

The expiration time will be sent in the Cache-Control and Expires HTTP response headers, and therefore, the files are likely to be cached by the user's browser, as well as by intermediate caching proxy servers such as Internet Service Providers. After a file is transmitted with a given expiration time, there is generally no way to clear it out of intermediate caches, even if the user clears their own browser cache. Re-deploying a new version of the app will not reset any caches. Therefore, if you ever plan to modify a static file, it should have a short (less than one hour) expiration time. In most cases, the default 10-minute expiration time is appropriate.

app.yaml Reference

Region ID

Directory structure

Example

Syntax

Runtime and app elements

Handlers element

CORS Support

Scaling elements

Static cache expiration