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.

Hierarchy graph of YAML services

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

Hierarchy graph of small YAML services

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. You can define the default service in the app.yaml 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 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

If the Google Cloud console project ID for this app is simple-sample then this configuration would create a default service with automatic scaling and a public address of https://simple-sample.uc.r.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 https://mobile-frontend-dot-simple-sample.uc.r.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 https://my-service-dot-simple-sample.uc.r.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.