English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Python Backends Configuration

You can add backends to your application in a configuration file called `backends.yaml`, which declares the name and desired properties of each backend server.

- About backends.yaml
- Types of Backends
- Request Handling
- Defining Handlers
- Instance Classes
- Backends Definitions

## About backends.yaml

Backends have several unique and important differences from default App Engine instances; for more information about how backends work, please see the Backends documentation. The following code sample shows a sample `backends.yaml` file. This configuration file defines four separate backends:

1. A backend named `memdb`. This backend has five instances of the instance class B8.
2. A backend named `crawler` uses the default class and options, but with ten instances. This backend defines `crawler.py` as the start handler.
3. A backend named `worker` using the default class with one instance, and configured with failfast to disable pending queue behavior.
4. A backend named `cmdline`, used to execute long-running commands issued by admins of the application.

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

## Types of Backends

App Engine supports two backend types: resident and dynamic. Resident backends are the default type of backend; they use resident instances, which remain in memory, even when idle, and are restarted automatically. This allows you to perform larger tasks or tasks requiring continuous processing. By default, a backend is configured with one instance, but you can add more in the configuration file.

The following table compares the major features of resident and dynamic backends:

| Resident Backends | Dynamic Backends | Other Notes
--- | --- | --- | ---
Instance type | Resident | Dynamic | Both resident and dynamic backends have one instance by default. You can configure the number of instances using the optional instances directive.
Startup | Manual, via the Admin Console or command-line tool | Upon receipt of an HTTP request |
Shutdown | Usually manual, via the Admin Console or command-line tool | After sitting idle for a few minutes. | Other factors can affect shutdown. See Shutdown for more information.
State | Preserved until manually shut down, or until an unexpected shutdown event takes place. See Shutdown for more details on shutdown events. | Erased when the backend is shutdown after sitting idle for a few minutes. |
Type of Processing | Continuous or driven by requests | Driven by requests |
Cost | Relatively more, because resident backends run continuously. | Relatively less, because dynamic backends terminate when idle. | Billed by the hour, even if idle

Uses

Any work that requires continuous processing or preserved state, such as:

- Storing a game state in memory
- Caching a social graph or web index
- Running a web crawler

Any request-based work, such as:

- Task queue requests requiring more power, time, or memory to complete.
- Report generation
- Large or complex user requests
- Ad-hoc queries or admin scripts

Both resident and dynamic backends allow you to address tasks to a specific instance of a backend. You can obtain the instance and backend names programmatically; the endpoint takes the form `http://[instance].[backend_name].[your_app_id].appspot.com`.

Load Balancing | Requests are evenly balanced across all instances of the backend. | Requests are concentrated on the lowest-numbered instances first, and are served by additional instances as traffic increases. |

## Request Handling

Resident and dynamic backends both use pending queues to handle incoming traffic. Requests to a backend that is busy handling other requests wait in a pending queue for a short period of time (10 seconds) before being aborted.

You can disable the backend's pending queue using the `failfast` feature. You can configure failfast either on a per-request basis or on an entire backend (though the backend option is currently experimental). To use failfast for a single request, add the following header to the task request:

    X-AppEngine-FailFast

To make a backend failfast, add the `failfast` option to the backend definition in `backends.yaml`.

## Defining Handlers

Backends share the request handlers defined in `app.yaml` with your main application version. It is not possible to configure a separate set of handlers for each backend, so mark any handlers that you wish to restrict to admins with `login: admin`. This login declaration blocks external requests, while allowing internal requests (for example, from another instance of your application, or a Task Queue) to access a handler without additional configuration.

The `start` directive allows each backend to define a separate handler for `/_ah/start`.

## Instance Classes

App Engine provides four different classes of backend instances, each with different memory and and CPU limits. These classes allow you to configure your backend with the processing capacity you need to perform your work. Each class has a specific hourly billing rate. See Billable Resource Unit Costs for billing.

The default class for backends is `B2`, which gives you 256MB of memory and 1200MHz of CPU capacity.

You can change the class of a backend using the `class` directive in `backends.yaml`:

    backends:
    - name: cmdline
      class: B4

The `class` directive has the following values:

Class configuration | Memory limit | CPU limit | Cost per hour*
--- | --- | --- | ---
`B1` | 128MB | 600MHz | 0.08
`B2` (default) | 256MB | 1.2GHz | $0.16
`B4` | 512MB | 2.4GHz | $0.32
`B8` | 1024MB | 4.8GHz | $0.64

*See Billing, Quotas, and Limits for more information about Backends Billing.

## Backends Definitions

The `backends.yaml` file has a single list element called `backends`. Each element in the list represents a backend for the application. Backends are subject to Billing, Quotas, and Limits.

A `backends` directive can have the following directives:

`name` (required)

  The server name, composed of letters, digits, and hyphens. Cannot be a name that is currently used as an application version. This name is also referred to as the `BACKEND_ID`.

`class`

  Determines the backend's instance class, which determines the memory and CPU limits for each instance. The default class is `B2`.

`instances`

  An integer between `1` and `20` indicating the number of instances to assign to the given backend. Defaults to `1` if unspecified. The instance number is also referred to as the `INSTANCE_ID`.

  Each instance can handle a single request at a time. Backends have pending queues; requests to a busy instance retry for 10 seconds before aborting.

`start`

  Specifies a script to run at `start` time. Adding this directive is equivalent to defining a handler for `/_ah/start`, but only applies to a single backend. The value should be a filename relative to the application's root directory.

  If you specify a startup script in `backends.yaml`, it overrides any other handler that matches `/_ah/start` in `app.yaml`, such as `url: .*` or even `url: /_ah/start`. If unspecified, the `start` request is handled like a normal request, by matching against the `handlers` declared in `app.yaml`. If no handler matches, the `start` request will return `404`, which is considered a successful response.

  For more information, see Startup.

`options`

  A list of boolean settings, which can include one or more of the following options.

  dynamic

    Defaults to resident instances. This option sets the backend to use dynamic instances rather than resident instances.

    Backends default to resident instances. Backends can be configured to always remain in memory, so state is preserved across requests. This means that the backends are configured to always remain in memory, as described in the Types of Backends section above. A resident server is only restarted when the underlying appserver restarts.

  failfastExperimental!

    The `failfast` option disables pending queues, so that an instance that is busy returns an HTTP 503 error immediately when it receives a new request. You can achieve this same behavior by adding an `X-AppEngine-FailFast` header to requests, and the header is not experimental.

  publicExperimental!

    Sets backend access to `public`. Public backends can serve external HTTP requests from the web. See Public and Private Backends for more information.