Usare Spring Cloud Gateway

Articolo
11/05/2024

Nota

I piani Basic, Standard ed Enterprise saranno deprecati a partire dalla metà di marzo 2025, con un periodo di ritiro di 3 anni. È consigliabile eseguire la transizione ad App Azure Container. Per altre informazioni, vedere l'annuncio di ritiro di Azure Spring Apps.

Il piano Standard a consumo e dedicato sarà deprecato a partire dal 30 settembre 2024, con un arresto completo dopo sei mesi. È consigliabile eseguire la transizione ad App Azure Container. Per altre informazioni, vedere Eseguire la migrazione del consumo di Azure Spring Apps Standard e del piano dedicato alle app Azure Container.

Questo articolo si applica a:❌ Basic/Standard ✔️ Enterprise

Questo articolo illustra come usare VMware Spring Cloud Gateway con il piano Azure Spring Apps Enterprise per instradare le richieste alle applicazioni.

VMware Spring Cloud Gateway è un componente VMware Tanzu commerciale basato sul progetto Spring Cloud Gateway open source. Spring Cloud Gateway gestisce le problematiche trasversali per i team di sviluppo di API, ad esempio Single Sign-On (SSO), il controllo di accesso, la limitazione della frequenza, la resilienza e la sicurezza, e altro ancora. È possibile accelerare il recapito delle API usando modelli nativi del cloud moderni e qualsiasi linguaggio di programmazione scelto per lo sviluppo di API.

Spring Cloud Gateway include le funzionalità seguenti:

Configurazione del routing dinamico, indipendentemente da singole applicazioni che possono essere applicate e modificate senza ricompilazione.
Filtri di route dell'API commerciale per il trasporto di attestazioni JWT (JSON Web Token) autorizzate ai servizi dell'applicazione.
Autorizzazione del certificato client.
Approcci di limitazione della frequenza.
Configurazione dell'interruttore.
Supporto per l'accesso ai servizi dell'applicazione tramite credenziali di autenticazione di base HTTP.

Per l'integrazione con il portale API per VMware Tanzu, VMware Spring Cloud Gateway genera automaticamente la documentazione openAPI versione 3 dopo eventuali aggiunte o modifiche alla configurazione della route.

Prerequisiti

Un'istanza del servizio del piano Enterprise di Azure Spring Apps già con Spring Cloud Gateway abilitata. Per altre informazioni, vedere Avvio rapido: Creare e distribuire app in Azure Spring Apps usando il piano Enterprise.
Interfaccia della riga di comando di Azure versione 2.0.67 o successiva. Usare il comando seguente per installare l'estensione Azure Spring Apps: az extension add --name spring.

Configurare le route

Questa sezione descrive come aggiungere, aggiornare e gestire le route API per le app che usano Spring Cloud Gateway.

La definizione di configurazione della route include le parti seguenti:

URI OpenAPI: questo URI fa riferimento a una specifica OpenAPI. È possibile usare un endpoint URI pubblico, https://petstore3.swagger.io/api/v3/openapi.json ad esempio o un URI costruito, http://<app-name>/{relative-path-to-OpenAPI-spec}ad esempio , dove <app-name> è il nome di un'applicazione in Azure Spring Apps che include la definizione dell'API. Sono supportate sia le specifiche OpenAPI 2.0 che OpenAPI 3.0. Se abilitata, la specifica viene visualizzata nel portale API.
route: elenco di regole di route per indirizzare il traffico alle app e applicare filtri.
protocollo: protocollo back-end dell'applicazione a cui Spring Cloud Gateway instrada il traffico. I valori supportati del protocollo sono HTTP o HTTPSe il valore predefinito è HTTP. Per proteggere il traffico da Spring Cloud Gateway all'applicazione abilitata per HTTPS, è necessario impostare il protocollo su HTTPS nella configurazione della route.
route a livello di app: sono disponibili tre proprietà di route che è possibile configurare a livello di app per evitare ripetizioni in tutte o nella maggior parte delle route nella configurazione della route. La regola di routing concreta sostituisce la regola di routing a livello di app per la stessa proprietà. È possibile definire le proprietà seguenti a livello di app: predicates, filterse ssoEnabled. Se si usa la OpenAPI URI funzionalità per definire le route, l'unica proprietà di routing a livello di app da supportare è filters.

Usare il comando seguente per creare una configurazione di route. Il --app-name valore deve essere il nome di un'app ospitata in Azure Spring Apps a cui le richieste instradano.

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'esempio seguente mostra un file JSON passato al --routes-file parametro nel comando create:

{
   "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
      }
   ]
}

Nella tabella seguente sono elencate le definizioni di route. Tutte le proprietà sono facoltative.

Proprietà	Descrizione
title	Titolo da applicare ai metodi nella documentazione openAPI generata.
description	Descrizione da applicare ai metodi nella documentazione openAPI generata.
uri	URI completo, che esegue l'override del nome dell'app a cui viene indirizzata la richiesta.
ssoEnabled	Valore che indica se abilitare la convalida SSO. Vedere Configurare l'accesso Single Sign-On.
tokenRelay	Passa il token di identità dell'utente attualmente autenticato all'applicazione.
Predicati	Elenco di predicati. Vedere Predicati disponibili.
filtri	Elenco di filtri. Vedere Filtri disponibili.
ordine	Ordine di elaborazione della route. Un ordine inferiore viene elaborato con precedenza più elevata, come in Spring Cloud Gateway.
tag	Tag di classificazione applicati ai metodi nella documentazione openAPI generata.

Nota

A causa di motivi di sicurezza o compatibilità, non tutti i filtri/predicati sono supportati in Azure Spring Apps. Le opzioni seguenti non sono supportate:

BasicAuth
JWTKey

Usare le route per Spring Cloud Gateway

Usare la procedura seguente per creare un'applicazione di esempio usando Spring Cloud Gateway.

Usare il comando seguente per creare un'applicazione di test denominata test-app in Azure Spring Apps:

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

Assegnare un endpoint pubblico al gateway per accedervi.

Per visualizzare lo stato e le risorse in esecuzione assegnati a Spring Cloud Gateway, aprire l'istanza di Azure Spring Apps nel portale di Azure, selezionare la sezione Spring Cloud Gateway e quindi selezionare Panoramica.

Per assegnare un endpoint pubblico, selezionare Sì accanto a Assegna endpoint. Un URL viene visualizzato in pochi minuti. Salvare l'URL da usare in un secondo momento.

È anche possibile usare l'interfaccia della riga di comando di Azure per assegnare l'endpoint. Usare il comando seguente per assegnare l'endpoint.
```
az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --assign-endpoint true
```

Creare una regola per accedere all'endpoint di controllo integrità dell'app di test tramite Spring Cloud Gateway.

Salvare il contenuto seguente in un file test-api.json . Questa configurazione include un filtro RateLimit, che consente 20 richieste ogni 10 secondi e un filtro RewritePath, che consente all'endpoint della richiesta di raggiungere l'endpoint di controllo integrità 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"
      ]
    }
  ]
}

Usare quindi il comando seguente per applicare la regola all'app 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

È anche possibile visualizzare le route nel portale, come illustrato nello screenshot seguente:

Usare il comando seguente per accedere all'API tramite l'endpoint test health check del gateway:
```
curl https://<endpoint-url>/test/api/healthcheck
```

Usare i comandi seguenti per eseguire query sulle regole di routing:

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}'

Uso dei filtri

Il progetto Spring Cloud Gateway open source include molti filtri predefiniti da usare nelle route del gateway. Spring Cloud Gateway offre molti filtri personalizzati oltre ai filtri inclusi nel progetto OSS.

L'esempio seguente illustra come applicare il AddRequestHeadersIfNotPresent filtro a una route:

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

Applicare quindi la definizione di route usando il comando dell'interfaccia della riga di comando di Azure seguente:

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>

Per altre informazioni sui filtri di route disponibili, vedere How to use VMware Spring Cloud Gateway Route Filters with the Azure Spring Apps Enterprise plan (Come usare i filtri di route di VMware Spring Cloud Gateway con il piano Enterprise di Azure Spring Apps).

Condividi tramite

Usare Spring Cloud Gateway

Prerequisiti

Configurare le route

Usare le route per Spring Cloud Gateway

Uso dei filtri

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive