app.yaml Configuration File

Go Java Node.js PHP Python Ruby .NET Custom

Note: Some Java runtimes have reached end of support. You cannot re-deploy versions that use runtimes after their end of support date. We recommend that you upgrade your app to use the latest version of Java.

The app.yaml file defines your configuration settings for your runtime as well as general app, network, and other resource settings.

Do not add app.yaml to the .gcloudignore file. app.yaml might be required for deployment, and adding it to .gcloudignore will cause the deployment to fail.

Syntax

The syntax of the app.yaml file is the YAML format. The YAML format supports comments, where any line that begins with the hash symbol (#) character is ignored, for example:

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

Name	Description
build_env_variables	Optional. If you are using a runtime that supports buildpacks, you can define build environment variables in your app.yaml file. To learn more, see Using build environment variables.
runtime	Required. The name of the runtime environment that is used by your app. For example, to specify the runtime environment, use: runtime: java To specify a supported version of Java or to use the new Java runtimes, see the runtime_config setting. For more information and an example, see Java runtime and Configuring your app with app.yaml.
runtime_config	Specifies the Java version. Starting in Java version 11, you must specify the version of the operating system. runtime_config: operating_system: "ubuntu22" runtime_version: "21" operating_system: Specifies the version of the Ubuntu operating system that you want to use. Required for version 11 and later. Not supported for Java 8. See the supported Ubuntu versions and runtimes on the Java runtimes page. runtime_version: Optional for all runtime versions. Specifies the version of the Java runtime that you want to use. See the supported versions and the default values on the Java runtimes page.
env: flex	Required: Select the flexible environment.
service: service_name	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. In the flexible environment, 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. If you deploy without specifying a service name, then a new version of the default service is created. If you deploy with a service name that already exists, a new version of that service is created. If you deploy with a new service name that doesn't exist, a new service and version are created. We recommend using a unique name for each service-version combination. Note: Services were previously called "modules."
service_account	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. The service account must be provided in the following format: service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
skip_files	Optional. The skip_files element specifies which files in the application directory are not to be uploaded to App Engine. The value is either a regular expression, or a list of regular expressions. Any filename that matches any of the regular expressions is omitted from the list of files to upload when the application is uploaded. For example, to skip files whose names end in .bak, add a skip_files section like the following: skip_files: - ^.*\.bak$

Runtime-specific settings

See the Java runtime page to learn more about specifying a Java version using the runtime_config settings.

Network settings

You can specify network settings in your app.yaml configuration file, for example:

network:
  name: NETWORK_NAME
  instance_ip_mode: INSTANCE_IP_MODE
  instance_tag: TAG_NAME
  subnetwork_name: SUBNETWORK_NAME
  session_affinity: true
  forwarded_ports:
    - PORT
    - HOST_PORT:CONTAINER_PORT
    - PORT/tcp
    - HOST_PORT:CONTAINER_PORT/udp

You can use the following options when configuring network settings:

Option	Description
name	Every VM instance in the flexible environment is assigned to a Google 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 https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default). If you do not specify a network name, instances are assigned to the project's default network (which has the name default). If you want to specify a subnetwork name, you must specify a network name.
instance_ip_mode	Optional. To prevent instances from receiving an ephemeral external IP address, set to internal and enable Private Google Access. If your instance was previously deployed without this setting, or was deployed with this set to external, redeploying with it set to internal removes ephemeral external IP addresses from your instances. The internal setting has limitations. Default is external.
instance_tag	Optional. 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. If not specified, the instance is tagged with aef-INSTANCE_ID when Shared VPC is not used. If Shared VPC is used, the instance is tagged with both aef-INSTANCE_ID and aef-instance.
subnetwork_name	Optional. You can segment your network and use a custom subnetwork. Ensure that the network name is specified. Give the short name, not the resource path (for example, default rather than https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default/subnetworks/default).The subnetwork must be in the same region as the application.
session_affinity	Optional. Set to true to configure App Engine to route multiple sequential requests for a given user to the same App Engine instance such as when storing user data locally during a session. Session affinity enables inspecting the value of a cookie to identify multiple requests by the same user and then directs all such requests to the same instance. If the instance is rebooted, unhealthy, overloaded or becomes unavailable when the number of instances has been scaled down, session affinity will be broken and further requests are then routed to a different instance. Note that enabling session affinity can affect your load balancing setup. This parameter is disabled by default.
forwarded_ports	Optional. You can forward ports from your instance (HOST_PORT) to the Docker container (CONTAINER_PORT). HOST_PORT must be between 1024 and 65535 and cannot conflict with the following ports: 22, 8080, 8090, 8443, 10000, 10001, 10400-10500, 11211, 24231. CONTAINER_PORT must be between 1 and 65535 and cannot conflict with the following ports: 22, 10001, 10400-10500, 11211. If you only specify a PORT, then App Engine assumes that it is the same port on the host and the container. By default, both TCP and UDP traffic are forwarded. Traffic must be directly addressed to the target instance's IP address rather than over the appspot.com domain or your custom domain.

Advanced network configuration

You can segment your Compute Engine network into subnetworks. This allows you to enable VPN scenarios, such as accessing databases within your corporate network.

To enable subnetworks for your App Engine application:

1. Create a custom subnet network.

2. Add the network name and subnetwork name to your app.yaml file, as specified above.

3. To establish a simple VPN based on static routing, create a gateway and a tunnel for a custom subnet network. Otherwise, see how to create other types of VPNs.

Port forwarding

Port forwarding allows for direct connections to the Docker container on your instances. This traffic can travel over any protocol. Port forwarding is intended to help with situations where you might need to attach a debugger or profiler. Traffic must be directly addressed to the target instance's IP address rather than over the appspot.com domain or your custom domain.

By default, incoming traffic from outside your network is not allowed through the Google Cloud Platform firewalls. After you have specified port forwarding in your app.yaml file, you must add a firewall rule that allows traffic from the ports you want opened.

You can specify a firewall rule in the Networking Firewall Rules page in the Google Cloud console or using gcloud commands.

For example, if you want to forward TCP traffic from port 2222:

1. In the network settings of your app.yaml, include:

   network:
     forwarded_ports:
       - 2222/tcp
   

   1. If you use the Python runtime, modify the app.yaml to include:

      entrypoint: gunicorn -b :$PORT -b :2222 main:app
      

2. Specify a firewall rule in the Google Cloud console or using gcloud compute firewall-rules create to allow traffic from any source (0.0.0.0/0) and from tcp:2222.

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.

You can specify up to eight volumes of tmpfs in the resource settings. You can then enable workloads that require shared memory via tmpfs and can improve file system I/O.

For example:

resources:
  cpu: 2
  memory_gb: 2.3
  disk_size_gb: 10
  volumes:
  - name: ramdisk1
    volume_type: tmpfs
    size_gb: 0.5

You can use the following options when configuring resource settings:

Option	Description	Default
cpu	The number of cores; it must be one, an even number between 2 and 32, or a multiple of 4 between 32 and 80.	1 core
memory_gb	RAM in GB. The requested memory for your application, which does not include the ~0.4 GB of memory that is required for the overhead of some processes. Each CPU core requires a total memory between 1.0 and 6.5 GB. To calculate the requested memory: memory_gb = cpu * [1.0 - 6.5] - 0.4 For the example above where you have specified 2 cores, you can request between 1.6 and 12.6 GB. The total amount of memory available to the application is set by the runtime environment as the environment variable GAE_MEMORY_MB.	0.6 GB
disk_size_gb	Size in GB. The minimum is 10 GB and the maximum is 10240 GB.	13 GB
name	Required, if using volumes. Name of the volume. Names must be unique and between 1 and 63 characters. Characters can be lowercase letters, numbers, or dashes. The first character must be a letter, and the last character cannot be a dash. The volume is mounted in the app container as /mnt/NAME.
volume_type	Required, if using volumes. Must be tmpfs.
size_gb	Required, if using volumes. Size of the volume, in GB. The minimum is 0.001 GB and the maximum is the amount of memory available in the application container and on the underlying device. Google does not add additional RAM to your system to satisfy the disk requirements. RAM allocated for tmpfs volumes will be subtracted from memory available to the app container. The precision is system dependent.

Split health checks

By default, split health checks are enabled. You can use periodic health check requests 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. If an instance is not live, then it is restarted. If an instance is not ready, then it will not receive any client requests. A health check can also fail if there is no free disk space.

There are two types of health checks that you can use:

• Liveness checks confirm that the VM and Docker container are running. App Engine restarts unhealthy instances.
• Readiness checks confirm your instance is ready to accept incoming requests. Instances that fail the readiness check are not added to the pool of available instances.

Warning: Legacy health checks using the /_ah/health path are now deprecated, and you should migrate to use split health checks.

By default, HTTP requests from health checks are not forwarded to your application container. If you want to extend health checks to your application, then specify a path for liveness checks or readiness checks. A customized health check to your application is considered successful if it returns a 200 OK response code.

Liveness checks

Liveness checks confirm that the VM and the Docker container are running. Instances that are deemed unhealthy are restarted.

You can customize liveness check requests by adding an optional liveness_check section to your app.yaml file, for example:

liveness_check:
  path: "/liveness_check"
  check_interval_sec: 30
  timeout_sec: 4
  failure_threshold: 2
  success_threshold: 2

The following settings are available for liveness checks:

Field	Default	Range (Minimum-Maximum)	Description
path	None		If you want liveness checks to be forwarded to your application container, specify a URL path, such as "/liveness_check"
timeout_sec	4 seconds	1-300	Timeout interval for each request, in seconds.
check_interval_sec	30 seconds	1-300	Time interval between checks, in seconds. Note that this value must be greater than timeout_sec.
failure_threshold	4 checks	1-10	An instance is unhealthy after failing this number of consecutive checks.
success_threshold	2 checks	1-10	An unhealthy instance becomes healthy again after successfully responding to this number of consecutive checks.
initial_delay_sec	300 seconds	0-3600	The delay, in seconds, after the instance starts during which health check responses are ignored. This setting applies to each newly created instance and can allow a new instance more time to get up and running. The setting delays autohealing from checking on and potentially prematurely recreating the instance if the instance is in the process of starting up. The initial delay timer starts when the instance is in RUNNING mode. For example, you may want to increase the delay if your application has initialization tasks that take a long time before it is ready to serve traffic.

Readiness checks

Readiness checks confirm that an instance can accept incoming requests. Instances that don't pass the readiness check are not added to the pool of available instances.

You can customize health check requests by adding an optional readiness_check section to your app.yaml file, for example:

readiness_check:
  path: "/readiness_check"
  check_interval_sec: 5
  timeout_sec: 4
  failure_threshold: 2
  success_threshold: 2
  app_start_timeout_sec: 300

The following settings are available for readiness checks:

Field	Default	Range (Minimum-Maximum)	Description
path	None		If you want readiness checks to be forwarded to your application container, specify a URL path, such as "/readiness_check"
timeout_sec	4 seconds	1-300	Timeout interval for each request, in seconds.
check_interval_sec	5 seconds	1-300	Time interval between checks, in seconds. Note that this value must be greater than timeout_sec.
failure_threshold	2 checks	1-10	An instance is unhealthy after failing this number of consecutive checks.
success_threshold	2 checks	1-10	An unhealthy instance becomes healthy after successfully responding to this number of consecutive checks.
app_start_timeout_sec	300 seconds	1-1800	This setting applies to new deployments, not individual VMs. It specifies the maximum time in seconds allowed for a sufficient number of instances in a deployment to pass health checks. If this duration is exceeded then the deployment fails and is rolled back. The timer starts when the Compute Engine instances have been provisioned and the Load Balancer backend service has been created. For example, you might want to increase the timeout if you wish to provide longer timeouts during deployments for a sufficient number of instances to become healthy.

Health check frequency

To ensure high availability, App Engine creates redundant copies of each health checker. If a health checker fails, a redundant one can take over with no delay.

If you examine the nginx.health_check logs for your application, you might see health check polling happening more frequently than you have configured, due to the redundant health checkers that are also following your settings. These redundant health checkers are created automatically and you cannot configure them.

Service scaling settings

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

You can use either automatic or manual scaling. The default is automatic scaling.

Automatic scaling

You can configure automatic scaling by adding an automatic_scaling section to your app.yaml file. For example:

automatic_scaling:
  min_num_instances: 1
  max_num_instances: 15
  cool_down_period_sec: 180
  cpu_utilization:
    target_utilization: 0.6
  target_concurrent_requests: 100

The following table lists the settings you can use with automatic scaling:

Name	Description
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	The minimum number of instances given to your service. When a service is deployed, it is given this many instances and scales according to traffic. Must be 1 or greater, default is 2 to reduce latency. Note: The number of running instances may drop below this value for a short period of time during some events. If your application requires running continuously on a certain number of instances, consider overprovisioning.
max_num_instances	The maximum number of instances that your service can scale up to. The maximum number of instances in your project is limited by your project's resource quota. Default is 20.
cool_down_period_sec	The number of seconds that the autoscaler should wait before it starts collecting information from a new instance. This prevents the autoscaler from collecting information when the instance is initializing, during which the collected usage would not be reliable. The cool-down period must be greater than or equal to 60 seconds. Default is 120.
cpu_utilization	Use this header if you are going to specify the target CPU utilization.
target_utilization	Target CPU utilization. CPU use is averaged across all running instances and is used to decide when to reduce or increase the number of instances. Note that instances are downscaled irrespective of in-flight requests 25 seconds after an instance receives the shutdown signal. Default is 0.5.
target_concurrent_requests	(Beta) Target number of concurrent connections per instance. If you specify a value for this parameter, then the autoscaler uses the average number of concurrent connections across all running instances to decide when to reduce or increase the number of instances. An instance is downscaled 25 seconds after it receives the shutdown signal, regardless of requests that are in process. If you don't specify a value for this parameter, then the autoscaler doesn't target a number of concurrent connections per instance. Connections are different from requests. A connection can be reused by a client to send multiple requests.

Manual scaling

You can configure manual scaling by adding a manual_scaling section to your app.yaml file. For example:

manual_scaling:
  instances: 5

The following table lists the settings you can use with manual scaling:

Name	Description
manual_scaling	Required to enable manual scaling for a service.
instances	The number of instances to assign to the service. Note: The number of running instances may drop below this value for a short period of time during some events. If your application requires running continuously on a certain number of instances, consider overprovisioning.

Defining environment variables

You can define environment variables in app.yaml to make them available to your app, for 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.

Using your environment variables

To retrieve and your environment variable for the Java runtime, use System.getenv().

Also see the list of the latest Java or Java 8 runtime environment variables that cannot be overwritten. For example, all the environment variables that are prefixed with GAE are reserved for system use.