Traffic Migration

When you deploy a new version of your app's default module, all requests are immediately routed to the new version. If your app is experiencing high traffic at the time of the upgrade, you may see some increased latency as new instances of the new version must come online before requests can be handled.

Traffic migration automatically preloads new instances before user requests are re-routed, and gradually shifts the traffic from the older to the newer version. Once all traffic is re-routed, the new version automatically becomes the default version and your old default version will no longer receive any user requests. Traffic migration works only for default modules, support for all modules will be available in the future.

You can use traffic splitting to cut-over from one default version to another, but traffic migration is easier, and more efficient. Note that you cannot use traffic migration if you already have traffic splitting engaged, and you cannot use traffic splitting while traffic migration is underway.

Warmup requests

When a user request results in the creation of a new instance, a loading request is sent to the instance first, to initialize the instance and load the application code. This can increase latency when handling the first user request.

The App Engine backend can load code into a new instance before any user requests are routed to it. This is accomplished by sending a warmup request. Traffic migration works only if your new version enables warmup requests.

Warmup requests are already enabled by default in Java modules. For Python, Go, and PHP modules, you need to enable warmup requests by including this line in your app.yaml file:

inbound_services:

- warmup

For more information, read about warmup requests in the Python, Java, Go , and PHP documentation.

Uploading your new version

You must upload the version as an ordinary version. It will not start to receive requests until you enable migration.

Migrating to the new version

After you have uploaded the new version, migrate from the current default version to the new version using either the Admin Console or the appcfg utility as described in this section. Do not use the appcfg set_default_version command.

Migration takes a few minutes. Once migration is complete, the new version is designated the default version of your default module. The original version is still deployed - but it will not receive any user requests, unless they are sent with an explicit url path that targets that version.

Migration with the Admin Console

Once you've uploaded your new code, go to the Admin Console and select your project. (Migration is only available in the Admin Console at this time. It will appear in the Developers Console soon.)

Click through to the versions page, where you'll see a list of all the versions of your default module. Select your newly-uploaded version using the button to its left, and click on Migrate Traffic.

Migration with the appcfg command

After you've uploaded your new code, you can initiate traffic migration with these forms of the appcfg command:

# Uses the version name you've assigned in your config file
appcfg.py [options...] migrate_traffic <app-directory>

# The -V option overrides the version name in your config file, so you may not need to edit the config file at all
appcfg.py [options...] -V <name-of-new-def-version> migrate_traffic <app-directory>

The migrate_traffic command will only read the application and version name from your config file. No other parameters are processed.

The command will start the migration and return immediately. To learn when migration has completed, visit the Admin Console versions page and verify the default version has changed.