Converting Backends to Services

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

The original App Engine architecture is based on a single frontend instance with optional backend instances. If you have an application that uses backends, you might want to convert the backends to a service format to take full advantage of the additional functionality that services provide, such as the ability to version backends.

App Engine automatically runs an existing backend as a new, non-default version of the default service. Resident backends are assigned manual scaling and dynamic backends are assigned basic scaling.

You can convert backend instances to named services that are versioned and have explicit scaling type and instance classes. You must replace the original backends.yaml file with multiple .yaml files as shown below.

For example, here is a fragment from a .yaml file that defines three backends (memdb, worker, and cmdline):

backends:
- name: memdb
  class: B8
  instances: 5
- name: worker
  start: worker.app
  options: failfast
- name: cmdline
  options: dynamic

To convert these backends to services, create a separate .yaml file for each service:

In memdb.yaml:

application: myapp
module: memdb
version: uno
instance_class: B8
manual_scaling:
  instances: 5

In worker.yaml:

application: myapp
module: worker
version: uno
# For failfast functionality, please use the ‘X-AppEngine-FailFast’ header on requests made to this module.
manual_scaling:
  instances: 1
handlers:
# If a module has an _ah/start handler, it should be listed first.
- url: /_ah/start
  script: worker.app

Note that the original definition of the worker backend used the start: tag to bind the script worker.app to the _ah/start path. For services, this binding is defined as a handler with the explicit _ah/start path. Additionally, if there's more than one handler, the _ah/start handler should be listed first.

In cmdline.yaml:

application: myapp
module: cmdline
version: uno
basic_scaling:
  max_instances: 1

The Python SDK contains a script that can perform these transformations for you. Given two .yaml files, one for the app and one for its backends, it creates new .yaml files defining services for each backend. Using the migration example above, assume the original file defining the three backends is called backends.yaml, and the file defining the main app is app.yaml. The script would generate three new .yaml files: memdb.yaml, worker.yaml, and cmdline.yaml. Here is how to call it:

$ path-to-sdk/backends_conversion.py backends.yaml app.yaml