Migrate to Extensible Service Proxy V2 Beta

The Extensible Service Proxy V2 Beta (ESPv2 Beta) is an Envoy-based proxy that enables Cloud Endpoints to provide API management features. ESPv2 Beta is a replacement of the Extensible Service Proxy (ESP) that shipped with the initial Beta release of Endpoints for Cloud Functions and Cloud Run.

This document describes how to migrate an existing deployment of an Endpoints API for Cloud Functions or Cloud Run from using ESP to using ESPv2 Beta.

This document also describes two issues that you should take into consideration before you migrate your APIs:

Migrating your Endpoints APIs to use ESPv2 Beta

To migrate your APIs to ESPv2 Beta you only have to build your existing API service configuration into a new ESPv2 Beta docker image, then deploy the image. To migrate your APIs, see:

You do not have to modify the API spec or modify the backend service unless you have to work around any issues described in the Release Notes or to handle any of the other migration issues described below.

Updating the variable used to specify startup options

To specify startup options to ESP, you could set the ESP_ARGS environment variable.

With ESPv2 Beta, you use the same mechanism to set startup options, but the environment variable is now named ESPv2_ARGS. See Extensible Service Proxy V2 Beta startup options for more information on setting ESPv2_ARGS and the options available for setting ESPv2_ARGS.

Handle JWTs in the backend service

When using JWTs to perform authentication, ESP usually forwards all headers it receives. However, ESP may override the original Authorization header when the backend address is specified by x-google-backend in OpenAPI specification or BackendRule in gRPC service configuration. If a request has the Authorization header, its value will be copied to a new header X-Forwarded-Authorization if ESP needs to over-write it.

Both proxies send the authentication result in the X-Endpoint-API-UserInfo to the backend API. It is recommended to use this header instead of the original Authorization header. However, the format of the header differs.

In ESP, the X-Endpoint-API-UserInfo header contains a Base64 encoded JSON object that includes the payload of the JWT as well as additional fields added by ESP.

If available in the JWT, ESP adds the id, issuer, email, and audiences properties to the encoded JSON object. It also adds the claims property that includes the original payload of the JWT. The JSON object has the form:

{
  "id": "from-sub",
  "issuer": "from-iss",
  "email": "from-email",
  "audiences": ["from-aud"],
  "claims": {
     original-jwt-payload
   }
}

See Using a custom method to authenticate users and Authentication between services for more on using JWTs with authentication.

ESPv2 Beta sets the X-Endpoint-API-UserInfo header differently than ESP. With ESPv2 Beta, the X-Endpoint-API-UserInfo header only contains the Base64 encoded payload of the original JWT without modification.

If your backend service expects the X-Endpoint-API-UserInfo header to use the ESP representation, you have to update your service to use this new format.

What's next

Learn about: