app.yaml Configuration File

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, Node.js runtime, and environment variables.

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 Node.js, the app.yaml is required to contain at least a runtime: nodejs8 or nodejs10 entry, for a brief overview, see Defining Runtime Settings.

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 Node.js application:

runtime: nodejs10 # For Node.js 8, use runtime: nodejs8

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: 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, "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.

Example:
runtime: nodejs10

handlers:
# ...

For more information, see Static cache expiration.

env_variables

Optional. 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 app.yaml file.

Example:
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.

To retrieve and use your environment variables, you can use process.env.

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_code
Optional. The error_code can be one of the following:
over_quota
Indicates the app has exceeded a resource quota
timeout
Served if a deadline is reached before there is a response from your app.

The error_code is optional; if it's not specified, the given file is the default error response for your app.

file
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.
Example
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.

See the Handlers and sub-elements syntax

inbound_services

Optional. Applications must enable those services before it can receive inbound requests. You can enable the service for a Node.js app by including an inbound_services section in the app.yaml file.

warmup
Enables warmup requests. See Configuring Warmup Requests.
Example:
inbound_services:
  - warmup
instance_class

Optional. The instance class for this service.

The following values are available depending on your service's scaling:

Automatic scaling
F1, F2, F4, F4_1G
Default: F1 is assigned if you do not specify an instance class along with the automatic_scaling element.
Basic and manual scaling
B1, B2, B4, B4_1G, B8
Default: B2 is assigned if you do not specify an instance class along with the basic_scaling element or the manual_scaling element.

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 10, which is the default. To find the optimal value, gradually increase it and monitor the performance of your application.

runtime

Required. The name of the runtime environment that is used by your app. To specify Node.js, use nodejs8 or nodejs10.

runtime: nodejs8 or nodejs10
service

Required if creating a service. Optional for the default service. Each service and each version must have a name. A name can contain numbers, letters, and hyphens. It 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.

Example:
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 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 Static cache expiration for more details.
http_headers

Optional. You can set HTTP headers for responses of your static file or directory handlers. To set HTTP headers in Node.js, do that in your app's code.

Example
handlers:
- url: /images
  static_dir: static/images
  http_headers:
    X-Foo-Header: foo
    X-Bar-Header: bar value
  # ...

CORS Support

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.appspot.com that accesses assets hosted by myassets.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.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: http://mygame.appspot.com
  # ...

Note: if you wanted to allow everyone to access your assets, you could use the wildcard '*', instead of http://mygame.appspot.com.

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. 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:

301
Moved Permanently response code.
302
Found response code.
303
See Other response code.
307
Temporary Redirect response code.
Example

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 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 to deploy successfully.

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 static file handlers. The secure element has the following possible values:
optional
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.
never
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.
always
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.
Example
handlers:
- url: /youraccount/.*
  secure: always
  script: auto

To target a specific version of your app using the 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-[YOUR_PROJECT_ID].appspot.com

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 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
  # ...
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 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.

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 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/(.*)

url

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:

static_dir
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.
static_files
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.

Scaling elements

To learn more about how App Engine apps scale, see Scaling dynamic instances.

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 F1 unless specified otherwise.

The automatic_scaling element sets minimum and maximum levels for number of instances, latency, and concurrent connections for a service.

This element can contain the following elements:

target_cpu_utilization
Optional. Specify a value between 0.5 and 0.95. The default is 0.6.

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.

target_throughput_utilization
Optional. Specify a value from 0.5 to 0.95. The default is 0.6.

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 max_concurrent_requests times target_throughput_utilization, the scheduler starts a new instance.

max_instances
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.

min_instances
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.

max_concurrent_requests

Optional. The number of concurrent requests an automatic scaling instance can accept before the scheduler spawns a new instance (Default: 10, Maximum: 80).

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 max_concurrent_requests times target_throughput_utilization, the scheduler starts a new instance.

You might experience increased API latency if this setting is too high. Note that the scheduler might spawn a new instance before the actual maximum number of requests is reached.

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 10, which is the default. To find the optimal value, gradually increase it and monitor the performance of your application.

max_idle_instances

The maximum number of idle instances that App Engine should maintain for this version. The default value is automatic. 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 heavy load.
  • 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.

max_pending_latency

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. The default value is 30ms.

App Engine can create an instance at any time between the time specified in min_pending_latency and max_pending_latency. In other words, App Engine will not create an instance to serve a pending request before the time specified in min_pending_latency, but App Engine will create an instance after max_pending_latency is reached.

  • A low maximum means App Engine will start new instances sooner for pending requests, improving performance but raising running costs.
  • 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 run.
min_idle_instances

The number of instances to be kept running and ready to serve traffic. Note that you are charged for the number of instances specified whether they are receiving traffic or not. This setting only applies to the version that receives most of the traffic. 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. For this feature to function properly, you must make sure that warmup requests are enabled and that your application handles warmup requests.

    If you set a minimum number of idle instances, pending latency will have less effect on your application's performance. Because App Engine keeps idle instances in reserve, it is unlikely that requests will enter the pending queue except in exceptionally high load spikes. You will need to test your application and expected traffic volume to determine the ideal number of instances to keep in reserve.

min_pending_latency

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. When this threshold is reached, it is a signal to scale down, and results in a decrease in the number of instances. The default value is 30ms.

  • A low minimum means requests must spend less time in the pending queue when all existing instances are active. This improves performance but increases the cost of running your application.
  • A high minimum means requests will remain pending longer if all existing instances are active. This lowers running costs but increases the time users must wait for their requests to be served.
Example
service: my-service
runtime: nodejs10
instance_class: F2
automatic_scaling:
  max_instances: 11
  target_cpu_utilization: 0.7
basic_scaling

Optional. The basic_scaling element sets the number of instances for a service.

This element can contain the following elements:

idle_timeout
Optional. The instance will be shut down this amount of time after receiving its last request. The default is 5 minutes (5m).
max_instances
Required. The maximum number of instances for App Engine to create for this service version. This is useful to limit the costs of a service.
Example
service: my-service
runtime: nodejs10
instance_class: B8
basic_scaling:
  max_instances: 11
  idle_timeout: 10m
manual_scaling

Optional. The manual_scaling element enables manual scaling for a service and sets the number of instances for a service.

This element can contain the following elements:

instances
The number of instances to assign to the service at the start.
Example
service: my-service
runtime: nodejs10
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.

Was this page helpful? Let us know how we did:

Send feedback about...

App Engine standard environment for Node.js docs