Notice: Over the next few months, we're reorganizing the App Engine documentation site to make it easier to find content and better align with the rest of Google Cloud products. The same content will be available, but the navigation will now match the rest of the Cloud products.
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.
You configure your App Engine app's settings in the app.yaml
The app.yaml file also contains information about your
app's code, such as the runtime and the latest version
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
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
Optional. If you are using a runtime that supports buildpacks, you
can define build environment variables in your
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.
The command to start your application. The entrypoint starts a process
that responds to HTTP requests on the port defined by the environment
variable PORT. For more information, see
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
Served if a deadline is reached before there is a response from
The error_code is optional; if it's not specified, the given file
is the default error response for your app.
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.
The custom error data must be less than 10 kilobytes.
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,
The following values are available depending on your
F1, F2, F4, F4_1G
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
Required. The name of the runtime environment that is used by your
app. For example, to specify Ruby 3.0, use:
Required if creating a
Optional for the default
service. Each service and each version must have a name. A name can
contain numbers, letters, and hyphens. The combined length of
VERSION-dot-SERVICE-dot-PROJECT_ID, where VERSION is the name of
your version, SERVICE is the name of your service, and PROJECT_ID
is your project ID, 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.
Optional. The service_account element lets you specify a
user-managed service account as the identity for the version. The specified service account will be used when accessing other Google Cloud services and executing tasks.
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.
String literal. Specify the fully-qualified name of your
Serverless VPC Access connector in quotes:
The handlers 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
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.
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.
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. For information about which response headers influence caching,
- url: /images
X-Bar-Header: bar value
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.
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:
Note: if you wanted to allow everyone to access your assets, you could
use the wildcard '*', instead of
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.
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
Moved Permanently response code.
Found response code.
See Other response code.
Temporary Redirect response code.
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.
Specifies that requests to the specific handler should target your
app. The only accepted value for the script element
is auto because all traffic is served using the
entrypoint command. In order to use static handlers, at least one of
your handlers must contain the line script: auto
or define an entrypoint element to deploy successfully.
Optional. Any URL handler can use the secure setting,
including script handlers and
static file handlers. The secure element has the following
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
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.
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.
Google Accounts sign-in and sign-out are always performed using a
secure connection, unrelated to how the application's URLs are
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 URLs beginning with /stylesheets are treated as paths to
# static files in the stylesheets/ directory.
- url: /stylesheets
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.
# 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 cannot be the same as application code files.
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:
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
The URL pattern has some differences in behavior when used with the
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.
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.
The elements in following table configure how your application scales. To learn
more about how App Engine apps scale, see
Optional. Applicable only for applications that use an
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:
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.
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.
Optional. The maximum number of idle instances that
App Engine should maintain for this version. Specify a
value from 1 to 1000. If not specified, the default value is automatic,
which means App Engine will manage
the number of idle instances.
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
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.
Optional: The number of additional instances to be kept running
and ready to serve traffic for this version.
App Engine calculates the number of instances necessary to
serve your current application traffic based on scaling
settings such as target_cpu_utilization and
target_throughput_utilization. Setting min_idle_instances
specifies the number of instances to
run in addition to this calculated number. For example,
if App Engine calculates that 5 instances
are necessary to serve traffic, and min_idle_instances
is set to 2, App Engine will run 7 instances (5, calculated
based on traffic, plus 2 additional per min_idle_instances).
Note that you are
charged for the number of instances specified whether they are
receiving traffic or not. 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.
Optional. Specify a value between 0.5 and 0.95. The default is
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.
Optional. Specify a value from 0.5 to 0.95. The default is
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
target_throughput_utilization, the scheduler tries
to start a new instance.
Optional. The number of concurrent requests an automatic scaling
instance can accept before the scheduler spawns a new instance
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
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
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.
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.
If not specified, the default value is automatic. This means
requests can remain in the pending queue for up to 10s, the maximum
pending request time limit, before new instance starts are triggered.
A low maximum means App Engine will start new instances
sooner for pending requests, improving performance but raising
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
An optional element you can set to specify 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.
Specifying a value can lower running costs but increase the time
users must wait for their requests to be served.
For free apps, the default value is 500ms. For paid
apps, the default value is 0.
This element works together with the max_pending_latency
element to determine when App Engine creates new instances.
If pending requests are in the queue:
Less than the min_pending_latency you specify,
App Engine will not create new instances.
More than max_pending_latency, App Engine
will try to create a 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.