You can configure your App Engine application'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 the
application code, such as the application ID and the latest version identifier.
Example
The following is an example of an app.yaml
file for a Python
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. For more information about this
syntax, see the YAML website.
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
.
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 GCP Console project ID that you specified when you created the application in the Google Cloud Platform 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 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
The 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.
Before an application can receive email, the
application must be configured to enable the service.
You enable the service for a Python 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 App Engine runtime environment used by this application. To specify Python, use python27. 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
|
Handlers element
The handlers
element is a required element in the app.yaml
. 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: http://mygame.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. 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 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
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 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.
The development web server does not support HTTPS connections. It
ignores the
To access the versioned appspot.com URL for your application, replace
the periods that would usually separate the subdomain components of
the URL with the string " Google Accounts sign-in and sign-out are always performed using a secure connection, unrelated to how the application's URLs are configured. To use custom domains with HTTPS, you must first activate and configure SSL for App Engine with your domain. |
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 the application as
static files. 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
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 following table lists the options for defining how you can specify that your application should scale.
Element | Description |
---|---|
automatic_scaling |
Optional. Automatic scaling is assumed by default with a default
instance class of
The This element can contain the following elements:
service: my-service runtime: python27 api_version: 1 instance_class: F2 automatic_scaling: min_idle_instances: 5 max_idle_instances: automatic # default value min_pending_latency: 30ms # default value max_pending_latency: automatic max_concurrent_requests: 50 |
basic_scaling |
Optional.
The This element 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 |
Optional.
The This element can contain the following elements:
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.