Region ID
The REGION_ID is an abbreviated code that Google assigns
based on the region you select when you create your app. The code does not
correspond to a country or province, even though some region IDs may appear
similar to commonly used country and province codes. For apps created after
February 2020, REGION_ID.r is included in
App Engine URLs. For existing apps created before this date, the
region ID is optional in the URL.
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 |
The recommended approach is to remove the
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
At this time, App Engine has one version of the
|
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:
|
builtins |
Optional.
The Python 2 SDK includes a number of built-in handlers for
common application functions. The This field is deprecated in the Python 3 runtime. The following built-in handlers are available for your use:
builtins: - deferred: on - appstats: on
The builtins: - name: on Is equivalent to: includes: - $PYTHON_LIB/google/appengine/ext/builtins/name/
When you use
For example, consider the following handlers: - url: /.* script: main.app builtins: - appstats: on The resulting list of handlers is: [/_ah/stats, /.*]
If the includes: - included.yaml
And the handlers: - url: /.* script: main.app builtins: - appstats: on The resultant list of handlers is now: [/.*, /_ah/stats]
The order of placement of the |
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, runtime: python27 api_version: 1 threadsafe: true default_expiration: "4d 5h" handlers: # ... For more information, see Cache expiration. |
env_variables
|
Optional.
You can define environment variables in your
Environment variables that are prefixed with
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_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. |
includes
|
Optional.
The includes: - lib/user_admin.yaml App Engine resolves the included path in the following order:
If the
Included |
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 The following inbound services are available:
inbound_services: - mail - warmup |
instance_class |
Optional. The instance class for this service. The following values are available depending on your service's scaling:
|
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 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 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 |
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
Required if creating a
service.
Optional for the service: service-name
Note: The
module: service-name |
service_account |
Optional. The service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com |
skip_files |
Optional.
The
The skip_files: - ^(.*/)?#.*#$ - ^(.*/)?.*~$ - ^(.*/)?.*\.py[co]$ - ^(.*/)?.*/RCS/.*$ - ^(.*/)?\..*$
The default pattern excludes Emacs backup files with names of the form
To extend the above regular expression list, copy and paste the above
list into your 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 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 This field is deprecated in the Python 3 runtime. threadsafe: [true | false]
Note: The |
version |
The recommended approach is to remove the
For more information about using this command, 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
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
Each version of an application retains its own copy of
|
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. For more information, see Connecting to a VPC network.
vpc_access_connector: name: "projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME" egress_setting: all-traffic |
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. |
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 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 handlers:
- url: /images
static_dir: static/images
http_headers:
X-Foo-Header: foo
X-Bar-Header: bar value
vary: Accept-Encoding
# ...
CORS SupportOne 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 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 |
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.
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 |
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
Note: just like for a Python 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:
handlers: - url: /youraccount/.* script: accounts.app login: required secure: always
The development web server does not support HTTPS connections. It
ignores the
To
target a specific version of your app using the
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
Each file in the static directory is served using the MIME type that
corresponds with its filename extension unless overridden by the
directory's
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
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
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
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 |
Required element under The URL pattern has some differences in behavior when used with the following elements:
|
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 |
|---|---|
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:
automatic_scaling: target_cpu_utilization: 0.65 min_instances: 5 max_instances: 100 min_pending_latency: 30ms 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
This element enables basic scaling of instance classes B1 and higher, can contain the following elements:
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
This element enables manual scaling of instance classes B1 and higher, and can contain the following element:
manual_scaling: instances: 5 |