Migrer vers Extensible Service Proxy V2 Bêta

Extensible Service Proxy v2 bêta (ESPv2 bêta) est un proxy basé sur Envoy qui permet à Cloud Endpoints de fournir des fonctionnalités de gestion des API. ESPv2 Bêta remplace l'Extensible Service Proxy (ESP) fourni avec la version bêta initiale d'Endpoints pour Cloud Functions et Cloud Run.

Ce document explique comment migrer un déploiement existant d'une API Endpoints pour Cloud Functions ou Cloud Run avec ESP et avec ESPv2 bêta.

Ce document décrit également deux problèmes que vous devez prendre en compte avant de migrer vos API :

Migrer vos API Endpoints pour utiliser ESPv2 bêta

Pour migrer vos API vers la version ESPv2 bêta, il vous suffit de créer la configuration de service de l'API existante dans une nouvelle image Docker ESPv2 bêta, puis de déployer l'image. Pour migrer vos API, consultez les pages suivantes :

Vous n'avez pas besoin de modifier les spécifications de l'API ni le service de backend, sauf si vous devez contourner les problèmes décrits dans les notes de version ou gérer les autres problèmes de migration décrits ci-dessous.

Mettre à jour la variable utilisée pour spécifier les options de démarrage

Pour spécifier les options de démarrage dans ESP, vous pouvez définir la variable d'environnement ESP_ARGS.

Dans ESPv2 bêta, vous utilisez le même mécanisme pour définir les options de démarrage, mais la variable d'environnement s'appelle désormais ESPv2_ARGS. Pour plus d'informations sur la définition de ESPv2_ARGS et sur les options disponibles pour définir ESPv2_ARGS, reportez-vous à la section Options de démarrage d'Extensible Service Proxy v2 bêta.

Gérer les jetons JWT dans le service de backend

Lorsque vous utilisez des jetons JWT pour effectuer une authentification, ESP transfère généralement tous les en-têtes reçus. Cependant, ESP peut remplacer l'en-tête Authorization d'origine lorsque l'adresse de backend est spécifiée par x-google-backend dans la spécification OpenAPI ou par BackendRule dans la configuration du service gRPC. Si une requête contient un en-tête Authorization, sa valeur est copiée dans un nouvel en-tête X-Forwarded-Authorization si ESP doit la remplacer.

Les deux proxys envoient le résultat d'authentification dans le fichier X-Endpoint-API-UserInfo à l'API backend. Il est recommandé d'utiliser cet en-tête à la place de l'en-tête Authorization d'origine. Cependant, le format de l'en-tête est différente.

Dans ESP, l'en-tête X-Endpoint-API-UserInfo contient un objet JSON encodé en base64Url qui inclut la charge utile du JWT, ainsi que des champs supplémentaires ajoutés par ESP.

Lorsqu'il est disponible dans le jeton JWT, ESP ajoute les propriétés id, issuer, email et audiences à l'objet JSON encodé. Il ajoute également la propriété claims qui inclut la charge utile d'origine du jeton JWT. L'objet JSON se présente sous la forme suivante :

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

Pour en savoir plus sur l'utilisation des jetons JWT pour l'authentification, consultez les pages Utiliser une méthode personnalisée pour authentifier les utilisateurs et Authentification entre les services.

ESPv2 bêta définit l'en-tête X-Endpoint-API-UserInfo différemment d'ESP. Dans ESPv2 bêta, l'en-tête X-Endpoint-API-UserInfo contient uniquement la charge utile encodée en base64 du jeton JWT d'origine sans modification.

Si votre service de backend s'attend à ce que l'en-tête X-Endpoint-API-UserInfo utilise la représentation ESP, vous devez mettre à jour votre service pour utiliser ce nouveau format.

Étape suivante

Apprenez-en davantage sur :