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.
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
Each service must have anapp.yaml
file in its root directory.
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.
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 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 Static 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 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
To use the module: service-name
Required if creating a
service.
Optional for 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
To use the
Required if creating a
service.
Optional for the service: service-name
Note: The
module: service-name |
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 threadsafe: [true | false]
Note: The |
version |
The recommended approach is to remove the
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
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. Specify the fully-qualified name of a
connector in the 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. |
auth_fail_action |
Optional.
Describes the action taken when the
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 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 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 handlers: - url: /images static_dir: static/images http_headers: X-Foo-Header: foo X-Bar-Header: bar value # ... 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 |
login |
Optional. Determines whether the URL handler requires that the user is signed in. This element has three possible values:
When a URL handler with a
Note: the |
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 |
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:
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
This element enables basic scaling of instance classes B1 and higher, can contain the following elements:
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
This element enables manual scaling of instance classes B1 and higher, and can contain the following element:
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.