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. El ESPv2 Beta reemplaza al proxy de servicio extensible (ESP) basado en NGINX.

En este documento, se describe cómo migrar una implementación existente de la API de Endpoints desde el ESP a ESPv2 Beta.

Antes de comenzar

Antes de comenzar la migración, considera los casos de uso no compatibles y rompe los cambios de la API que se describen a continuación.

Casos de uso no compatibles de ESPv2 Beta

  • El entorno flexible de App Engine no es compatible

    El entorno flexible de App Engine tiene compatibilidad con Endpoints integrada que se habilita mediante la configuración de endpoints_api_service en el archivo app.yaml de la aplicación. Esta implementación integrada de Endpoints solo admite el ESP. No se puede migrar a ESPv2 Beta.

    Si quieres usar ESPv2 Beta con el entorno flexible de App Engine, inhabilita endpoints_api_service en app.yaml. Puedes implementar el ESPv2 Beta como un servicio independiente de Cloud Run que se usa para administrar tu aplicación en el entorno flexible de App Engine. La implementación funciona de la misma manera que ESPv2 Beta se usa para admitir el entorno estándar de App Engine.

  • La configuración de NGINX personalizada no es compatible

    El ESPv2 Beta es un proxy basado en Envoy. No puede admitir una configuración personalizada de proxy NGINX. Si tu configuración del ESP usa las marcas -n o --nginx_config, tu implementación puede depender de una configuración NGINX personalizada que no se pueda migrar fácilmente a ESPv2 Beta.

Cambios rotundos

  • Se cambió el formato de datos del encabezado X-Endpoint-API-UserInfo. Si tu aplicación usa este encabezado, se debe cambiar para que use el formato nuevo. Consulta Maneja JWT en el servicio de backend para conocer más detalles.
  • Si se requiere una clave de API para una solicitud, el ESP envía el encabezado X-Endpoint-API-Project-ID con el ID del proyecto del consumidor a la aplicación de backend. El ESPv2 Beta usa dos encabezados diferentes,X-Endpoint-API-Consumer-Type y X-Endpoint-API-Consumer-Number, para enviar los detalles requeridos. Consulta la documentación de referencia de Service Infrastructure para obtener más detalles sobre Consumer-Type y Consumer-Number enviados con estos encabezados.

  • Se cambia el formato del cuerpo de la respuesta de error HTTP. Cuando el ESPv2 Beta rechaza una solicitud HTTP, genera un cuerpo de respuesta de error en un formato nuevo. Si tu implementación usa código de cliente para procesar el cuerpo de respuesta JSON de error HTTP, el código de cliente debe actualizarse. Consulta el cuerpo de respuesta JSON de error HTTP para obtener más detalles.

  • Se encuentran disponibles nuevas marcas de inicio y algunas marcas ESP están obsoletas o se reemplazaron en ESPv2 Beta. Consulta Cambios en la marca de inicio entre ESP y ESPv2 Beta.

Migra tus API de Endpoints para usar ESPv2 Beta

Los pasos de migración necesarios para usar el ESPv2 Beta con plataformas sin servidores (Cloud Run, Cloud Functions, App Engine) difieren de los pasos necesarios para las plataformas sin servidores (Google Kubernetes Engine, Compute Engine y Kubernetes).

A continuación, se describen los pasos de migración necesarios para cada tipo de plataforma:

Plataformas sin servidores: GKE, Compute Engine, Kubternetes

El ESPv2 Beta es un reemplazo directo del ESP. Para la mayoría de las configuraciones, solo debe actualizar a la etiqueta de imagen de Docker.

Sin embargo, es posible que debas ajustar las marcas de inicio si configuraste el ESP con lo siguiente:

  • Más de un puerto a través de las marcas --http_port, http2_port o --ssl_port.
  • El SSL, DNS, Client IP o alguna otra marca de uso poco frecuente.

Hay disponibles nuevas marcas de inicio para ESPv2 Beta y algunas de ellas ya no están disponibles o fueron reemplazadas. Para obtener más detalles, consulta Cambios en la marca de inicio entre ESP y ESPv2 Beta.

GKE y Kubernetes

A fin de migrar las configuraciones de Endpoints para GKE y Kubernetes, cambia la etiqueta de imagen del ESP de :1 a :2 en el archivo yaml de implementación. Por ejemplo:

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--http_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed",
  ]

Compute Engine

Tanto ESP como ESPv2 Beta se implementan en el contenedor de Docker con el comando docker run. Para migrar Endpoints para Compute Engine a ESPv2 Beta, actualiza la etiqueta de imagen de Docker de :1 a :2 en el comando. Por ejemplo:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

Plataformas sin servidores (Cloud Run, Cloud Functions, App Engine)

En el caso de las plataformas sin servidores, el ESPv2 Beta se implementa como un servicio de Cloud Run para administrar la aplicación que se ejecuta en Cloud Run, Cloud Function o App Engine. Para migrar Endpoints a ESPv2 Beta, debes compilar tu configuración de servicio de Endpoints existente en una nueva imagen de Docker de ESPv2 Beta y, luego, implementar la imagen en tu servicio de Cloud Run de ESPv2 Beta.

Los pasos de implementación para el ESP y ESPv2 Beta son idénticos, excepto por los siguientes detalles:

  • La etiqueta de imagen debe cambiarse de :1 a :2 en el ESPv2 Beta cuando implementas ESPv2 Beta en Cloud Run. Por ejemplo:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/endpoints-release/endpoints-runtime-serverless:2" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESP_PROJECT_ID
    
  • La secuencia de comandos de gcloud_build_image se descarga desde una ubicación diferente. Usa gcr.io/endpoints-release/endpoints-runtime-serverless:2 como la imagen base.

  • Se usa una variable de entorno para especificar marcas de inicio. El nombre de variable para ESP es ESP_ARGS. El nombre de ESPv2 Beta es ESPv2_ARGS. Consulta las Opciones de inicio del proxy de servicio extensible V2 Beta para obtener más información sobre cómo configurar ESPv2_ARGS y las marcas de inicio disponibles.

Cambios en la marca de inicio entre ESP y ESPv2 Beta

Al igual que con el proxy de servicio extensible, puedes especificar marcas de configuración cuando implementas servicios de ESPv2. Debido al cambio del ESP basado en NGINX por el ESPv2 Beta basado en Envoy, algunas marcas se dieron de baja o se reemplazaron, y se agregaron marcas nuevas. En esta sección, se usan tres tablas para describir los cambios:

  • En la tabla 1, se describen las marcas nuevas que reemplazan a las marcas obsoletas.
  • En la Tabla 2, se describen las marcas nuevas.
  • En la tabla 3, se describen las marcas obsoletas.

Marcas reemplazadas

Marcas nuevas Marcas reemplazadas Descripción
--listener_port --http_port, --http2_port, --ssl_port Un único puerto de escucha de Envoy admite http, http2 y ssl en el ESPv2 Beta. No es necesario especificar puertos diferentes.
--ssl_server_cert_path --ssl_port Cuando se usa --ssl_server_cert_path, el ESPv2 Beta usa certificados de server.key y archivos server.crt. Con el ESPv2 Beta, puedes especificar rutas de acceso a certificados del servidor que no sean /etc/nginx/ssl. Esta marca reemplaza a --ssl_port en el ESP, que usa certificados de las rutas de acceso a archivos /etc/nginx/ssl/nginx.key y /etc/nginx/ssl/nginx.crt.
--ssl_backend_client_cert_path --tls_mutual_auth, --enable_grpc_backend_ssl, --grpc_backend_ssl_private_key_file, --grpc_backend_ssl_cert_chain_file Cuando se usa --ssl_backend_client_cert_path, el ESPv2 Beta usa certificados de client.key y archivos client.crt. Con el ESPv2 Beta, puedes especificar rutas de certificación de cliente distintas de /etc/nginx/ssl. Esta marca reemplaza a --tls_mutual_auth en el ESP, que usa certificados de las rutas de acceso a archivos /etc/nginx/ssl/backend.key y /etc/nginx/ssl/backend.crt.
--ssl_backend_client_root_certs_file --grpc_backend_ssl_root_certs_file Con ESPv2 Beta, --ssl_backend_client_root_certs_file funciona para todos los backends. Esta marca reemplaza a --grpc_backend_ssl_root_certs_file en el ESP, que solo funciona para backends de gRPC.
--ssl_minimum_protocol,--ssl_maximum_protocol --ssl_protocols Cuando uses --ssl_protocols en el ESP, debes enumerar todos los protocolos ssl deseados. En el ESPv2 Beta, puedes especificar un protocolo mínimo y máximo.
--envoy_use_remote_address,--envoy_xff_num_trusted_hops --xff_trusted_proxy_list,--client_ip_header,--client_ip_position Envoy requiere use_remote_address y xff_num_trusted_hops para configurar la extracción de IP del cliente.
--dns_resolver_addresses --dns La marca de reemplazo tiene el mismo comportamiento, pero un valor predeterminado diferente. El ESP usa 8.8.8.8 como agente de resolución de DNS. El ESPv2 Beta usa el agente de resolución de DNS configurado en /etc/resolv.conf.

Marcas nuevas

Marcas nuevas Descripción
--http_request_timeout_s Establece el tiempo de espera para todas las llamadas remotas de http/https, excepto las llamadas de backend y las llamadas del Control de servicios de Google, en segundos.
--service_control_check_timeout_ms Establece el tiempo de espera para las llamadas de Verificación de control de servicio de Google, en milisegundos.
--service_control_report_timeout_ms Establece el tiempo de espera para las llamadas al Informe de control de servicio de Google.
--service_control_quota_timeout_ms Configura el tiempo de espera para las llamadas a la cuota de control de servicio de Google.
--service_control_check_retries Especifica el número de reintento para las llamadas de Control del control de servicios de Google.
--service_control_report_retries Especifica el número de reintento para las llamadas del Informe del control de servicios de Google.
--service_control_quota_retries Especifica el número de reintento para las llamadas de cuota del control de servicios de Google.
--backend_dns_lookup_family La configuración específica de Envoy que se usa para definir la familia de búsqueda de DNS para todos los backends.
--disable_tracing Una marca general que se usa para inhabilitar todos los seguimientos.
--tracing_project_id Se usa para configurar el ID del proyecto que posee los datos de seguimiento.
--tracing_incoming_context se usa para especificar el contexto de seguimiento entrante.
--tracing_outgoing_context Se usa para especificar el contexto de seguimiento saliente.

Marcas obsoletas

Marcas obsoletas Descripción
--enable_websocket Websocket está habilitado de forma predeterminada en Envoy.
--experimental_proxy_backend_host_header No compatible.
--allow_invalid_headers No compatible. Esta es una configuración de NGINX: ignore_invalid_headers. Si una solicitud HTTP tiene nombres de encabezado no válidos, el ESPv2 Beta rechazará. Los nombres de encabezado válidos están compuestos por letras, dígitos, guiones y guiones bajos de inglés. En el ESPv2 Beta, la marca --underscores_in_headers determina si se permiten guiones bajos en los encabezados.
--client_max_body_size La configuración de NGINX, que no es compatible.
--client_body_buffer_size La configuración de NGINX, que no es compatible.
--large_client_header_buffers La configuración de NGINX, que no es compatible.
--keepalive_timeout La configuración de NGINX, que no es compatible.
--client_body_timeout La configuración de NGINX, que no es compatible.
--rewrite No compatible.
--experimental_enable_multiple_api_configs No compatible.
--enable_backend_routing No es necesario. El enrutamiento del backend se habilita automáticamente para las plataformas sin servidores.
--rollout_fetch_throttle_window_in_s No es necesario.
--nginx_config No compatible.

Consulta las opciones de inicio del proxy de servicio extensible V2 Beta para obtener más detalles sobre las marcas de inicio del ESPv2 Beta. Puedes encontrar ejemplos genéricos adicionales y texto de ayuda para las marcas en el repositorio de GitHub.

Controla JWT en el servicio de backend

Cuando se usan JWT para realizar la autenticación, ambos proxies envían el resultado de la autenticación en el encabezado X-Endpoint-API-UserInfo a la API de backend. Recomendamos usar este encabezado en lugar del encabezado Authorization original, ya que el encabezado Authorization original se puede modificar en plataformas sin servidores. Sin embargo, el formato del encabezado se modificó para ESPv2 Beta.

En el ESP, el encabezado X-Endpoint-API-UserInfo contiene un objeto JSON codificado en Base64Url que contiene la carga útil de JWT y algunos campos específicos que agrega el ESP.

Si está disponible en el JWT, el ESP agrega los valores de 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
   }
}

En el ESPv2 Beta, el encabezado X-Endpoint-API-UserInfo solo contiene la carga útil codificada en Base64Url del JWT original, sin modificaciones.

Si tu servicio de backend espera que el encabezado X-Endpoint-API-UserInfo use el formato JSON del ESP, debes actualizar tu servicio para controlar el formato nuevo y simplificado.

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.

Formato de cuerpo de respuesta JSON de error

Si el ESP o ESPv2 Beta rechaza una solicitud HTTP, el cuerpo de la respuesta contiene un código de estado y un mensaje de error en formato JSON. El formato del cuerpo de la respuesta cambió en ESPv2 Beta, como se muestra en los siguientes ejemplos:

El cuerpo de la respuesta de error del ESP

{
 "code": 5,
 "message": "Method does not exist.",
 "details": [
  {
   "@type": "type.googleapis.com/google.rpc.DebugInfo",
   "stackEntries": [],
   "detail": "service_control"
  }
 ]
}

Cuerpo de respuesta de error de ESPv2 Beta

{
 "code": 400,
 "message": "Method does not exist.",
}

Existen dos diferencias principales:

  • En el ESPv2 Beta, el campo code contiene un código de estado http, en lugar de un código de estado de RPC que se encuentra en el ESP.
  • El cuerpo de la respuesta de error en el ESPv2 Beta no contiene un campo details.

¿Qué sigue?

Más información sobre: