Configuring your App with app.yaml

A Java 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.

You can select the Java 8 / Jetty 9.3 Runtime or the Java 8 Runtime. Using Maven or Gradle makes this easier.

About app.yaml files

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

#  Copyright 2016 Google Inc. All Rights Reserved.
#
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
# [START appyaml]
runtime: java
env: flex

handlers:
- url: /.*
  script: this field is required, but ignored
  secure: always
# [END appyaml]

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: java This setting is required. It is name of the App Engine language runtime used by this application. To specify Java, use java.

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.

The Java runtime supports several configurations, based on Java 8:

To select Jetty9 (default / optional):

runtime_config:
   jdk: openjdk8
   server: jetty9

To select Java 8:

runtime_config:
   jdk: openjdk8

The flexible runtime environment

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

Network settings

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

    network:
      instance_tag: [TAG_NAME]
      name: [NETWORK_NAME]

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

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: .5
  memory_gb: 1.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 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 the maximum is 10240GB. 10GB
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.
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

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:

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

Servlet 3.1 annotations processing

Jetty 9 Quickstart works with advanced servlet annotations to improve startup performance. If you are using the Servlet 3.1 specification, and you want the Servlet 3.1 annotations to be processed, include this beta setting in your app.yaml file.

beta_settings:
  java_quickstart: true

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: java
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](/compute/docs/resource-quotas).
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.

Manual scaling

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

service: my-service
runtime: java
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 at the start. This number can later be altered by using the Modules API setNumInstances() function.

Defining environment variables

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

env_variables:
  MY_VAR: 'my value'
Is is then possible to get these values using 'System.getenv()'.

Send feedback about...

App Engine flexible environment for Java docs