Google Cloud Platform

Automate deployments and traffic splitting with the App Engine Admin API

Google App Engine provides you with easy ways to manage your application from the Google Cloud Platform Console or the command line. However, there are situations when you need to manage your application programmatically. Perhaps you need to deploy to App Engine from your own custom tool chain, or you want to write your own A/B testing framework.

The App Engine Admin API lets you do all these things and more, so we're happy to announce that the API is now generally available.

You can use the Admin API not only to deploy new versions and manage traffic for any service, but also to change various configuration settings of your application, such as instance class. You can also stop individual versions in order to scale your App Engine Flexible environment deployments to zero. Finally, the API allows you to deploy several App Engine services in parallel, speeding up your deployments.

You can use the Google APIs explorer to easily test-drive the API and get a feel for what it offers.

Usage example

Let’s return to the earlier scenario: imagine that you’re writing a script to deploy a new version of your application and test it with 50% of production traffic or gradually shift the rest of the traffic to the new version. Let’s walk through the basic steps here; you’ll find the full instructions in our Getting started guide.

To deploy a version, you’ll generally follow these steps:
sol

  1. Stage your application resources to a Google Cloud Storage bucket
  2. Convert your app.yaml file to a JSON manifest
  3. Send an HTTP POST request to the Admin API to create the new version
For this example, we’ll deploy a version for which the source code has already been staged.
First, create a file called “helloworld.json” with the following contents:

  {
  "deployment": {
    "files": {
      "main.py": {
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      },
    }
  },
  "handlers": [
    {
      "script": {
        "scriptPath": "main.app"
      },
      "urlRegex": "/.*"
    }
  ],
  "runtime": "python27",
  "threadsafe": true,
  "id": "appengine-helloworld",
  "inboundServices": [
    "INBOUND_SERVICE_WARMUP"
  ]
}

Next, send an HTTP POST request to the Admin API to create the new version:

  POST 
https://appengine.googleapis.com/v1/apps/my-application/services/def
ault/versions helloworld.json

(To actually send this request, you'll need to set up authentication tokens; the Getting started guide contains the full steps.)

The response will contain the ID of a long-running operation that you can then poll to identify when the deployment has completed.

To split traffic between versions, you need at least one other version. You can create another version by changing the version ID and redeploying the same app. For example, using the same steps, deploy a “appengine-goodbyeworld” version using this JSON manifest:

  {
  "deployment": {
    "files": {
      "main.py": {
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/goodbye_world/main.py"
      },
    }
  },
  "handlers": [
    {
      "script": {
        "scriptPath": "main.app"
      },
      "urlRegex": "/.*"
    }
  ],
  "runtime": "python27",
  "threadsafe": true,
  "id": "appengine-goodbyeworld",
  "inboundServices": [
    "INBOUND_SERVICE_WARMUP"
  ]
}

Once the version is successfully deployed, route 50% of traffic to it with the following request:

  PATCH 
https://appengine.googleapis.com/v1/apps/my-application/services/def
ault/?updateMask=split { "split": { "shardBy": "IP", "allocations { 
"appengine-helloworld": 0.5, "appengine-goodbyeworld": 0.5 } } }

Now you can visit your application at http://.appspot.com

. As you reload the page, you'll see the contents change depending on which version your request got routed to.

Another way to move traffic between versions is to use App Engine’s Traffic Migration feature to gradually shift all traffic as quickly as possible while giving the new instances sufficient time to warm up:

  PATCH 
https://appengine.googleapis.com/v1/apps/my-application/services/def
ault/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { 
<"appengine-goodbyeworld": 1 } } }

More information

The App Engine Admin API documentation contains full instructions on how to use the API, including how to authenticate to the API and how to use client libraries to call the API from your specific programming language.

We hope the Admin API simplifies your day-to-day workflows by letting you manage your App Engine applications from the tools you already use.