app.yaml Configuration File

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:

runtime: python

runtime_config:  operating_system: "ubuntu24"  runtime_version: "3.14"

service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com

skip_files: - ^.*\.bak$

Runtime-specific settings

See the Python runtime page to learn more about specifying a Python interpreter 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:

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:

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.

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:

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:

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:

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:

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 Python runtime, use os.environ.

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