Migra al proxy de servicio extensible V2 Beta

El proxy de servicio extensible V2 Beta (ESPv2 Beta) es un proxy basado en Envoy que le permite a Cloud Endpoints proporcionar características de administración de API. ESPv2 Beta es un reemplazo del Proxy de servicio extensible (ESP) que se envió con la versión Beta inicial de Endpoints para Cloud Functions y Cloud Run.

En este documento, se describe cómo migrar una implementación existente de una API de Endpoints para Cloud Functions o Cloud Run de ESP a la versión Beta de ESPv2.

En este documento, también se describen dos problemas que debes tener en cuenta antes de migrar tus API:

Migra tus API de Endpoints para usar ESPv2 Beta

Para migrar tus API a ESPv2 Beta, solo debes compilar tu configuración de servicio de API existente en una nueva imagen de Docker de ESPv2 y, luego, implementar la imagen. Para migrar tus API, consulta estas páginas:

No es necesario que modifiques las especificaciones de la API ni el servicio de backend, a menos que tengas que solucionar cualquier problema descrito en las Notas de la versión o controlar cualquier otro problema de migración que se describe a continuación.

Actualiza la variable que se usa para especificar las opciones de inicio

Para especificar las opciones de inicio en el ESP, puedes configurar la variable de entorno ESP_ARGS.

Con ESPv2 Beta, usas el mismo mecanismo para configurar opciones de inicio, pero la variable de entorno ahora se llamará ESPv2_ARGS. Consulta las Opciones de inicio del proxy de servicio extensible V2 Beta a fin de obtener más información sobre la configuración ESPv2_ARGS y las opciones disponibles para la configuración ESPv2_ARGS.

Controla JWT en el servicio de backend

Cuando se usan JWT para realizar la autenticación, el ESP suele reenviar todos los encabezados que recibe. Sin embargo, el ESP puede anular el encabezado original Authorization cuando la dirección de backend se especifique mediante x-google-backend en la especificación de OpenAPI o BackendRule en la configuración del servicio de gRPC. Si una solicitud tiene el encabezado Authorization, su valor se copiará en un encabezado X-Forwarded-Authorization nuevo si el ESP necesita sobrescribirlo.

Ambos proxies envían el resultado de la autenticación en X-Endpoint-API-UserInfo a la API de backend. Se recomienda usar este encabezado en lugar del encabezado Authorization original. Sin embargo, el formato del encabezado es diferente.

En el ESP, el encabezado X-Endpoint-API-UserInfo contiene un objeto JSON codificado en Base64 que incluye la carga útil de JWT y campos adicionales agregados por el ESP.

Si está disponible en el JWT, el ESP agrega las propiedades id, issuer, email y audiences al objeto JSON codificado. También agrega la propiedad claims que incluye la carga útil original del JWT. El objeto JSON tiene el siguiente formato:

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

Consulta Usa un método personalizado para autenticar usuarios y Autenticación entre servicios a fin de obtener más información sobre el uso de JWT con autenticación.

El ESPv2 Beta establece el encabezado X-Endpoint-API-UserInfo de manera diferente al ESP. Con el ESPv2 Beta, el encabezado X-Endpoint-API-UserInfo solo contiene la carga útil codificada en Base64 del JWT original sin modificaciones.

Si tu servicio de backend espera que el encabezado X-Endpoint-API-UserInfo use la representación del ESP, debes actualizar tu servicio para usar este formato nuevo.

Qué sigue

Más información sobre: