Configuring your App with app.yaml

A Python App Engine application can be configured by a file named app.yaml that contains cpu, memory, network and disk resources, automatic or manual scaling configurations, and general settings.

About app.yaml files

A Python 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 Python application:

runtime: python
env: flex
entrypoint: gunicorn -b :$PORT main:app

runtime_config:
  python_version: 3

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:

NameDescription
runtime: python This setting is required. It is name of the App Engine language runtime used by this application. To specify Python, use python. This selects a full implementation of Python 2.7 or 3.6. Use the runtime_config setting to choose a different version of Python. This runtime does not support any App Engine APIs. You must use the publicly available REST APIs to access cloud services. Read more.

Other runtimes are available; refer to each languages's documentation for more info.
env: flex 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. 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.

Note: Services were previously called "modules."

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$

You can use the runtime_config section to select a specific version of Python:

runtime_config:
    python_version: <version number>

The valid values for python_version are:

  • 3 which uses the latest supported Python 3.x release, which is currently 3.6.2.
  • 3.4 which uses Python 3.4.2.
  • 3.5 which uses Python 3.5.4.
  • 3.6 which uses Python 3.6.2.
  • 2 which uses Python 2.7.9.

You don't need to include the runtime_config section if you are using Python 2, which is the default.

Network settings

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

network:
  instance_tag: TAG_NAME
  name: NETWORK_NAME
  subnetwork_name: SUBNETWORK_NAME
  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
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 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.
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.
forwarded_ports Optional. You can forward ports from your instance (HOST_PORT) to the Docker container (CONTAINER_PORT). 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 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 VPN, create a gateway and a tunnel for a custom subnet network.

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.

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 Platform Console or using gcloud commands.

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

  1. Modify the app.yaml to include:

    entrypoint: gunicorn -b :$PORT -b :2222 main:app
    
  2. In the network settings of your app.yaml, include:

    network:
      forwarded_ports:
        - 2222/tcp
    
  3. Specify a firewall rule in the Cloud Platform 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 or an even number between 2 and 32. 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 0.9 and 6.5 GB.

To calculate the requested memory:

memory_gb = cpu * [0.9 - 6.5] - 0.4

For the example above where you have specified 2 cores, you can request between 1.4 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. 10 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.

Health checks

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.

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

  • Legacy health checks are enabled by default and are generally available (GA). These health checks confirm that your App Engine instance is running and healthy.

  • Updated health checks are more fine-grained and allow you to use separate checks to confirm that your App Engine instance is running (live) and ready to serve content (ready). These health checks are in beta, and you must explicitly enable updated health checks.

You can only use one type of health check in a project. You can modify both types of health checks with custom logic in your app.yaml file.

Legacy health checks

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

health_check:
  enable_health_check: True
  check_interval_sec: 5
  timeout_sec: 4
  unhealthy_threshold: 2
  healthy_threshold: 2

You can use the following options with legacy health checks:

Option Description Default
enable_health_check Enable/disable health checks. Health checks are enabled by default.
To disable health checking, set to False.
True
check_interval_sec Time interval between checks. 1 second
timeout_sec Health check timeout interval. 1 second
unhealthy_threshold An instance is unhealthy after failing this number of consecutive checks. 1 check
healthy_threshold An unhealthy instance becomes healthy again after successfully
responding to this number of consecutive checks.
1 check
restart_threshold When the number of failed consecutive health checks exceeds this threshold, the instance is restarted. 300 checks

Updated health checks

There are two types of updated health checks. You can use liveness checks to confirm that your App Engine instance is running, and readiness checks to confirm that your instance is ready to serve content.

By default, HTTP requests from updated 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.

Enabling updated health checks

To enable updated health checks for your Google Cloud Platform project, you can run the following command:

gcloud beta app update --split-health-checks --project [YOUR_PROJECT_ID]

You can also enable updated health checks by specifying a liveness_check or readiness_check section in your app.yaml file. For examples, see Liveness checks and Readiness checks.

You must enable updated health checks for each project individually. By default, legacy health checks are enabled. You cannot use both types of health checks in the same project.

If you are updating an application that was using legacy health checks and you customized the settings, you must remove the health_check section from your app.yaml file.

To confirm the type of health checks your application is using, run the following command:

gcloud beta app describe

If your application is using updated health checks, then the description should include the following information:

featureSettings:
    splitHealthChecks: true

After you enable updated health checks, deploy a new major version of your app to start using liveness and readiness health checks.

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.
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 can allow an instance more time at deployment to get up and running.

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.
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-3600 The maximum time, in seconds, an instance has to become ready after the VM and other infrastructure are provisioned. After this period, the deployment fails and is rolled back. You might want to increase this setting if your application requires significant initialization tasks, such as downloading a large file, before it is ready to serve.

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.

Automatic scaling

You can set automatic scaling in the app.yaml file. For example:

service: my-service
runtime: python
env: flex
automatic_scaling:
  min_num_instances: 5
  max_num_instances: 20
  cool_down_period_sec: 120 # default value
  cpu_utilization:
    target_utilization: 0.5

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

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 Must be 1 or greater, default is 2 to reduce latency. 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 is 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 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. 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. Note that instances are downscaled irrespective of in-flight requests, 25 seconds after an instance receives the shutdown signal.

Manual scaling

You can set manual scaling in the app.yaml file. For example:

service: my-service
runtime: python
env: flex
manual_scaling:
  instances: 5

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

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

Defining environment variables

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

env_variables:
  MY_VAR: 'my value'
It is then possible to get these values using os.environ.

Setting project ID (app ID) for a project

In some App Engine standard runtimes, you might have specified the project ID (sometimes called "app ID" in App Engine standard) in the project's app.yaml or appengine-web.xml file. However, flexible runtimes expect the project ID (app ID) to be supplied in either of two ways:

  • Specify the project ID prior to invoking gcloud app deploy to deploy your app. You specify the project ID using the command gcloud config set project YOUR-PROJECT-ID. You can view the current project ID using the command gcloud config list.

  • Specify the project ID during deployment using the Google Cloud plugin for Intellij or the Google Cloud plugin for Eclipse.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

App Engine flexible environment for Python docs