Utiliser Spring Cloud Gateway

  • Article

Remarque

Azure Spring Apps est le nouveau nom du service Azure Spring Cloud. Bien que le service ait un nouveau nom, vous verrez l’ancien nom à divers endroits pendant un certain temps, car nous travaillons à mettre à jour les ressources telles que les captures d’écran, les vidéos et les diagrammes.

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

Cet article explique comment utiliser VMware Spring Cloud Gateway avec le plan Azure Spring Apps Enterprise pour acheminer les demandes vers vos applications.

VMware Spring Cloud Gateway est un composant VMware Tanzu commercial basé sur le projet open source Spring Cloud Gateway. Spring Cloud Gateway 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, la sécurité, etc. Vous pouvez accélérer la livraison des API à l’aide de modèles modernes natifs Cloud et de n’importe quel langage de programmation pour le développement d’API.

Spring Cloud Gateway propose les fonctionnalités suivantes :

  • Configuration du routage dynamique, indépendamment des applications individuelles qui peuvent être appliquées et modifiées sans recompilation.
  • Filtres d’itinéraires d’API commerciales pour le transport des revendications JWT (JSON Web Token) autorisées vers les services d’application.
  • Autorisation de certificat client.
  • Approches de limitation du débit.
  • Configuration du disjoncteur.
  • Prise en charge de l’accès aux services d’application via les informations d’identification d’authentification HTTP de base.

Pour s’intégrer au portail d’API pour VMware Tanzu, VMware Spring Cloud Gateway génère automatiquement la documentation OpenAPI version 3 après les ajouts ou modifications de configuration de routage.

Prérequis

Configurer des itinéraires

Cette section explique comment ajouter, mettre à jour et gérer des routes d’API pour les applications qui utilisent Spring Cloud Gateway.

La définition de configuration des routes comprend les éléments suivants :

  • URI OpenAPI : cet URI fait référence à une spécification OpenAPI. Vous pouvez utiliser un point de terminaison d’URI public tel que https://petstore3.swagger.io/api/v3/openapi.json ou un URI construit tel que http://<app-name>/{relative-path-to-OpenAPI-spec}, où <app-name> est le nom d’une application dans Azure Spring Apps qui inclut la définition d’API. Les spécifications OpenAPI 2.0 et OpenAPI 3.0 sont prises en charge. La spécification s’affiche dans le portail d’API si elle est activée.
  • routes : une liste de règles d’itinéraire pour diriger le trafic vers les applications et appliquer des filtres.
  • Protocole : protocole principal de l’application vers laquelle Spring Cloud Gateway achemine le trafic. Les valeurs prises en charge du protocole sont HTTP ou HTTPS, et la valeur par défaut est HTTP. Pour sécuriser le trafic de Spring Cloud Gateway vers votre application compatible HTTPS, vous devez définir le protocole sur HTTPS dans votre configuration de routage.
  • routes au niveau de l’application : il existe trois propriétés de routage que vous pouvez configurer au niveau de l’application pour éviter des répétitions sur la totalité ou la plupart des routes dans la configuration des routes. La règle de routage concrète remplace la règle de routage au niveau de l’application pour la même propriété. Vous pouvez définir les propriétés suivantes au niveau de l’application : predicates, filters et ssoEnabled. Si vous utilisez la fonctionnalité OpenAPI URI pour définir des routes, la seule propriété de routage au niveau de l’application à prendre en charge est filters.

Utilisez la commande suivante pour créer une configuration de routage. La --app-name valeur doit être le nom d’une application hébergée dans Azure Spring Apps vers laquelle les demandes sont acheminées.

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

L’exemple suivant montre un fichier JSON transmis au paramètre --routes-file dans la commande de création :

{
   "predicates": [
      "<app-level-predicate-of-route>",
   ],
   "ssoEnabled": false,
   "filters": [
      "<app-level-filter-of-route>",
   ],
   "openApi": {
      "uri": "<OpenAPI-URI>"
   },
   "protocol": "<protocol-of-routed-app>",
   "routes": [
      {
         "title": "<title-of-route>",
         "description": "<description-of-route>",
         "predicates": [
            "<predicate-of-route>",
         ],
         "ssoEnabled": true,
         "filters": [
            "<filter-of-route>",
         ],
         "tags": [
            "<tag-of-route>"
         ],
         "order": 0
      }
   ]
}

Le tableau suivant répertorie les définitions de routes. Toutes ces propriétés sont facultatives.

Propriété Description
title Un titre à appliquer aux méthodes dans la documentation OpenAPI générée.
description Une description à appliquer aux méthodes dans la documentation OpenAPI générée.
URI URI complet, qui remplace le nom de l’application vers laquelle les demandes sont acheminées.
ssoEnabled Une valeur qui indique s'il faut activer la validation d’authentification unique. Consultez Configurer l’authentification unique.
tokenRelay Passe le jeton d’identité de l’utilisateur actuellement authentifié à l’application.
Prédicats Liste de prédicats. Consultez Prédicats disponibles.
filtres Liste de filtres. Consultez Filtres disponibles.
order L’ordre de traitement de l’itinéraire Un ordre inférieur est traité avec une priorité plus élevée, comme dans Spring Cloud Gateway.
tags Balises de classification appliquées aux méthodes de la documentation OpenAPI générée.

Remarque

Tous les filtres ou les prédicats ne sont pas pris en charge dans Azure Spring Apps pour des raisons de sécurité et de compatibilité. Les éléments suivants ne sont pas pris en charge :

  • BasicAuth
  • JWTKey

Utilisez des itinéraires pour Spring Cloud Gateway.

Effectuez les étapes suivantes pour créer un exemple d’application à l’aide de Spring Cloud Gateway.

  1. Utilisez la commande suivante pour créer une application de test nommée test-app dans Azure Spring Apps :

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

  2. Affectez un point de terminaison public à la passerelle pour y accéder.

    Pour afficher l’état d’exécution et les ressources fournies à Spring Cloud Gateway, ouvrez votre instance d’application Azure Spring Apps dans le Portail Microsoft Azure, sélectionnez la section Spring Cloud Gateway, puis sélectionnez Vue d’ensemble.

    Sélectionnez Oui en regard de Affecter un point de terminaison pour attribuer un point de terminaison public. Une URL s’affiche en quelques minutes. Enregistrez l’URL pour l’utiliser plus tard.

    Screenshot of Azure portal Azure Spring Apps overview page with 'Assign endpoint' highlighted.

    Vous pouvez également utiliser Azure CLI pour affecter le point de terminaison. Utilisez la commande suivante pour affecter le point de terminaison.

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

  3. Créez une règle pour accéder au point de terminaison de contrôle d’intégrité de l’application de test via Spring Cloud Gateway.

    Enregistrez le contenu suivant dans un fichier test-api.json . Cette configuration inclut un filtre RateLimit, qui autorise 20 requêtes toutes les 10 secondes, et un filtre RewritePath, qui permet au point de terminaison de la requête d’atteindre le point de terminaison de contrôle d’intégrité Spring Boot standard.

    {
  "protocol": "HTTP",
  "routes": [
    {
      "title": "Test API",
      "description": "Retrieve a health check from our application",
      "predicates": [
        "Path=/test/api/healthcheck",
        "Method=GET"
      ],
      "filters": [
        "RateLimit=20,10s",
        "RewritePath=/api/healthcheck,/actuator/health"
      ],
      "tags": [
        "test"
      ]
    }
  ]
}

    Puis, utilisez la commande suivante pour appliquer la règle à l’application test-app :

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

    Vous pouvez également afficher les itinéraires dans le portail, comme illustré dans la capture d’écran suivante :

    Screenshot of Azure portal Azure Spring Apps Spring Cloud Gateway page showing 'Routing rules' pane.

  4. Utilisez la commande suivante pour accéder aux test health checkAPI par le biais du point de terminaison de passerelle :

    curl https://<endpoint-url>/test/api/healthcheck

  5. Utilisez les commandes suivantes pour interroger les règles d’acheminement :

    az spring gateway route-config show \
    --name test-api-routes \
    --query '{appResourceId:properties.appResourceId, routes:properties.routes}'

az spring gateway route-config list \
    --query '[].{name:name, appResourceId:properties.appResourceId, routes:properties.routes}'

Utiliser des filtres

Le projet open source Spring Cloud Gateway inclut de nombreux filtres intégrés à utiliser dans les itinéraires de passerelle. Spring Cloud Gateway fournit de nombreux filtres personnalisés en plus des filtres inclus dans le projet du logiciel Open Source (OSS).

L’exemple suivant montre comment appliquer le AddRequestHeadersIfNotPresent filtre à un itinéraire :

[
  {
    "predicates": [
      "Path=/api/**",
      "Method=GET"
    ],
    "filters": [
      "AddRequestHeadersIfNotPresent=Content-Type:application/json,Connection:keep-alive"
    ]
  }
]

Ensuite, appliquez la définition de route à l’aide de la commande Azure CLI suivante :

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

Pour plus d’informations sur les filtres de routage disponibles, consultez Comment utiliser les filtres de routage VMware Spring Cloud Gateway avec le plan Azure Spring Apps Enterprise.

Étapes suivantes