Configurer VMware Spring Cloud Gateway

Cet article s’applique à :❌ De base/Standard ✔️ Entreprise

Cet article montre comment configurer VMware Spring Cloud Gateway pour VMware Tanzu avec le plan Entreprise Azure Spring Apps.

VMware Spring Cloud Gateway est un composant VMware Tanzu commercial basé sur le projet open source Spring Cloud Gateway. VMware Spring Cloud Gateway pour Tanzu gère les problèmes transversaux que rencontrent les équipes de développement d’API, comme l’authentification unique (SSO), le contrôle d’accès, la limitation du débit, la résilience et la sécurité. Vous pouvez accélérer la livraison des API en utilisant des modèles modernes natifs Cloud dans le langage de programmation de votre choix pour le développement d’API.

Une instance de VMware Spring Cloud Gateway route le trafic conformément à des règles. Elle prend en charge les opérations de scale-in/out et de scale-up/down afin de répondre aux besoins d’une charge de trafic dynamique.

VMware Spring Cloud Gateway propose les fonctionnalités suivantes :

• Configuration du routage dynamique, indépendamment des applications, que vous pouvez appliquer et modifier sans recompilation
• Filtres de routes d’API commerciales pour le transport des revendications JWT (JSON Web Token) autorisées vers des services d’application
• Autorisation de certificat client
• Approches de limitation du débit
• Configuration de disjoncteur
• Prise en charge de l’accès aux services d’application via les informations d’identification d’authentification HTTP de base

Pour son intégration au portail d’API pour VMware Tanzu, VMware Spring Cloud Gateway génère automatiquement la documentation d’OpenAPI version 3 lorsque des ajouts ou modifications sont apportées à la configuration du routage. Pour plus d’informations, consultez Utiliser le portail d’API pour VMware Tanzu.

Prérequis

• Une instance du service Azure Spring Apps de plan Entreprise déjà approvisionnée, avec VMware Spring Cloud Gateway activé. Pour plus d’informations, consultez Démarrage rapide : Générer et déployer des applications sur Azure Spring Apps à l’aide du plan Enterprise.
• Azure CLI version 2.0.67 ou ultérieure. Utilisez la commande suivante pour installer l’extension Azure Spring Apps : az extension add --name spring.

Activer ou désactiver VMware Spring Cloud Gateway

Vous pouvez activer ou désactiver VMware Spring Cloud Gateway après la création de l’instance de service à l’aide du portail Azure ou d’Azure CLI. Avant de désactiver VMware Spring Cloud Gateway, vous devez annuler l’affectation de son point de terminaison et supprimer toutes les configurations de routage.

az spring gateway create \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name>

az spring gateway delete \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name>

Redémarrer VMware Spring Cloud Gateway

Une fois l’action de redémarrage terminée, les instances de VMware Spring Cloud Gateway sont redémarrées de manière propagée.

az spring gateway restart \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name>

Affecter un point de terminaison public à VMware Spring Cloud Gateway

Cette section explique comment affecter un point de terminaison public à VMware Spring Cloud Gateway et comment configurer ses propriétés.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --assign-endpoint true

Configurer les métadonnées de VMware Spring Cloud Gateway

Les métadonnées VMware Spring Cloud Gateway génèrent automatiquement la documentation OpenAPI version 3. Vous pouvez configurer les métadonnées VMware Spring Cloud Gateway afin d’afficher les groupes de routes dans le portail d’API pour VMware Tanzu. Pour plus d’informations, consultez Utiliser le portail d’API pour VMware Tanzu.

Le tableau suivant décrit les options de métadonnées disponibles :

Vous pouvez utiliser le portail Azure ou Azure CLI pour modifier les propriétés des métadonnées.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --api-description "<api-description>" \
    --api-title "<api-title>" \
    --api-version "v0.1" \
    --server-url "<gateway-endpoint-URL>" \
    --allowed-origins "*"

Configurer l’authentification unique

VMware Spring Cloud Gateway prend en charge l’authentification et l’autorisation par le biais de l’authentification unique avec un fournisseur d’identité OpenID. Le fournisseur prend en charge le protocole OpenID Connect Discovery. Le tableau suivant décrit les propriétés d’authentification unique :

Pour configurer l’authentification unique avec Microsoft Entra ID, consultez Configurer l’authentification unique à l’aide de Microsoft Entra ID pour Spring Cloud Gateway et le portail d’API.

Vous pouvez utiliser le portail Azure ou Azure CLI pour modifier les propriétés d’authentification unique.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --client-id <client-id> \
    --client-secret <client-secret> \
    --issuer-uri <issuer-uri> \
    --scope <scope>

VMware Spring Cloud Gateway prend uniquement en charge les serveurs d’autorisation qui prennent en charge le protocole OpenID Connect Discovery. Veillez également à configurer le serveur d’autorisation externe pour autoriser la redirection vers la passerelle. Reportez-vous à la documentation de votre serveur d’autorisation et ajoutez https://<gateway-external-url>/login/oauth2/code/sso à la liste des URI de redirection autorisés.

Si vous configurez une mauvaise propriété d’authentification unique, comme un mot de passe incorrect, vous devrez supprimer l’intégralité de la propriété d’authentification unique puis ajouter la bonne configuration.

Après avoir configuré l’authentification unique, n’oubliez pas de définir ssoEnabled: true pour les routes VMware Spring Cloud Gateway.

Configurer la déconnexion de l’authentification unique

Les instances de service VMware Spring Cloud Gateway fournissent un point de terminaison d’API par défaut pour se déconnecter de la session d’authentification unique active. Le chemin d’accès à ce point de terminaison est /scg-logout. La déconnexion a l’un des résultats suivants, selon la façon dont vous appelez le point de terminaison de déconnexion :

• Déconnexion de la session et redirection vers la déconnexion du fournisseur d’identité (IdP).
• Déconnexion de la session d’instance de service.

Se déconnecter de la session IdP et SSO

Si vous envoyez une requête GET au point de terminaison /scg-logout, celui-ci envoie une réponse de redirection 302 à l’URL de déconnexion IdP. Pour faire en sorte que le point de terminaison renvoie l’utilisateur à un chemin sur l’instance de service de passerelle, ajoutez un paramètre de redirection à la requête GET avec le point de terminaison /scg-logout. Par exemple, vous pouvez utiliser ${server-url}/scg-logout?redirect=/home.

La valeur du paramètre de redirection doit être un chemin valide sur l’instance de service VMware Spring Cloud Gateway. Vous ne pouvez pas rediriger vers une URL externe.

Les étapes suivantes illustrent comment implémenter la fonction dans vos microservices :

1. Obtenez une configuration de routage afin de router la requête de déconnexion vers votre application. Pour obtenir un exemple, consultez la configuration du routage dans le dépôt animal-rescue sur GitHub.

2. Ajoutez la logique de déconnexion dont vous avez besoin à l’application. À la fin, vous avez besoin d’une requête GET au point de terminaison /scg-logout de la passerelle, comme indiqué dans la valeur return de la méthode getActionButton dans le dépôt animal-rescue.

Se déconnecter uniquement de la session d’authentification unique

Si vous envoyez la requête GET au point de terminaison /scg-logout à l’aide de XMLHttpRequest, la redirection 302 risque d’être avalée et de ne pas être gérée dans le gestionnaire de réponse. Dans ce cas, l’utilisateur serait déconnecté uniquement de la session d’authentification unique sur l’instance de service VMware Spring Cloud Gateway. Il aurait toujours une session IdP valide. En règle générale, si l’utilisateur tente de se reconnecter, il est automatiquement renvoyé à la passerelle comme authentifié à partir du fournisseur d’identité.

Vous devez disposer d’une configuration de routage afin de router la requête de déconnexion vers votre application, comme illustré dans l’exemple suivant. Ce code crée une session d’authentification unique de déconnexion de passerelle uniquement.

const req = new XMLHttpRequest();
req.open("GET", "/scg-logout);
req.send();

Configurer le partage des ressources cross-origin (CORS)

Le partage des ressources cross-origin (CORS) permet aux ressources limitées d’une page web d’être demandées à partir d’un domaine autre que celui à partir duquel la première ressource a été fournie. Le tableau suivant décrit les options de configuration CORS disponibles.

Vérifiez que vous disposez de la bonne configuration CORS si vous souhaitez procéder à une intégration au portail d’API. Pour plus d’informations, consultez la section Affecter un point de terminaison public à VMware Spring Cloud Gateway.

Utiliser la mise à l’échelle du service

Vous pouvez personnalisez l’allocation des ressources pour les instances de VMware Spring Cloud Gateway, notamment les processeurs virtuels, la mémoire et le nombre d’instances.

Pour la haute disponibilité, nous déconseillons l’utilisation d’un seul réplica.

Le tableau suivant décrit l’utilisation des ressources par défaut.

Configurer TLS entre la passerelle et les applications

Pour renforcer la sécurité et protéger les informations sensibles contre toute interception par des parties non autorisées, vous pouvez activer le protocole TLS (Transport Layer Security) entre VMware Spring Cloud Gateway et vos applications.

Avant de configurer TLS, vous devez disposer d’une application compatible TLS et d’un certificat TLS. Pour préparer un certificat TLS, générez un certificat à partir d’une autorité de certification approuvée. Le certificat vérifie l’identité du serveur et établit une connexion sécurisée.

Une fois qu’une application compatible TLS s’exécute dans Azure Spring Apps, chargez le certificat sur Azure Spring Apps. Pour plus d'informations, consultez la certification Importer un certificats de Utiliser des certificats TLS/SSL dans votre application dans Azure Spring Apps.

Avec le certificat mis à jour sur Azure Spring Apps, vous pouvez configurer le certificat TLS pour la passerelle et activer la vérification de certificat. Vous pouvez configurer le certificat dans le portail Azure ou à l’aide d’Azure CLI.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --enable-cert-verify <value> \
    --certificate-names <certificate-name-in-Azure-Spring-Apps>

Préparer la configuration du routage

Vous devez spécifier le protocole HTTPS dans la configuration du routage. L’objet JSON suivant indique à VMware Spring Cloud Gateway d’utiliser le protocole HTTPS pour tout le trafic entre la passerelle et l’application.

1. Créez un fichier nommé test-tls-route.json avec le contenu suivant :

   {
       "routes": [
         {
           "title": "Test TLS app",
           "predicates": [
             "Path=/path/to/your/app",
             "Method=GET"
           ]
         }
        ],
       "uri": "https://<app-custom-domain-name>"
   }
   

2. Utilisez la commande suivante pour appliquer la règle à l’application :

   az spring gateway route-config create \
       --resource-group <resource-group-name> \
       --service <Azure-Spring-Apps-instance-name> \
       --name test-tls-app \
       --routes-file test-tls-route.json
   

Vous pouvez maintenant tester si l’application est compatible TLS avec le point de terminaison de la passerelle. Pour plus d’informations, consultez la section Configurer des routes de Utiliser Spring Cloud Gateway.

Effectuer une rotation des certificats

À mesure que les certificats expirent, vous devez faire pivoter les certificats dans VMware Spring Cloud Gateway en effectuant ces étapes :

1. Générez de nouveaux certificats à partir d’une autorité de certification approuvée.
2. Importez les certificats dans Azure Spring Apps. Pour plus d'informations, consultez la certification Importer un certificats de Utiliser des certificats TLS/SSL dans votre application dans Azure Spring Apps.
3. Synchronisez les certificats à l’aide du portail Azure ou d’Azure CLI.

VMware Spring Cloud Gateway redémarre afin de s’assurer que la passerelle utilise le nouveau certificat pour toutes les connexions.

az spring gateway restart \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name>

Configurer les paramètres de mise à l'échelle automatique

Vous pouvez définir des modes de mise à l’échelle automatique pour VMware Spring Cloud Gateway.

az monitor autoscale create \
    --resource-group <resource-group-name> \
    --name <autoscale-setting-name> \
    --resource /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.AppPlatform/Spring/<service-instance-name>/gateways/default \
    --min-count 1 \
    --max-count 5 \
    --count 1

az monitor autoscale rule create \
    --resource-group <resource-group-name> \
    --autoscale-name <autoscale-setting-name> \
    --scale out 1 \
    --cooldown 1 \
    --condition "GatewayHttpServerRequestsSecondsCount > 100 avg 1m"

Pour plus d’informations sur les métriques disponibles, consultez la section Options de métriques de l’utilisateur dans Métriques pour Azure Spring Apps.

Configurer le cache de réponse

La configuration du cache de réponse offre un moyen de définir un cache de réponse HTTP que vous pouvez appliquer globalement ou au niveau de la route.

Activer le cache de réponse globalement

Une fois que vous avez activé le cache de réponse globalement, il est automatiquement activé pour toutes les routes applicables.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name>
    --enable-response-cache \
    --response-cache-scope Instance \
    --response-cache-size {Examples are 1GB, 100MB, 100KB} \
    --response-cache-ttl {Examples are 1h, 30m, 50s}

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --enable-response-cache false

Activer le cache de réponse au niveau de la route

Pour activer le cache de réponse pour n’importe quelle route, utilisez le filtre LocalResponseCache. L’exemple suivant montre comment utiliser le filtre LocalResponseCache dans la configuration de règle de routage :

{
   "filters": [
      "<other-app-level-filter-of-route>",
   ],
   "routes": [
      {
        "predicates": [
            "Path=/api/**",
            "Method=GET"
         ],
         "filters": [
            "<other-filter-of-route>",
            "LocalResponseCache=3m, 1MB"
         ],
      }
   ]
}

Pour plus d’informations, consultez la section LocalResponseCache de Guide pratique pour utiliser des filtres de routage VMware Spring Cloud Gateway avec le plan Entreprise Azure Spring Apps et LocalResponseCache dans la documentation VMware.

Au lieu de configurer size et timeToLive pour chaque filtre LocalResponseCache individuellement, vous pouvez définir ces paramètres au niveau de Spring Cloud Gateway. Cette option vous permet d’utiliser le filtre LocalResponseCache sans spécifier ces valeurs initialement, tout en conservant la possibilité de les remplacer ultérieurement.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --enable-response-cache \
    --response-cache-scope Route \
    --response-cache-size {Examples are 1GB, 100MB, 100KB} \
    --response-cache-ttl {Examples are 1h, 30m, 50s}

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --enable-response-cache false

L’exemple suivant montre comment utiliser le filtre LocalResponseCache quand size et timeToLive sont définis au niveau de Spring Cloud Gateway :

{
   "filters": [
      "<other-app-level-filter-of-route>",
   ],
   "routes": [
      {
        "predicates": [
            "Path=/api/path1/**",
            "Method=GET"
         ],
         "filters": [
            "<other-filter-of-route>",
            "LocalResponseCache"
         ],
      },
      {
        "predicates": [
            "Path=/api/path2/**",
            "Method=GET"
         ],
         "filters": [
            "<other-filter-of-route>",
            "LocalResponseCache=3m, 1MB"
         ],
      }
   ]
}

Configuration des variables d’environnement

Le service Azure Spring Apps gère et ajuste VMware Spring Cloud Gateway. À l’exception des cas d’usage qui configurent l’analyse des performances des applications (APM) et le niveau de journal, vous n’avez normalement pas besoin de configurer VMware Spring Cloud Gateway avec des variables d’environnement.

Si vous avez des exigences que vous ne pouvez pas satisfaire par d’autres configurations décrites dans cet article, vous pouvez essayer de configurer les variables d’environnement affichées dans la liste des propriétés d’application courantes. Veillez à vérifier votre configuration dans votre environnement de test avant de l’appliquer à votre environnement de production.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --properties <key=value> \
    --secrets <key=value>

Après la mise à jour de variables d’environnement, VMware Spring Cloud Gateway redémarre.

Configurer l’analyse des performances des applications (APM)

Pour analyser VMware Spring Cloud Gateway, vous pouvez configurer APM. Le tableau suivant répertorie les cinq types d’agents Java APM fournis par VMware Spring Cloud Gateway, ainsi que leurs variables d’environnement requises.

Pour découvrir d’autres variables d’environnement prises en charge, consultez les sources suivantes :

• Vue d’ensemble d’Application Insights
• Variables d’environnement Dynatrace
• Variables d’environnement New Relic
• Variables d’environnement AppDynamics
• Variables d’environnement Elastic

Configurer l’intégration d’APM au niveau de l’instance de service (recommandé)

Pour activer l’analyse APM dans votre instance de VMware Spring Cloud Gateway, vous pouvez créer une configuration APM au niveau de l’instance de service et la lier à Spring Cloud Gateway. Ainsi, vous pouvez configurer APM une seule fois et lier la même analyse APM à Spring Cloud Gateway et à vos applications.

Gérer APM dans VMware Spring Cloud Gateway (déprécié)

Vous pouvez utiliser le portail Azure ou Azure CLI pour configurer APM dans VMware Spring Cloud Gateway. Vous pouvez également spécifier les types d’agents Java APM à utiliser et les variables d’environnement APM correspondantes qu’ils prennent en charge.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --apm-types <APM-type> \
    --properties <key=value> \
    --secrets <key=value>

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --apm-types ApplicationInsights \
    --properties APPLICATIONINSIGHTS_CONNECTION_STRING=<your-Application-Insights-connection-string> APPLICATIONINSIGHTS_SAMPLE_RATE=10

Configurer des niveaux de journaux

Vous pouvez configurer les niveaux de journalisation de VMware Spring Cloud Gateway des manières suivantes afin d’obtenir davantage de détails ou de réduire les journaux :

• Vous pouvez définir les niveaux de journalisation sur TRACE, DEBUG, INFO, WARN, ERROR ou OFF. Le niveau de journalisation par défaut pour VMware Spring Cloud Gateway est INFO.
• Vous pouvez désactiver les journaux en définissant les niveaux de journalisation sur OFF.
• Lorsque le niveau de journalisation est défini sur WARN, ERROR ou OFF, vous devrez peut-être le régler sur INFO lors d’une demande de support technique auprès de l’équipe Azure Spring Apps. Cette modification entraîne un redémarrage de VMware Spring Cloud Gateway.
• Lorsque le niveau de journalisation est défini sur TRACE ou DEBUG, cela peut affecter les performances de VMware Spring Cloud Gateway. Essayez d’éviter ces paramètres dans votre environnement de production.
• Vous pouvez définir des niveaux de journalisation pour l’enregistreur d’événements root ou pour des enregistreurs d’événements spécifiques tels que io.pivotal.spring.cloud.gateway.

Les enregistreurs d’événements suivants peuvent contenir des informations de dépannage précieuses aux niveaux TRACE et DEBUG :

Pour obtenir des clés de variables d’environnement, ajoutez le préfixe logging.level., puis définissez le niveau de journalisation en configurant logging.level.{loggerName}={logLevel} pour l’environnement. Les exemples suivants montrent les étapes à effectuer dans le portail Azure et dans Azure CLI.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --properties \
      logging.level.root=INFO \
      logging.level.io.pivotal.spring.cloud.gateway=DEBUG \
      logging.level.org.springframework.cloud.gateway=DEBUG \
      logging.level.org.springframework.boot.autoconfigure.web=TRACE \
      logging.level.org.springframework.security.web=ERROR

Mettre à jour la configuration du module complémentaire

La fonctionnalité de configuration du module complémentaire vous permet de personnaliser certaines propriétés de VMware Spring Cloud Gateway à l’aide d’une chaîne au format JSON. Cette fonctionnalité est utile lorsque vous devez configurer des propriétés qui ne sont pas exposées par le biais de l’API REST.

La configuration du module complémentaire est un objet JSON avec des paires clé/valeur qui représentent la configuration souhaitée. L’exemple suivant montre la structure du format JSON :

{
    "<addon-key-name>": {
        "<addon-key-name>": "<addon-value>"
        ...
    },
    "<addon-key-name>": "<addon-value>",
    ...
}

La liste suivante montre les configurations de module complémentaire prises en charge pour les noms de clés et types de valeurs du module complémentaire. Cette liste est susceptible de changer à mesure que nous mettons à niveau la version de VMware Spring Cloud Gateway.

• Configuration SSO :

  • Nom de la clé : sso

  • Type de valeur : Objet

  • Propriétés :

    • RolesAttributeName (chaîne) : spécifie le nom de l’attribut qui contient les rôles associés à la session d’authentification unique.
    • InactiveSessionExpirationInMinutes (entier) : spécifie le délai d’expiration, en minutes, pour les sessions d’authentification unique inactives. La valeur 0 signifie que la session n’expire jamais.

  • Exemple :

    {
        "sso": {
            "rolesAttributeName": "roles",
            "inactiveSessionExpirationInMinutes": 1
        }
    }
    

• Configuration des métadonnées :

  • Nom de la clé : api

  • Type de valeur : Objet

  • Propriétés

    • groupId (chaîne) : identificateur unique pour le groupe d’API disponibles sur l’instance de VMware Spring Cloud Gateway. La valeur doit être composée uniquement de lettres minuscules et de chiffres.

  • Exemple :

    {
        "api": {
            "groupId": "id1"
        }
    }
    

• Configuration de pod

  • Nom de clé : PodOverrides, qui est utilisé pour spécifier des remplacements pour la configuration de pod par défaut.

  • Type de valeur : Objet

  • Propriétés

    • Containers : ce tableau contient la configuration des conteneurs individuels au sein du pod. Seul le conteneur nommé gateway est pris en charge actuellement.
      • Name : spécifie le nom du conteneur. Le conteneur doit être nommé gateway.
      • Lifecycle : PreStop est un hook de cycle de vie exécuté lorsqu’un conteneur est sur le point d’être arrêté. Ce crochet vous permet d'effectuer tout nettoyage nécessaire avant que le conteneur ne s'arrête.
    • TerminationGracePeriodSeconds : spécifie la durée pendant laquelle Kubernetes attend qu’un pod se termine correctement avant de le tuer de force.

  • Exemple :

    {
        "PodOverrides": {
            "Containers": [
                {
                    "Name": "gateway",
                    "Lifecycle": {
                        "PreStop": {
                            "Exec": {
                                "Command": [
                                    "/bin/sh",
                                    "-c",
                                    "sleep 20"
                                ]
                            }
                        }
                    }
                }
            ],
            "TerminationGracePeriodSeconds": 120
        }
    }
    

    Lorsqu’un pod contenant ce conteneur est arrêté, le hook PreStop exécute la commande /bin/sh -c 'sleep 20', ce qui entraîne le sommeil du conteneur pendant 20 secondes. Cette pause donne au conteneur le temps de terminer les tâches en cours ou de faire le ménage avant qu'il ne s'arrête réellement.

    Le paramètre TerminationGracePeriodSeconds fournit un total de 120 secondes pour que le pod se termine correctement, y compris le temps nécessaire à tous les crochets de cycle de vie, tels que PreStop.

Effectuez les étapes suivantes pour mettre à jour la configuration du module complémentaire :

Étapes suivantes

• Utiliser Spring Cloud Gateway