Structure of a Google App Engine application

App Engine resources are structured as a hierarchy of services, versions, and instances, collectively referred to as an application. As we'll see, this hierarchy plays an important role in how systems are designed in App Engine, and relates closely to many of App Engine's features such as routing and deployment strategies. Note the following diagram:

The hierarchical model of App Engine is as follows:

• At the highest level, the service (formerly known as the module) represents an individual web service such as an API or front-end web application. An App Engine application can contain one or many services, and each project contains exactly one default service. A default service acts much like other services within the project, with some special considerations. When no service is specified, App Engine will route requests to the default service. Default services are typically viewed as the main entry point for an App Engine application, and often when people talk about an App Engine application, they are actually referring to this default service.
• Each App Engine service consists of one or more versions, which represent a unique implementation of the service. As the name implies, versions are generally used to represent unique versions of the service, such as changes to the service's API or its underlying implementation. When a service is deployed to App Engine, a version can be provided as part of the deployment command. If no version is provided, the platform will assign the deployment a new version in the form of a timestamp. App Engine provides mechanisms for starting and stopping services, as well as allocating traffic between versions.

These mechanisms allow developers to achieve things like graceful rollbacks, canary testing, and A/B testing. For example, a new version of a service can be deployed without allocating any traffic. Developers can then validate the service through load and integration tests. If the version looks good, a small portion of requests can be directed to it for canary testing. If things go well, traffic can be increased to 100%. At any point, the service can be rolled back by directing traffic to a previous version.

• At the bottom of the hierarchy, App Engine instances represent a running process of the given service and version. Each version of an App Engine service can have zero or more instances, which allows services to be scaled horizontally. Instances are generally managed as a group rather than individually, and instances should be considered ephemeral.