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. Including
REGION_ID.r in App Engine URLs is optional for
existing apps and will soon be required for all new apps.
To ensure a smooth transition, we are slowly updating App Engine to use region IDs. If we haven't updated your Google Cloud project yet, you won't see a region ID for your app. Since the ID is optional for existing apps, you don't need to update URLs or make other changes once the region ID is available for your existing apps.
Learn more about region IDs.
You configure your App Engine app's settings in the app.yaml
file.
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.
For Go 1.12+, the app.yaml is required to contain at least a
runtime: go114 entry. For a brief overview, see
Defining Runtime
Settings.
Directory structure
Each service's folder must contain anapp.yaml file and one or more Go source
files that include the package main statement at the beginning.
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 Go 1.12+
application:
runtime: go114 # or go112 or go113 for Go 1.12 or Go 1.13 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: auto
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 |
|---|---|
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: go114 # or go112 or go113 for Go 1.12 or Go 1.13 default_expiration: "4d 5h" handlers: # ... For more information, see Cache expiration. |
entrypoint |
Optional.
Overrides the default startup behavior by executing the
|
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.
You can then get these values using Also see the list of runtime environment variables that cannot be overwritten. |
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 |
Optional. 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 Go 1.12+ app
by including an
|
instance_class |
Optional. The instance class for this service. The following values are available depending on your service's scaling:
|
main |
Optional. The path or fully qualified package name of the main package.
You must declare the path to the main package if your
myapp/
├── app.yaml
├── go.mod
├── cmd
│ └── web
│ └── main.go
└── pkg
└── users
└── users.go
Then you should use either: main: ./cmd/web or main: example.com/myapp/cmd/web |
runtime |
Required. The name of the runtime environment that is used by your app. To specify Go 1.14, use: runtime: go114Other available runtime values: go111, go112, go113
|
service |
Required if creating a
service.
Optional for the service: service-name |
Handlers element
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 scripts, static files,
static directories, and other settings.
| Element | Description |
|---|---|
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: 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 |
script |
Optional.
Specifies that requests to the specific handler should target your
app. The only accepted value for the handlers: - url: /images static_dir: static/images - url: /.* secure: always redirect_http_response_code: 301 script: auto |
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: auto secure: always
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 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)$ # ... Static files cannot be the same as application code files. |
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 |