Configuration Files

Each version of a service is defined in a .yaml file, which gives the name of the service and version. The YAML file usually takes the same name as the service it defines, but this is not required. If you are deploying several versions of a service, you can create multiple yaml files in the same directory, one for each version.

Typically, you create a directory for each service, which contains the service's YAML files and associated source code. Optional application-level configuration files (dispatch.yaml, cron.yaml, index.yaml, and queue.yaml) are included in the top level app directory. The example below shows three services. In service1 and service2, the source files are at the same level as the YAML file. In service3, there are YAML files for two versions.

For small, simple projects, all the app's files can live in one directory:

Every YAML file must include a version parameter. To define the default service, you can explicitly include the parameter service: default or leave the service parameter out of the file.

Each service's configuration file defines the scaling type and instance class for a specific service/version. Different scaling parameters are used depending on which type of scaling you specify. If you do not specify scaling, automatic scaling is the default. The scaling and instance class settings are described in the appengine-web.xml reference section.

For each service you can also specify settings that map URL requests to specific scripts and identify static files for better server efficiency. These settings are also included in the yaml file and are described in the appengine-web.xml reference section.

The default service

Every application has a single default service. You can define the default service in the appengine-web.xml with the setting service: default, but it isn't necessary to do this. All configuration parameters relevant to services can apply to the default service.

Optional configuration files

These configuration files control optional features that apply to all the services in an app:

• dispatch.yaml overrides routing default rules by sending incoming requests to a specific service based on the path or hostname in the URL.
• queue.yaml configures both push queues and pull queues.
• index.yaml specifies which indexes your app needs if using Datastore queries.
• cron.yaml configures regularly scheduled tasks that operate at defined times or regular intervals.

To deploy updates of these configuration files to App Engine, run the following command from the directory where they are located:

    gcloud app deploy [CONFIG_FILE]

An example

Here is an example of how you would configure the various files in a WAR directory structure for an application that has two services: a default service that handles web requests, plus another service (named my-service) for backend processing.

Assuming that the top-level EAR directory is "my-application," define the file my-application/META-INF/appengine-application.xml:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<appengine-application xmlns="http://appengine.google.com/ns/1.0">
  <application>my-application</application>
</appengine-application>

Create WAR directories for the two services: my-application/default and my-application/my-service.

Now create an appengine-web.xml file in each WAR that specifies the parameters for the service. The file must include a version name for the service. To define the default service, you can explicitly include the <service>default</service> parameter or leave it out of the file. Here is the file my-application/default/WEB-INF/appengine-web.xml that defines the default service:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>my-application</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
</appengine-web-app>

The file my-application/my-service/WEB-INF/appengine-web.xml defines the service that will handle background requests:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>my-application</application>
  <module>my-service</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

Finally, define the file my-application/META-INF/application.xml that enumerates the services. Note that the default service should be the first service listed.

<?xml version="1.0"
encoding="UTF-8"?>

<application
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                      http://java.sun.com/xml/ns/javaee/application_5.xsd"
  version="5">

  <description>GAE Java SuperFun app</description>
  <display-name>SuperFun</display-name>

  <!-- Services -->
  <!-- The default service should be listed first -->
  <module>
    <web>
      <web-uri>default</web-uri>
      <context-root>default</context-root>
    </web>
  </module>
  <module>
    <web>
      <web-uri>my-service</web-uri>
      <context-root>my-service</context-root>
    </web>
  </module>

</application>

App Engine will ignore the <context-root> elements, so HTTP clients need not prepend it to the URL path when addressing a service.