Upgrading to the App Engine Flexible Environment Latest Release

The App Engine flexible environment includes several new features and improvements which also come with changes in the way that you configure your apps. If you previously deployed your apps to a beta release of the flexible environment, use this topic to help you upgrade to the current release.

To upgrade, you must account for several changes in your app's code and App Engine configuration files. Also be aware of the following key dates to ensure that you migrate or upgrade your apps before the deprecated beta-related services are shut down:

Important dates
  • Beta deprecation date: November 15th, 2016

    On November 15th, 2016, all deployments to App Engine using the beta vm:true configuration were deprecated.

  • General availability date: March 10th, 2017

    The App Engine flexible environment (env:flex) was released for general availability on March 10th, 2017.

  • Beta decommission date: December 15th, 2017

    On December 15th, 2017, the Managed VMs environment (vm:true) will be shut down and all apps using the beta vm:true configuration will stop receiving traffic.

Upgrading to the flexible environment

The past beta releases of the flexible environment have been deprecated, but configurations that were previously deployed with vm:true will continue to work until the decommission date, December 15th, 2017. On that date, all apps using vm:true will stop serving traffic and are required to upgrade to the env:flex configuration.

To upgrade to the flexible environment:

  1. Update your app.yaml configuration file by replacing the deprecated vm: true entry with env: flex. Example:

    runtime: python
    env: flex
    
  2. Depending on your app and configuration, you might also need to update that same app.yaml file to account for environment variable changes and the other breaking changes.

    Review the list of breaking changes below to determine what additional changes are required in your app.yaml.

    If you are using a runtime that was compatible with the App Engine standard APIs, such as python-compat , see also Continuing to use compat runtimes.

  3. While you are upgrading your app for the flexible environment, you should also consider making changes to utilize the new features.

  4. After you have made the necessary changes, deploy the new version of your app to App Engine.

    For example, from the root directory of your app where your app.yaml file is located, you can run:

    gcloud app deploy
    

Continuing to use compat runtimes

All customers must move to env:flex before December 15, 2017. For customers who cannot upgrade to a supported runtime, you can continue to use a runtime that is compatible with the App Engine standard APIs, such as python-compat . To run an application on a compat runtime on env:flex, follow these steps:

  1. Fill out this form.
  2. After you receive a confirmation email, update your app.yaml configuration file:
    1. Replace the deprecated vm:true entry with the env:flex element:
      env:flex
    2. Add the enable_app_engine_apis: true under the beta_settings section:
      beta_settings:
      enable_app_engine_apis: true

    Example:

    runtime: python
    env: flex
    entrypoint: gunicorn -b :$PORT main:app
    runtime_config:
      python_version: 3
    beta_settings:
      enable_app_engine_apis: true
  3. To keep your app running using a compat runtime, see the following sections.
  4. Plan the rest of your app's upgrade or migration to env:flex.

Cron service

If you are using a compat runtime, to keep existing handlers working with the Cron service, take the following steps:

  1. Remove login: admin from the related handler in your app.yaml file.
  2. Update the handler to verify that requests originate from App Engine's cron service, X-AppEngine-Cron.

Task queues service

Although it is unsupported in the flexible environment, if you are approved to use a compat runtime, the App Engine Task Queue API is still available. To keep existing handlers working with the Task Queues service, take the following steps:

  1. Remove login: admin from the related handler in your app.yaml file.
  2. Update the handler to verify that requests originate from App Engine's task queue service:
    • X-AppEngine-QueueName
    • X-AppEngine-TaskName
    • X-AppEngine-TaskRetryCount
    • X-AppEngine-TaskRetryReason
    • X-AppEngine-TaskExecutionCount
    • X-AppEngine-TaskETA

For alternatives to the Task Queue API, see Task queues.

Shared-core machine types

Shared-core machine types, which have less than 1 vCPU, are not supported in the App Engine flexible environment. If you are using shared core machines, when you move to env:flex, you must upgrade your machines to be at least one core. Alternatively, you can move the app to the App Engine standard environment.

Warmup requests

/_ah/warmup requests are not supported in the App Engine flexible environment.

To warm up your app, implement a health check handler that only returns a ready status when the application is warmed up.

For example, you can create a readiness check that returns a ready status after initializing the cache so your app won't receive traffic until it is ready.

Static files

If you are defining static files in the handlers: section of app.yaml, then these static files are served from App Engine instances directly, instead of from other App Engine infrastructure. The interface and behavior are identical, but a small amount of CPU and other resources are consumed on App Engine instances when a file is served.

Hidden resources

The underlying resources behind flexible environment deployments (including Cloud Load Balancing, Compute Engine instances, and Managed Instance Groups) are hidden in Google Cloud Platform Console in order to provide a fuller abstraction of an App Engine application and its instances. Individual instances can be viewed and controlled in the Cloud Platform Console on the Instances page.

Instances can still be unlocked and reached via SSH for debugging purposes. Instead of using the gcloud compute instances command, use gcloud app instances. You can also initiate SSH connections from the Cloud Platform Console Instances page.

Breaking changes

Upgrading to the App Engine flexible environment requires a few changes to your code and configuration files. This section includes deprecations and breaking changes that you must address before deploying your app with the env: flex configuration.

Library deprecations

The following libraries and their related services were deprecated on November 15th, 2016, and are not supported in the flexible environment:

app.yaml changes

Replace the deprecated configuration vm:true in your app.yaml file, with the flexible environment setting env:flex.

Authentication changes

You must also update the app.yaml file to remove or replace the other configuration setting that have been deprecated:

  • Secure handlers
    The secure setting under handlers is now deprecated for the App Engine flexible environment. If you need SSL redirection, you can update your application code and use the X-Forwarded-Proto header to redirect http traffic. You can also use the HTTP Strict Transport Security response header.
  • Login handlers
    The login setting under handlers is now deprecated for the App Engine flexible environment. You should follow the guidance for User service migration.

Environment variable changes

The following environment variables have been removed or renamed. When available, the replacement environment variable has been listed:

Deprecated environment variable New environment variable (where applicable)
APPENGINE_LOADBALANCER
APPENGINE_LOADBALANCER_IP
GAE_AFFINITY
GAE_APPENGINE_HOSTNAME
GAE_MINOR_VERSION
GAE_LONG_APP_ID GCLOUD_PROJECT
GAE_MODULE_INSTANCE GAE_INSTANCE
GAE_MODULE_NAME GAE_SERVICE
GAE_MODULE_VERSION GAE_VERSION
GAE_PARTITION
GAE_VM
HOSTNAME
MEMCACHE_ENV_DEBIAN_FRONTEND
MEMCACHE_ENV_PORT
MEMCACHE_NAME
MEMCACHE_PORT
MEMCACHE_PORT_11211_TCP
MEMCACHE_PORT_11211_TCP_ADDR
MEMCACHE_PORT_11211_TCP_PORT
MEMCACHE_PORT_11211_TCP_PROTO
MODULE_YAML_PATH
SERVER_SOFTWARE
USE_MVM_AGENT

Request header changes

The following HTTP request headers have changed:

  • Removed from all requests:

    • X-GOOGLE-REAL-IP
    • X-APPENGINE-API-TICKET
    • X-APPENGINE-AUTH-DOMAIN
    • X-APPENGINE-COUNTRY
    • X-APPENGINE-DATACENTER
    • X-APPENGINE-DEFAULT-VERSION-HOSTNAME
    • X-APPENGINE-HTTPS
    • X-APPENGINE-REQUEST-ID-HASH
    • X-APPENGINE-REQUEST-LOG-ID
    • X-APPENGINE-USER-IS-ADMIN
    • X-APPENGINE-USER-IP
    • X-APPENGINE-REGION
    • X-APPENGINE-CITY
    • X-APPENGINE-CITYLATLONG
  • Now included with all requests:

    • X-FORWARDED-FOR
    • X-CLOUD-TRACE-CONTEXT
    • X-FORWARDED-PROTO

Memcache service

The Memcache service is currently not available for the App Engine flexible environment. An alpha version of the memcache service will be available shortly. If you would like to be notified when the service is available, fill out this early access form.

If you need access to a memcache service immediately, you can use the third party memcache service from Redis Labs. To access this service, see Caching Application Data Using Redis Labs Memcache.

You can also use Redis Labs Redis Cloud, a third party fully-managed service. To access this service, see Caching Application Data Using Redis Labs Redis.

Task queues

The Task Queue API has limited availability outside of the standard environment. If you want to use the service outside of the standard environment, you can sign up for the Cloud Tasks alpha.

In many cases where you might use pull queues, such as queuing tasks or messages that will be pulled and processed by separate works, Cloud Pub/Sub is a good alternative that offers similar functionality and delivery guarantees.

URL routing changes

You can no longer route traffic to specific instances for apps that are running in the flexible environment. For example, you cannot direct requests to instance instanceID:

https://instanceID-dot-versionID-dot-serviceID-dot-app-id.appspot.com

New features to consider when upgrading

Take note of the following improvements that you can take advantage of when upgrading your app:

Pricing changes

The App Engine flexible environment release introduces a new pricing model. Customers who are currently using vm:true will receive one year of raw Compute Engine pricing. To view the new prices for the flexible environment, see Costs for flexible environment instances.

Tip: Spending limits are not supported in the flexible environment. You should consider creating budgets and setting alerts.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

App Engine flexible environment for Python docs