Configuration Files

Note: Services were previously called "modules", and services are still declared in app.yaml files as modules, for example: module: service_name.

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 app.yaml 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 app.yaml reference section.

The default service

Every application has a single default service. The default service is defined by the standard app.yaml file or by an app.yaml with the setting service: default. 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
• queue.yaml
• index.yaml
• cron.yaml
• dos.yaml

If you would like to update these files automatically during each deployment, put them in the top level app directory and specify the app directory when you issue the appcfg.py update command.

If you place configuration files inside a service's directory (alongside the app.yaml file for the service), they will be updated only when you explicitly name that service's YAML file in the update command. They will not be updated when you update the root app directory that contains subfolders for each service.

You can also update configuration files individually using the special update commands (update_dispatch, update_queues, update_indexes, update_cron, update_dos) and specifying the app directory, or by just naming the files themselves in the update command.

An example

Here is an example of how you would configure YAML files for an application that has three services: a default service that handles web requests, plus two more services that handle mobile requests and backend processing.

Start by defining a configuration file named app.yaml that will handle all web-related requests:

runtime: python27
api_version: 1
threadsafe: true

This configuration would create a default service with automatic scaling and a public address of http://simple-sample.appspot.com.

Next, assume that you want to create a service to handle mobile web requests. For the sake of the mobile users (in this example) the max pending latency will be just a second and we’ll always have at least two instances idle. To configure this you would create a mobile-frontend.yaml configuration file. with the following contents:

service: mobile-frontend
runtime: python27
api_version: 1
threadsafe: true

automatic_scaling:
  min_idle_instances: 2
  max_pending_latency: 1s

The service this file creates would then be reachable at http://mobile-frontend.simple-sample.appspot.com.

Finally, add a service, called my-service for handling static backend work. This could be a continuous job that exports data from Datastore to BigQuery. The amount of work is relatively fixed, therefore you simply need 1 resident service at any given time. Also, these jobs will need to handle a large amount of in-memory processing, thus you’ll want services with an increased memory configuration. To configure this you would create a my-service.yaml configuration file with the following contents.

service: my-service
runtime: python27
api_version: 1
threadsafe: true

instance_class: B8
manual_scaling:
  instances: 1

The service this file creates would then be reachable at http://my-service.simple-sample.appspot.com.

Notice the manual_scaling: setting. The instances: parameter tells App Engine how many instances to create for this service.

You might also want to download this Python demo app and take a look.