Migrer vers Extensible Service Proxy V2

Extensible Service Proxy v2 (ESPv2) est un proxy basé sur Envoy qui permet à Cloud Endpoints de fournir des fonctionnalités de gestion des API. ESPv2 remplace le proxy Extensible Service Proxy (ESP) basé sur NGINX.

Ce document explique comment migrer un déploiement d'API Endpoints existant d'ESP vers ESPv2.

Avant de commencer

Avant de commencer la migration, tenez compte des cas d'utilisation non compatibles et des modifications majeures de l'API décrites ci-dessous.

Cas d'utilisation non compatibles avec ESPv2

• L'environnement flexible App Engine n'est pas compatible

  L'environnement flexible App Engine est doté d'une compatibilité avec Endpoints intégrée et activée en définissant endpoints_api_service dans le fichier app.yaml de l'application. Cette compatibilité avec Endpoints intégrée ne prend en charge qu'ESP ; il n'est pas possible de la faire migrer vers ESPv2.

  Si vous souhaitez utiliser ESPv2 avec l'environnement flexible App Engine, désactivez endpoints_api_service dans app.yaml. Vous pouvez déployer ESPv2 en tant que service Cloud Run distinct utilisé pour gérer votre application dans l'environnement flexible App Engine. Le déploiement fonctionne de la même manière que l'utilisation d'ESPv2 avec l'environnement standard App Engine.

• La configuration NGINX personnalisée n'est pas compatible

  ESPv2 est un proxy basé sur Envoy. Il n'est pas compatible avec la configuration de proxy NGINX personnalisée. Si votre configuration ESP utilise les options -n ou --nginx_config, votre mise en œuvre peut reposer sur une configuration NGINX personnalisée et difficile à migrer vers ESPv2.

Modifications importantes

• Le format de données d'en-tête X-Endpoint-API-UserInfo a été modifié. Si votre application utilise cet en-tête, vous devez le modifier pour utiliser le nouveau format. Pour en savoir plus, consultez la section Gérer les jetons JWT dans le service de backend.

• Si une clé API est requise pour une requête, ESP envoie l'en-tête X-Endpoint-API-Project-ID avec l'ID du projet client à l'application backend. ESPv2 utilise deux en-têtes différents, X-Endpoint-API-Consumer-Type et X-Endpoint-API-Consumer-Number, pour envoyer les détails requis. Pour en savoir plus sur les Consumer-Type et les Consumer-Number envoyés avec ces en-têtes, consultez la documentation de référence de l'infrastructure de service.

• Le format du corps de la réponse d'erreur HTTP a été modifié. Lorsque ESPv2 rejette une requête HTTP, il génère un corps de réponse d'erreur dans un nouveau format. Si votre mise en œuvre utilise du code client pour traiter le corps de la réponse JSON de l'erreur HTTP, ce code client doit être mis à jour. Pour en savoir plus, consultez la section Corps de réponse JSON d'une erreur HTTP.

• De nouvelles options de démarrage sont disponibles, et certaines options d'ESP ont été abandonnées ou remplacées dans ESPv2. Consultez la section Différences entre les options de démarrage d'ESP et d'ESPv2.

Migrer vos API Endpoints pour utiliser ESPv2

La procédure de migration requise pour utiliser ESPv2 avec des plates-formes sans serveur (Cloud Run, fonctions Cloud Run et App Engine) diffère de celle qui est requise pour les plates-formes autres que sans serveur (Google Kubernetes Engine, Compute Engine et Kubernetes).

La procédure de migration requise pour chaque type de plate-forme est décrite ci-dessous :

Plates-formes autres que sans serveur : GKE, Compute Engine, Kubernetes

ESPv2 êta est une option de remplacement pour ESP. Pour la plupart des configurations, il vous suffit de passer au tag d'image Docker.

Toutefois, vous devrez peut-être ajuster vos options de démarrage si vous avez configuré ESP avec les éléments suivants :

• plusieurs ports via les options --http_port, http2_port et/ou --ssl_port ;
• SSL, DNS, Client IP ou une autre option rarement utilisée.

De nouveaux indicateurs de démarrage sont disponibles pour ESPv2, et certaines options d'ESP ont été abandonnées ou remplacées. Pour en savoir plus, consultez la section Différences entre les options de démarrage d'ESP et d'ESPv2.

GKE et Kubernetes

Pour migrer les configurations Endpoints pour GKE et Kubernetes, remplacez le tag d'image ESP :1 par :2 dans le fichier de déploiement yaml. Exemple :

- 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",
  ]

Instance

ESP et ESPv2 sont déployés dans le conteneur Docker à l'aide de la commande docker run. Pour migrer des points de terminaison Endpoints pour Compute Engine vers ESPv2, mettez à jour le tag d'image Docker de :1 par :2 dans la commande. Exemple :

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

Plates-formes sans serveur (Cloud Run, Cloud Functions, App Engine)

Dans le cas des plates-formes sans serveur, ESPv2 est déployé en tant que service Cloud Run pour gérer une application s'exécutant sur Cloud Run, Cloud Functions ou App Engine. Pour migrer Endpoints vers ESPv2, vous devez créer la configuration de votre service Endpoints existant dans une nouvelle image Docker ESPv2 bêta, puis déployer cette image sur votre service ESPv2 Cloud Run.

Les étapes de déploiement d'ESP et d'ESPv2 sont identiques, à l'exception des détails suivants :

• Le tag d'image doit passer de :1 à :2 dans ESPv2 lorsque vous déployez ESPv2 dans Cloud Run. Exemple :

  gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/endpoints-release/endpoints-runtime-serverless:2" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESP_PROJECT_ID  

• Le script gcloud_build_image est téléchargé à partir d'un autre emplacement. Il utilise gcr.io/endpoints-release/endpoints-runtime-serverless:2 comme image de base.

• Une variable d'environnement permet de spécifier des options de démarrage. Pour ESP, le nom de cette variable est ESP_ARGS. Le nom d'ESPv2 est ESPv2_ARGS. Pour en savoir plus sur la définition de ESPv2_ARGS et sur les options de démarrage disponibles, consultez la page Options de démarrage d'Extensible Service Proxy v2.

Différences entre les options de démarrage d'ESP et d'ESPv2

Comme pour Extensible Service Proxy, vous pouvez spécifier des options de configuration lors du déploiement des services ESPv2. Avec le passage d'ESP basé sur NGINX à ESPv2 basé sur Envoy, certaines options sont désormais obsolètes ou remplacées, et de nouvelles options ont été ajoutées. Cette section présente ces modifications en trois tableaux :

• Le tableau 1 présente les nouvelles options qui remplacent les options obsolètes.
• Le tableau 2 présente les nouvelles options.
• Le tableau 3 présente les options obsolètes.

Options remplacées

Nouvelles options

Options obsolètes

Pour en savoir plus sur les options de démarrage ESPv2, consultez la page Options de démarrage d'Extensible Service Proxy V2. Des exemples génériques supplémentaires et du texte d'aide pour les options sont disponibles sur le dépôt GitHub.

Emplacements JWT par défaut

Par défaut, un jeton JWT est transmis dans l'en-tête Authorization (préfixé par "Bearer"), l'en-tête X-Goog-Iap-Jwt-Assertion ou le paramètre de requête access_token. Ces emplacements sont compatibles avec ESP et ESPv2. Vous pouvez également transmettre un jeton JWT dans l'en-tête Authorization (aucun préfixe) lorsque vous utilisez ESP. Toutefois, cet emplacement n'est pas compatible avec ESPv2.

Si vous souhaitez continuer à transmettre des jetons JWT à l'aide de l'en-tête Authorization (aucun préfixe) après la migration vers ESPv2, vous pouvez :

• Définir x-google-jwt-locations dans votre fichier OpenAPI (pour les utilisateurs de backends HTTP) :

x-google-jwt-locations:
- header: "Authorization"

• Définissez Authentication.providers.jwt_locations dans votre fichier yaml gRPC (pour les utilisateurs de backends gRPC) :

jwt_locations:
- header: Authorization

Gérer les jetons JWT dans le service de backend

Lorsque vous utilisez des jetons JWT pour effectuer une authentification, ESPv2 et ESP envoient le résultat d'authentification dans l'en-tête X-Endpoint-API-UserInfo à l'API backend. Nous vous recommandons d'utiliser cet en-tête à la place de l'en-tête d'origine Authorization, car l'en-tête Authorization peut être modifié sur les plates-formes sans serveur.

L'en-tête X-Endpoint-API-UserInfo contient un objet JSON encodé en Base64Url. Cependant, son format a été modifié d'ESP en ESPv2.

Pour ESPv2, l'en-tête X-Endpoint-API-UserInfo contient la charge utile JWT d'origine, sans aucune modification.

Dans ESP, l'en-tête X-Endpoint-API-UserInfo contient la charge utile JWT et quelques champs spécifiques ajoutés par ESP. ESP ajoute les champs id, issuer, email et audiences à l'objet JSON. Il ajoute également le champ claims pour inclure la charge utile JWT d'origine.

# ESPv1 X-Endpoint-API-UserInfo header value
{
  "id": "extracted from 'sub' field",
  "issuer": "extracted from 'iss' field",
  "email": "extracted from 'email' field",
  # The following "audiences" is extracted from 'aud' field.
  # The 'aud' field may have multiple audiences delimited by coma. e.g. "aud: aud1,aud2".
  # but the following "audiences" is always a JSON array.
  "audiences": ["aud1", "aud2"],
  "claims": {
     Original JWT payload
   }
}

L'exemple suivant illustre les différences. Tous ont été décodés en base64url.

# This is an example of the original JWT payload:
{
  &quotiss&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotsub&quot: &quot1234567890123456789&quot,
  &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
  &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
  &quotbar&quot: &quotbar.bar.bar.bar&quot,
  &quotazp&quot: &quot98765432109876543210&quot,
  &quotexp&quot: &quot1642809446&quot,
  &quotiat&quot: &quot1642805846&quot
}

# This is an example of the `X-Endpoint-API-UserInfo` header from ESPv2
# extracted from above JWT payload.
{
  &quotiss&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotsub&quot: &quot1234567890123456789&quot,
  &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
  &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
  &quotbar&quot: &quotbar.bar.bar.bar&quot,
  &quotazp&quot: &quot98765432109876543210&quot,
  &quotexp&quot: &quot1642809446&quot,
  &quotiat&quot: &quot1642805846&quot
}

# This is an example of the `X-Endpoint-API-UserInfo` header from ESP
# extracted from above JWT payload.
{
  &quotid&quot:&quot1234567890123456789&quot,
  &quotissuer&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotaudiences&quot: [
    &quotxyz1.example.com&quot
    &quotxyz2.example.com&quot
  ],
  &quotclaims&quot: {
    &quotiss&quot: &quothttps://accounts.google.com&quot,
    &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
    &quotsub&quot: &quot1234567890123456789&quot,
    &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
    &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
    &quotbar&quot: &quotbar.bar.bar.bar&quot,
    &quotazp&quot: &quot98765432109876543210&quot,
    &quotexp&quot: &quot1642809446&quot,
    &quotiat&quot: &quot1642805846&quot
  }
}

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.

Format du corps de la réponse JSON d'erreur

Si une requête HTTP est rejetée par ESP ou ESPv2, le corps de la réponse contient un code d'état et un message d'erreur au format JSON. Le format du corps de la réponse a été modifié dans ESPv2, comme indiqué dans les exemples ci-dessous :

Corps de réponse d'erreur d'ESP

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

Corps de la réponse d'erreur d'ESPv2

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

Il y a deux différences principales :

• Dans ESPv2, le champ code contient un code d'état HTTP au lieu du code d'état RPC utilisé par ESP.
• Le corps de la réponse d'erreur dans ESPv2 ne contient pas de champ details.

Étape suivante

Apprenez-en davantage sur les points suivants :

• Options de démarrage d'Extensible Service Proxy v2
• les extensions OpenAPI.
• Le dépôt ESPv2 sur GitHub