Configuring your App with app.yaml

Note: Services were previously called "modules", and services are still declared in app.yaml files as modules, for example: module: service_name.

A Node.js App Engine application can be configured by a file named app.yaml that specifies how URL paths correspond to request handlers and static files. It also contains information about the application code, such as the application ID and the latest version identifier.

About app.yaml files

A Node.js app specifies runtime configuration, including versions and URLs, in a file named app.yaml. The following is an example of an app.yaml file for a Node.js application:

runtime: nodejs
vm: true

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.

General settings

An app.yaml file can include these general settings, note that some of them are required:

runtime: nodejs This setting is required. It is name of the App Engine language runtime used by this application. To specify Node.js, use nodejs. Other runtimes are available; refer to each languages's documentation for more info.
vm: true Select the flexible environment.
module: default Defines the service name. Every application must have one (and only one) default service, which has the name default and may be omitted. Other services must have different names.

Note: Defining a service as: service: service_name is supported only by gcloud app commands.

threadsafe: true It tells App Engine that your application can handle multiple requests simultaneously. If false, App Engine sends requests serially to a given webserver. If you wish to use concurrent requests, make sure that your application uses proper thread synchronization before you enable threadsafe

Tip: You can instead use the CLI command group gcloud app of the Cloud SDK as an alternative to the appcfg tool. With gcloud app, you can deploy and manage your apps through commands that provide equivalent functions as the appcfg tool.
Important: gcloud app defines services in the configuration files as service: service_name, which are not currently supported by the appcfg tool.

The flexible runtime environment

There are separate sections in the configuration file for specifying network settings, compute resources, and health checking behavior:

Network Settings

  - 8081
  - 8082:8083
  instance_tag: <tag-name>
  name: <network-name>

Resource Settings
  cpu: .5
  memory_gb: 1.3
  disk_size_gb: 10
Health Checks
  enable_health_check: True
  check_interval_sec: 5
  timeout_sec: 4
  unhealthy_threshold: 2
  healthy_threshold: 2
  restart_threshold: 60

Network Settings

Option Description
forwarded_ports Ports can be forwarded from the VM to your application's container. You can specify that a port forwards to the same port number (8081), or from one port to another (8082:8083). Port 8080 is forwarded by default.
instance_tag A tag with that name is assigned to each instance of the service when it is created. Tags can be useful in gcloud commands to target an action to a group of instances. For example, see the use of the --source-tags and --target-tags flags in the compute firewalls-create command.
name Every VM instance in the flexible environment is assigned to a Compute Engine network. when it is created. Use this setting to specify a network name. Give the short name, not the resource path (for example "default" rather than ""). If you do not specify a network name, instances are assigned to the project's default network (which has the name "default").

Resource Settings

These settings control the computing resources. App Engine assigns a machine type based on the amount of CPU and memory you've specified. The machine is guaranteed to have at least the level of resources you've specified, it might have more.

Option Description Default
cpu The number of cores; it can be a fraction less than one. .5 cores
memory_gb RAM, in GB 1.3 GB
disk_size_gb Size in GB. The minimum is 10GB and maximum is 10240GB. 10GB

Health Checks

Periodic health check requests are used to confirm that a VM instance has been successfully deployed, and to check that a running instance maintains a healthy status. Each health check must be answered within a specified time interval. An instance is unhealthy when it fails to respond to a specified number of consecutive health check requests. An unhealthy instance will not receive any client requests, but health checks will still be sent. If an unhealthy instance continues to fail to respond to a predetermined number of consecutive health checks, it will be restarted.

Health check requests are enabled by default, with default threshold values. You can customize VM health checking by adding an optional health check section to your configuration file:

Option Description Default
enable_health_check Enable/disable health checks. Health checks are enabled by default.
To disable health checking, set to False.
check_interval_sec Time interval between checks 5 seconds
timeout_sec Health check timeout interval 4 seconds
unhealthy_threshold An instance is unhealthy after failing this number of consecutive checks 2 checks
healthy_threshold An unhealthy instance becomes healthy again after successfully
responding to this number of consecutive checks
2 checks
restart_threshold The number of consecutive check failures that will trigger a VM restart 60 checks

Service scaling settings

The keys used to control scaling of a service depend on the type of scaling you assign to a service:

If you do not specify any scaling, then automatic scaling is selected by default.

Manual Scaling

module: my-service
runtime: nodejs
vm: true
  instances: 5

Automatic Scaling

module: my-service
runtime: nodejs
vm: true
  min_num_instances: 5
  max_num_instances: 20
  cool_down_period_sec: 120 # default value
    target_utilization: 0.5

Manual Scaling

manual_scaling Required to enable manual scaling for a service.
instances The number of instances to assign to the service at the start.

Automatic Scaling

When you use automatic scaling you must specify the minimum and maximum number of instances. The other settings are optional.

automatic_scaling Automatic scaling is assumed by default. Include this line if you are going to specify any of the automatic scaling settings.
min_num_instances Must be 1 or greater. When a service is deployed, it is given the minimum number of instances and scales according to traffic and other settings.
max_num_instances Default: 20. Specifies the maximum number of instances that each version of your app can scale up to. The maximum number of instances in your project is limited by your project's resource quota.
cool_down_period_sec The time interval between auto scaling checks. The cool-down period must be greater than or equal to 60 seconds. The default is 120 seconds.
cpu_utilization This header is required if you are going to specify the target CPU utilization.

target_utilization Target CPU utilization (default 0.5). CPU use is averaged across all running instances and is used to decide when to reduce or increase the number of instances.

Securing URLs

Google App Engine supports secure connections via HTTPS for URLs using the * domain. When a request accesses a URL using HTTPS, and that URL is configured to use HTTPS in the app.yaml file, both the request data and the response data are encrypted by the sender before they are transmitted, and decrypted by the recipient after they are received. Secure connections are useful for protecting customer data, such as contact information, passwords, and private messages.

To configure a URL to accept secure connections, to requre login, or both, you need to add an empty request handler to the configuration file. The handler includes a URL, a null script, and the secure and/or login parameters:

- url: /.*
  script: IGNORED
  secure: always

Note that:

  • The URL pattern is 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 groupings.
  • URLs that begin with /_ah/ are reserved by App Engine for features or administrative purposes. You should not use them.
  • You must provide a path for script, but it will be ignored.
  • The login setting is available only when using a compat runtime in Python, Java, or Go.

The secure key has the following possible values:

Option Description
secure: 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.
secure: never Requests for a URL that match this handler that use HTTPS are automatically redirected to the HTTP equivalent URL.
secure: 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.

When a user's HTTPS query is redirected to be an HTTP query, 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.

The development web server does not support HTTPS connections. It ignores the secure parameter, so paths intended for use with HTTPS can be tested using regular HTTP connections to the development web server.

To access the versioned URL for your application, replace the periods that would usually separate the subdomain components of the URL with the string "-dot-". For instance: https://*desired_version*-dot-*your_app_id*

Google Accounts sign-in and sign-out are always performed using a secure connection, unrelated to how the application's URLs are configured.

Defining environment variables

You can define environment variables in app.yaml to make them available to the app:

  MY_VAR: 'my value'
It is then possible to get these values using process.env.

Send feedback about...

App Engine flexible environment for Node.js docs