Configurare VMware Spring Cloud Gateway

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

Questo articolo illustra come configurare VMware Spring Cloud Gateway per VMware Tanzu con il piano Enterprise di Azure Spring Apps.

VMware Spring Cloud Gateway è un componente VMware Tanzu commerciale basato sul progetto Spring Cloud Gateway open source. VMware Spring Cloud Gateway per Tanzu 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. È possibile accelerare il recapito delle API usando modelli nativi del cloud moderni nella scelta del linguaggio di programmazione per lo sviluppo di API.

Un'istanza di VMware Spring Cloud Gateway instrada il traffico in base alle regole. Supporta il ridimensionamento in/out e l'aumento/riduzione per soddisfare un carico di traffico dinamico.

VMware Spring Cloud Gateway include le funzionalità seguenti:

• Configurazione del routing dinamico, indipendentemente da singole applicazioni, che è possibile applicare e modificare senza ricompilare
• 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 di route. Per altre informazioni, vedere Usare il portale API per VMware Tanzu.

Prerequisiti

• Un'istanza del servizio del piano Enterprise di Azure Spring Apps già con VMware 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.

Abilitare o disabilitare VMware Spring Cloud Gateway

È possibile abilitare o disabilitare VMware Spring Cloud Gateway dopo la creazione dell'istanza del servizio usando il portale di Azure o l'interfaccia della riga di comando di Azure. Prima di disabilitare VMware Spring Cloud Gateway, è necessario annullarne l'assegnazione e rimuovere tutte le configurazioni di route.

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>

Riavviare VMware Spring Cloud Gateway

Dopo aver completato l'azione di riavvio, le istanze di VMware Spring Cloud Gateway vengono riavviate in sequenza.

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

Assegnare un endpoint pubblico a VMware Spring Cloud Gateway

Questa sezione descrive come assegnare un endpoint pubblico a VMware Spring Cloud Gateway e configurarne le proprietà.

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

Configurare i metadati di VMware Spring Cloud Gateway

I metadati di VMware Spring Cloud Gateway generano automaticamente la documentazione OpenAPI versione 3. È possibile configurare i metadati di VMware Spring Cloud Gateway per visualizzare i gruppi di route nel portale API per VMware Tanzu. Per altre informazioni, vedere Usare il portale API per VMware Tanzu.

Nella tabella seguente vengono descritte le opzioni disponibili per i metadati:

È possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure per modificare le proprietà dei metadati.

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 "*"

Configurare Single Sign-On

VMware Spring Cloud Gateway supporta l'autenticazione e l'autorizzazione tramite Single Sign-On (SSO) con un provider di identità OpenID. Il provider supporta il protocollo OpenID Connect Discovery. La tabella seguente descrive le proprietà SSO:

Per configurare l'accesso SSO con Microsoft Entra ID, vedere Configurare l'accesso Single Sign-On con Microsoft Entra ID per Spring Cloud Gateway e portale API.

È possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure per modificare le proprietà SSO.

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 supporta solo i server di autorizzazione che supportano il protocollo OpenID Connect Discovery. Assicurarsi inoltre di configurare il server di autorizzazione esterno per consentire i reindirizzamenti al gateway. Fare riferimento alla documentazione del server di autorizzazione e aggiungere https://<gateway-external-url>/login/oauth2/code/sso all'elenco degli URI di reindirizzamento consentiti.

Se si configura la proprietà SSO errata, ad esempio la password errata, è necessario rimuovere l'intera proprietà SSO e quindi aggiungere la configurazione corretta.

Dopo aver configurato l'accesso Single Sign-On, ricordarsi di impostare ssoEnabled: true per le route di VMware Spring Cloud Gateway.

Configurare la disconnessione SSO

Le istanze del servizio VMware Spring Cloud Gateway forniscono un endpoint API predefinito per disconnettersi dalla sessione SSO corrente. Il percorso di questo endpoint è /scg-logout. La disconnessione comporta uno dei risultati seguenti, a seconda della modalità di chiamata dell'endpoint di disconnessione:

• Disconnettersi dalla sessione e reindirizzare al provider di identità (IdP) disconnessione.
• Disconnettersi dalla sessione dell'istanza del servizio.

Disconnettersi dalla sessione IdP e SSO

Se si invia una richiesta di GET all'endpoint /scg-logout, l'endpoint invia una risposta di reindirizzamento 302 all'URL di disconnessione IdP. Per ottenere l'endpoint per restituire l'utente a un percorso nell'istanza del servizio gateway, aggiungere un parametro di reindirizzamento alla richiesta GET con l'endpoint /scg-logout. Ad esempio, è possibile usare ${server-url}/scg-logout?redirect=/home.

Il valore del parametro di reindirizzamento deve essere un percorso valido nell'istanza del servizio VMware Spring Cloud Gateway. Non è possibile reindirizzare a un URL esterno.

I passaggi seguenti descrivono un esempio di come implementare la funzione nei microservizi:

1. Ottenere una configurazione di route per instradare la richiesta di disconnessione all'applicazione. Per un esempio, vedere la configurazione della route nel repository animal-rescue su GitHub.

2. Aggiungere qualsiasi logica di disconnessione necessaria per l'applicazione. Alla fine è necessaria una richiesta GET all'endpoint /scg-logout del gateway, come illustrato nel valore di return per il metodo getActionButton nel repository animal-rescue.

Disconnettersi solo dalla sessione SSO

Se si invia la richiesta di GET all'endpoint /scg-logout usando XMLHttpRequest, il reindirizzamento di 302 potrebbe essere inghiottito e non gestito nel gestore della risposta. In questo caso, l'utente verrà disconnesso solo dalla sessione SSO nell'istanza del servizio VMware Spring Cloud Gateway. L'utente avrà comunque una sessione IdP valida. In genere, se l'utente tenta di accedere di nuovo, viene inviato automaticamente al gateway come autenticato da IdP.

È necessario avere una configurazione di route per instradare la richiesta di disconnessione all'applicazione, come illustrato nell'esempio seguente. Questo codice rende una sessione SSO di disconnessione solo gateway.

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

Configurare la condivisione di risorse tra le origini

La condivisione di risorse tra le origini (CORS) consente di richiedere risorse limitate in una pagina Web da richiedere da un altro dominio all'esterno del dominio da cui è stata servita la prima risorsa. Nella tabella seguente vengono descritte le opzioni di configurazione CORS disponibili.

Assicurarsi di avere la configurazione CORS corretta se si vuole eseguire l'integrazione con il portale API. Per altre informazioni, vedere la sezione Assegnare un endpoint pubblico a VMware Spring Cloud Gateway.

Usare il ridimensionamento del servizio

È possibile personalizzare l'allocazione delle risorse per le istanze di VMware Spring Cloud Gateway, tra cui vCPU, memoria e numero di istanze.

Per la disponibilità elevata, non è consigliabile usare una singola replica.

La tabella seguente descrive l'utilizzo predefinito delle risorse.

Configurare TLS tra il gateway e le applicazioni

Per migliorare la sicurezza e proteggere le informazioni riservate dall'intercettazione da parte di parti non autorizzate, è possibile abilitare Transport Layer Security (TLS) tra VMware Spring Cloud Gateway e le applicazioni.

Prima di configurare TLS, è necessario avere un'applicazione abilitata per TLS e un certificato TLS. Per preparare un certificato TLS, generare un certificato da un'autorità di certificazione (CA) attendibile. Il certificato verifica l'identità del server e stabilisce una connessione sicura.

Dopo aver eseguito un'applicazione abilitata per TLS in Azure Spring Apps, caricare il certificato in Azure Spring Apps. Per altre informazioni, vedere la sezione Importare un certificato in Usare certificati TLS/SSL nell'applicazione in Azure Spring Apps.

Con il certificato aggiornato ad Azure Spring Apps, è possibile configurare il certificato TLS per il gateway e abilitare la verifica del certificato. È possibile configurare il certificato nel portale di Azure o usando l'interfaccia della riga di comando di Azure.

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>

Preparare la configurazione della route

È necessario specificare il protocollo come HTTPS nella configurazione della route. L'oggetto JSON seguente indica a VMware Spring Cloud Gateway di usare il protocollo HTTPS per tutto il traffico tra il gateway e l'app.

1. Creare un file denominato test-tls-route.json con il contenuto seguente:

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

2. Usare il comando seguente per applicare la regola all'applicazione:

   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
   

È ora possibile verificare se l'applicazione è abilitata per TLS con l'endpoint del gateway. Per altre informazioni, vedere la sezione Configurare le route di Usare Spring Cloud Gateway.

Ruotare i certificati

Quando i certificati scadono, è necessario ruotare i certificati in VMware Spring Cloud Gateway attenendosi alla procedura seguente:

1. Generare nuovi certificati da una CA attendibile.
2. Importare i certificati in Azure Spring Apps. Per altre informazioni, vedere la sezione Importare un certificato in Usare certificati TLS/SSL nell'applicazione in Azure Spring Apps.
3. Sincronizzare i certificati usando il portale di Azure o l'interfaccia della riga di comando di Azure.

VMware Spring Cloud Gateway viene riavviato per assicurarsi che il gateway usi il nuovo certificato per tutte le connessioni.

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

Configurare le impostazioni di scalabilità automatica

È possibile impostare le modalità di scalabilità automatica per 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"

Per altre informazioni sulle metriche disponibili, vedere la sezione Opzioni metriche utente di Metriche per App Spring di Azure.

Configurare la cache delle risposte

La configurazione della cache delle risposte consente di definire una cache delle risposte HTTP che è possibile applicare a livello globale o a livello di route.

Abilitare la cache delle risposte a livello globale

Dopo aver abilitato la cache delle risposte a livello globale, la cache delle risposte viene abilitata automaticamente per tutte le route applicabili.

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

Abilitare la cache delle risposte a livello di route

Per abilitare la cache delle risposte per qualsiasi route, usare il filtro LocalResponseCache. L'esempio seguente illustra come usare il filtro LocalResponseCache nella configurazione della regola di routing:

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

Per altre informazioni, vedere la sezione LocalResponseCache di Come usare i filtri di route di VMware Spring Cloud Gateway con il piano Enterprise di Azure Spring Apps e LocalResponseCache nella documentazione di VMware.

Anziché configurare size e timeToLive per ogni filtro LocalResponseCache singolarmente, è possibile impostare questi parametri a livello di Spring Cloud Gateway. Questa opzione consente di usare il filtro LocalResponseCache senza specificare inizialmente questi valori, mantenendo al tempo stesso la flessibilità di eseguirne l'override in un secondo momento.

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'esempio seguente illustra come usare il filtro LocalResponseCache quando size e timeToLive vengono impostati a livello di 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"
         ],
      }
   ]
}

Configurare le variabili di ambiente

Il servizio Azure Spring Apps gestisce e ottimizza VMware Spring Cloud Gateway. Ad eccezione dei casi d'uso che configurano il monitoraggio delle prestazioni dell'applicazione (APM) e il livello di log, in genere non è necessario configurare VMware Spring Cloud Gateway con variabili di ambiente.

Se si hanno requisiti che non è possibile soddisfare da altre configurazioni descritte in questo articolo, è possibile provare a configurare le variabili di ambiente visualizzate nell'elenco Proprietà comuni dell'applicazione. Assicurarsi di verificare la configurazione nell'ambiente di test prima di applicarla all'ambiente di produzione.

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

Dopo aver aggiornato le variabili di ambiente, VMware Spring Cloud Gateway viene riavviato.

Configurare il monitoraggio delle prestazioni dell'applicazione

Per monitorare VMware Spring Cloud Gateway, è possibile configurare APM. La tabella seguente elenca i cinque tipi di agenti Java APM forniti da VMware Spring Cloud Gateway, insieme alle variabili di ambiente necessarie.

Per altre variabili di ambiente supportate, vedere le origini seguenti:

• Panoramica di Application Insights
• Variabili di ambiente Dynatrace
• Variabili di ambiente New Relic
• Variabili di ambiente AppDynamics
• Variabili di ambiente elastiche

Configurare l'integrazione di APM a livello di istanza del servizio (scelta consigliata)

Per abilitare il monitoraggio APM in VMware Spring Cloud Gateway, è possibile creare una configurazione APM a livello di istanza del servizio e associarla a Spring Cloud Gateway. In questo modo, è possibile configurare facilmente APM una sola volta e associare lo stesso APM a Spring Cloud Gateway e alle app.

Gestire APM in VMware Spring Cloud Gateway (deprecato)

È possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure per configurare APM in VMware Spring Cloud Gateway. È anche possibile specificare i tipi di agenti Java APM da usare e le variabili di ambiente APM corrispondenti supportate.

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

Configurare i livelli di log

È possibile configurare i livelli di log di VMware Spring Cloud Gateway nei modi seguenti per ottenere altri dettagli o ridurre i log:

• È possibile impostare i livelli di log su TRACE, DEBUG, INFO, WARN, ERROR o OFF. Il livello di log predefinito per VMware Spring Cloud Gateway è INFO.
• È possibile disattivare i log impostando i livelli di log su OFF.
• Quando il livello di log è impostato su WARN, ERROR o OFF, potrebbe essere necessario modificarlo in INFO quando si richiede il supporto del team di Azure Spring Apps. Questa modifica causa un riavvio di VMware Spring Cloud Gateway.
• Quando il livello di log è impostato su TRACE o DEBUG, potrebbe influire sulle prestazioni di VMware Spring Cloud Gateway. Provare a evitare queste impostazioni nell'ambiente di produzione.
• È possibile impostare i livelli di log per il logger root o per logger specifici, ad esempio io.pivotal.spring.cloud.gateway.

I logger seguenti possono contenere informazioni importanti sulla risoluzione dei problemi a livello di TRACE e DEBUG:

Per ottenere le chiavi delle variabili di ambiente, aggiungere il prefisso logging.level. e quindi impostare il livello di log configurando l'ambiente logging.level.{loggerName}={logLevel}. Gli esempi seguenti illustrano i passaggi per il portale di Azure e l'interfaccia della riga di comando di Azure.

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

Aggiornare la configurazione del componente aggiuntivo

La funzionalità di configurazione del componente aggiuntivo consente di personalizzare determinate proprietà di VMware Spring Cloud Gateway usando una stringa di formato JSON. La funzionalità è utile quando è necessario configurare le proprietà che non sono esposte tramite l'API REST.

La configurazione del componente aggiuntivo è un oggetto JSON con coppie chiave/valore che rappresentano la configurazione desiderata. L'esempio seguente illustra la struttura del formato JSON:

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

L'elenco seguente mostra le configurazioni dei componenti aggiuntivi supportate per i nomi delle chiavi e i tipi di valore del componente aggiuntivo. Questo elenco è soggetto a modifiche durante l'aggiornamento della versione di VMware Spring Cloud Gateway.

• Configurazione SSO:

  • Nome chiave: sso

  • Tipo valore: Oggetto

  • Proprietà:

    • RolesAttributeName (String): specifica il nome dell'attributo che contiene i ruoli associati alla sessione SSO.
    • InactiveSessionExpirationInMinutes (Integer): specifica l'ora di scadenza, espressa in minuti, per le sessioni SSO inattive. Un valore di 0 indica che la sessione non scade mai.

  • Esempio:

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

• Configurazione dei metadati:

  • Nome chiave: api

  • Tipo valore: Oggetto

  • Proprietà

    • groupId (String): identificatore univoco per il gruppo di API disponibili nell'istanza di VMware Spring Cloud Gateway. Il valore può contenere solo lettere minuscole e numeri.

  • Esempio:

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

• Configurazione dei pod

  • Nome chiave: PodOverrides, usato per specificare le sostituzioni per la configurazione predefinita del pod.

  • Tipo valore: Oggetto

  • Proprietà

    • Containers: questa matrice contiene la configurazione per i singoli contenitori all'interno del pod. Attualmente è supportato solo il contenitore denominato gateway.
      • Name: specifica il nome del contenitore. Il contenitore deve essere denominato gateway.
      • Lifecycle: PreStop è un hook del ciclo di vita che viene eseguito quando un contenitore sta per essere terminato. Questo hook consente di eseguire qualsiasi pulizia necessaria prima dell'arresto del contenitore.
    • TerminationGracePeriodSeconds: specifica la quantità di tempo in cui Kubernetes attende che un pod termini normalmente prima di ucciderlo forzatamente.

  • Esempio:

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

    Quando un pod contenente questo contenitore viene terminato, l'hook PreStop esegue il comando /bin/sh -c 'sleep 20', causando la sospensione del contenitore per 20 secondi. Questa pausa dà al contenitore del tempo necessario per completare le attività o la pulizia in corso prima che venga effettivamente arrestata.

    L'impostazione TerminationGracePeriodSeconds fornisce un totale di 120 secondi per il termine normale del pod, incluso il tempo impiegato da qualsiasi hook del ciclo di vita, ad esempio PreStop.

Per aggiornare la configurazione del componente aggiuntivo, seguire questa procedura.

Passaggi successivi

• Usare Spring Cloud Gateway