-
Notifications
You must be signed in to change notification settings - Fork 64
app yaml
ludoch edited this page Apr 15, 2026
·
2 revisions
You configure your App Engine app's settings in the app.yaml configuration
file. Your config file must specify at least a runtime entry.
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. To learn more about structuring multiple services in your app, see
Structuring Web Services in App Engine.
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.
The following is an example of an app.yaml file:
runtime: go126
instance_class: F2
env_variables:
BUCKET_NAME: "example-gcs-bucket"
handlers:
- url: /stylesheets
static_dir: stylesheets
- url: /(.*\.(gif|png|jpg))$
static_files: static/\1
upload: static/.*\.(gif|png|jpg)$
- url: /.*
script: autoEach service's folder must contain an app.yaml file and one or more Go source
files that include the package main statement at the beginning.
runtime: java25
instance_class: F2
env_variables:
BUCKET_NAME: "example-gcs-bucket"
handlers:
- url: /stylesheets
static_dir: stylesheets
- url: /.*
secure: always
redirect_http_response_code: 301
script: autoruntime: nodejs24
instance_class: F2
env_variables:
BUCKET_NAME: "example-gcs-bucket"
handlers:
- url: /stylesheets
static_dir: stylesheets
- url: /.*
secure: always
redirect_http_response_code: 301
script: autoruntime: php85
handlers:
# Serve a directory as a static resource.
- url: /stylesheets
static_dir: stylesheets
# Serve images as static resources.
- url: /(.+\.(gif|png|jpg))$
static_files: \1
upload: .+\.(gif|png|jpg)$
# Serve your app through a front controller at index.php or public/index.php.
- url: .*
script: autoIn this example, App Engine serves files with extension of gif, png, or
jpg as static resources. The application code reads the configured files at
runtime.
runtime: ruby40
instance_class: F2
env_variables:
BUCKET_NAME: "example-gcs-bucket"
handlers:
- url: /stylesheets
static_dir: stylesheets
- url: /(.*\.(gif|png|jpg))$
static_files: static/\1
upload: static/.*\.(gif|png|jpg)$
- url: /.*
script: autoruntime: python314
instance_class: F2
env_variables:
BUCKET_NAME: "example-gcs-bucket"
handlers:
# Matches requests to /images/... to files in static/images/...
- url: /images
static_dir: static/images
- url: /.*
secure: always
redirect_http_response_code: 301
script: autoThe following table provides YAML examples of available fields in an app.yaml
file:
<tr id="app_engine_apis">
<td>
`app_engine_apis`
</td>
<td>
Optional. If you want to use the
<a href="/appengine/docs/standard/go/services/access">App Engine legacy bundled services for second-generation runtimes</a>,
set this field to `true`.
Optional. If you want to use the
<a href="/appengine/docs/standard/php-gen2/services/access">App Engine legacy bundled services for second-generation runtimes</a>,
set this field to `true`.
Optional. If you want to use the
<a href="/appengine/docs/standard/python3/services/access">App Engine legacy bundled services for second-generation runtimes</a>,
set this field to `true`.
</td>
</tr>
<tr id="build_environment_variables">
<td id="handlers_build_environment_variables">
<a id="app_yaml_Defining_build_environment_variables"></a>
`build_env_variables`
</td>
<td>
Optional. If you are using a runtime that supports
<a href="/docs/buildpacks/overview">{{buildpacks_name}}</a>, you
can define build environment variables in your
`app.yaml` file.
To learn more, see <a
href="/appengine/docs/standard/testing-and-deploying-your-app#build-env-vars"> Using build environment variables.
| Element | Description |
|---|---|
default_expiration |
Go example: runtime: go126
default_expiration: "4d 5h"
handlers:
# ...Node.js example: runtime: nodejs24
default_expiration: "4d 5h"
handlers:
# ...PHP example: runtime: php85
default_expiration: "4d 5h"
handlers:
# ...Python example: runtime: python314
default_expiration: "4d 5h"
handlers:
# ...env_variables:
MY_VAR: "my value"env_variables:
MY_VAR: "my value"env_variables:
MY_VAR: "my value"echo getenv('MY_VAR');echo $_SERVER['MY_VAR'];env_variables:
DJANGO_SETTINGS_MODULE: "myapp.settings"
url: .*
script: automyapp/
├── app.yaml
├── go.mod
├── cmd
│ └── web
│ └── main.go
└── pkg
└── users
└── users.gomain: ./cmd/webmain: example.com/myapp/cmd/webruntime: go126runtime: java25runtime: nodejs24runtime: php85runtime: ruby40runtime: python314service: service-name |
| `service_account` |
service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID]. |
| `vpc_access_connector` |
"projects/*PROJECT_ID*/locations/*REGION*/connectors/*CONNECTOR_NAME*"vpc_access_connector:
name: "projects/*PROJECT_ID*/locations/*REGION*/connectors/*CONNECTOR_NAME*"
egress_setting: all-traffic |
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 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 static files, static directories, scripts in runtimes other
than Node.js, and other settings.
<tr id="handlers_auth_fail_action">
<td>`auth_fail_action`</td>
<td>
To use this element,
`app_engine_apis` must be set to `true`.
Optional.
Describes the action taken when the `login` element is
specified for a handler and the user is not logged in. Has two
possible values:
<dl>
<dt id="handlers_auth_fail_action_redirect">`redirect`</dt>
<dd>
Default. The user is redirected to the Google sign-in page, or
`/_ah/login_required` if OpenID authentication is used.
The user is redirected back to the application URL after signing in
or creating an account.
</dd>
<dt id="handlers_auth_fail_action_unauthorized">
`unauthorized`
</dt>
<dd>
The request is rejected with an `HTTP 401` status code
and an error message.
</dd>
</dl>
If an application needs different behavior, the application itself can
implement the handling of user logins. For example, requiring a login
for the `/profile/` directory or an administrator login for
the `/admin/` directory. See <a
href="/appengine/docs/standard/authenticating-users">the Users
API</a> for more information.
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 `auth_fail_action: unauthorized` to
the handler's configuration.
</td>
</tr>
<tr id="handlers_expiration">
<td>
<a id="app_yaml_Static_cache_expiration"></a>
`expiration`
</td>
<td>
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 <a
href="/appengine/docs/standard/how-requests-are-handled#static_cache_expiration">Cache
expiration</a> for more details.
</td>
</tr>
<tr id="handlers_http_headers">
<td>`http_headers`</td>
<td>
Optional. You can set <a
href="https://wikipedia.org/wiki/List_of_HTTP_header_fields">HTTP
headers</a> 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,
see <a href="/appengine/docs/standard/how-requests-are-handled#caching_static_content">Caching
static content</a>.
For more information about App Engine specific headers, see
<a href="/appengine/docs/standard/reference/request-headers">
Request headers and responses</a>.
**Example**
handlers:
- url: /images
static_dir: static/images
http_headers:
X-Foo-Header: foo
X-Bar-Header: bar value
vary: Accept-Encoding
# ... <h4>CORS Support</h4>
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`.
However, if `mygame` attempts to make a JavaScript
`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:
handlers:
- url: /images
static_dir: static/images
http_headers:
Access-Control-Allow-Origin: https://mygame.uc.r.appspot.com
# ... Tip: To allow everyone access to your assets, you can
use the wildcard `'*'`, instead of
`https://mygame.uc.r.appspot.com`.
</td>
</tr>
<tr id="handlers_login">
<td>`login`</td>
<td>
To use this element,
`app_engine_apis` must be set to `true`.
Optional.
Determines whether the URL handler requires that the user is signed
in.
This element has three possible values:
<dl>
<dt id="handlers_login_optional">`optional`</dt>
<dd>Default. Does not require that the user is signed in.</dd>
<dt id="handlers_login_required">`required`</dt>
<dd>
If the user has signed in, the handler proceeds normally. Otherwise,
the action given in <a
href="#handlers_auth_fail_action">`auth_fail_action`</a>
is taken.
</dd>
<dt id="handlers_login_admin">`admin`</dt>
<dd>
As with `required`, performs <a
href="#handlers_auth_fail_action">`auth_fail_action`</a>
if the user is not signed in. In addition, if the user is not an
administrator for the application, they are given an error message
regardless of the <a
href="#handlers_auth_fail_action">`auth_fail_action`</a>
setting. If the user is an administrator, the handler proceeds.
</dd>
</dl>
When a URL handler with a `login` setting other than
`optional` matches a URL, the handler first checks whether
the user has signed in to the application using its <a
href="/appengine/docs/standard/users/#Authentication_options">
authentication option</a>. If not, by default, the user is redirected
to the sign-in page. You can also use <a
href="#handlers_auth_fail_action">`auth_fail_action`</a> to
configure the app to simply reject requests for a handler from users
who are not properly authenticated, instead of redirecting the user to
the sign-in page.
Note: the `admin` login restriction is also satisfied for
internal requests for which App Engine sets appropriate
`X-Appengine` special headers. For example,
`cron` scheduled tasks satisfy the `admin`
restriction, because App Engine sets an HTTP header
`X-Appengine-Cron: true` on the respective requests.
However, the requests would **not** satisfy the
`required` login restriction, because cron scheduled tasks
are not run as any user.
</td>
</tr>
<tr id="handlers_mime_type">
<td>`mime_type`</td>
<td>
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 <a
href="http://www.iana.org/assignments/media-types/" target="_blank"
class="external">the IANA MIME Media Types website</a>.
</td>
</tr>
<tr id="handlers_redirect_http_response_code">
<td>`redirect_http_response_code`</td>
<td>
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
possible values:
<dl>
<dt id="handlers_redirect_http_response_code_301">
`301`
</dt>
<dd>Moved Permanently response code.</dd>
<dt id="handlers_redirect_http_response_code_302">
`302`
</dt>
<dd>
Found response code.
</dd>
<dt id="handlers_redirect_http_response_code_303">
`303`
</dt>
<dd>
See Other response code.
</dd>
<dt id="handlers_redirect_http_response_code_307">
`307`
</dt>
<dd>
Temporary Redirect response code.
</dd>
</dl>
Go example:
handlers:
- url: /youraccount/.*
script: auto
secure: always
redirect_http_response_code: 301PHP example:
handlers:
- url: /youraccount/.*
script: auto
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.
</td>
</tr>
<tr id="handlers_script">
<td>`script`</td>
<td>
Optional.
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.
handlers:
- url: /images
static_dir: static/images
- url: /.*
secure: always
redirect_http_response_code: 301
script: autohandlers:
- url: /images
static_dir: static/images
- url: /.*
secure: always
redirect_http_response_code: 301
script: autohandlers:
- url: /images
static_dir: static/images
- url: /.*
script: auto </td>
</tr>
<tr id="handlers_secure">
<td>`secure`</td>
<td>
Optional. Any URL handler can use the `secure` setting,
including static file handlers. The `secure` element has the following
possible values:
<dl>
<dt id="handlers_secure_optional">`optional`</dt>
<dd>
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
handler.
</dd>
<dt id="handlers_secure_never">`never`</dt>
<dd>
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.
</dd>
<dt id="handlers_secure_always">`always`</dt>
<dd>
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.
</dd>
</dl>
Go example
handlers:
- url: /youraccount/.*
script: auto
secure: alwaysNode.js example
handlers:
- url: /youraccount/.*
secure: always
script: autoPHP example
handlers:
- url: /youraccount/.*
script: auto
secure: alwaysPython example
handlers:
- url: /youraccount/.*
secure: always
script: auto To <a
href="/appengine/docs/standard/how-requests-are-routed">
target a specific version of your app using the REGION_ID.r.appspot.com
domain, you replace the periods that would usually separate the
subdomain components of the URL with the string "-dot-",
for example:
https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com
To use custom domains with HTTPS, you must first <a
href="/appengine/docs/standard/securing-custom-domains-with-ssl"> 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.
</td>
</tr>
<tr id="handlers_static_dir">
<td>
<a id="app_yaml_Static_directory_handlers"></a>
`static_dir`
</td>
<td>
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.
**Example:**
handlers:
# All URLs beginning with /stylesheets are treated as paths to
# static files in the stylesheets/ directory.
- url: /stylesheets
static_dir: stylesheets
# ... </td>
</tr>
<tr id="handlers_static_files">
<td>
`static_files`
</td>
<td>
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.
**Example:**
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)$
# ... Static files cannot be the same as application code files.
</td>
</tr>
<tr id="handlers_upload">
<td>`upload`</td>
<td>
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:
`archives/(.*)/items/(.*)`
</td>
</tr>
<tr id="handlers_url">
<td>`url`</td>
<td>
Required element under `handlers`. The URL pattern, as a
regular expression that can contain groupings. For example,
`/profile/(.*)/(.*)` would match the URL
`/profile/edit/manager` and use
`edit` and `manager` as the first and second
groupings.
The URL pattern has some differences in behavior when used with the
following elements:
<dl>
<dt><a href="#handlers_static_dir">`static_dir`</a></dt>
<dd>
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.
</dd>
<dt><a href="#handlers_static_files">
`static_files`</a>
</dt>
<dd>
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.
</dd>
</dl>
</td>
</tr>
| Element | Description |
|---|
The elements in following table configure how your application scales. If no scaling type is specified, then automatic scaling is set by default.
To learn more about how App Engine apps scale, see Scaling types.
| Element | Description |
|---|---|
| `automatic_scaling` |
|