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 PHP 5
application:
runtime: php55 api_version: 1 handlers: # Serve images as static resources. - url: /(.+\.(gif|png|jpg))$ static_files: \1 upload: .+\.(gif|png|jpg)$ application_readable: true # Serve php scripts. - url: /(.+\.php)$ script: \1
The above example will serve files with extension of gif
, png
, or jpg
as
static resources. The files have been configured to be readable by the
application code at runtime.
The example will also serve all PHP scripts. You can restrict the script handler
to root-level scripts by using the url: /([^/]+\.php)
expression. Existing
applications might find it useful to simulate Apache mod_rewrite $_GET['q']
routing.
A more extensive app.yaml
configuration is provided below:
runtime: php55 api_version: 1 handlers: - url: / script: home.php - url: /index\.html script: home.php - url: /stylesheets static_dir: stylesheets - url: /(.*\.(gif|png|jpg))$ static_files: static/\1 upload: static/.*\.(gif|png|jpg)$ - url: /admin/.* script: admin.php login: admin - url: /.* script: not_found.php
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 Google 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
|
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: php55 api_version: 1 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
env_variables: MY_VAR: "my value"where MY_VAR and my value are the name and
value of the environment variable that you want to define and each
environment variable entry is indented two spaces under the
env_variables element. Environment variables not assigned
a value default to "None" .
You can then retrieve the value of these variables by using either
echo getenv('MY_VAR');or echo $_SERVER['MY_VAR']; |
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. |
inbound_services |
Optional.
Applications must enable those services before it can receive inbound
requests. You can enable the service for a PHP 5 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:
|
module |
Note: Modules are now named Services. To manage your app with the gcloud CLI, use the service element instead. |
runtime |
Required. The name of the runtime environment that is used by your app. For example, to specify PHP 5, use: runtime: php55 |
service |
Services were formerly known as Modules.
Supported only by the gcloud CLI or gcloud CLI-based
plugins, for example:
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/ |
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
|
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.php 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: - url: /profile/(.*)/(.*) script: /employee/\2/\1.php # specify a script 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.php 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 |