Usare Spring Cloud Gateway

  • Articolo

Nota

Azure Spring Apps è il nuovo nome del servizio Azure Spring Cloud. Anche se il servizio ha un nuovo nome, il nome precedente verrà visualizzato in alcune posizioni per un po' mentre si lavora per aggiornare gli asset, ad esempio screenshot, video e diagrammi.

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 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, 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 le 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

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.
order 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.

  1. 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>

  2. 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.

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

    È 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

  3. 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:

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

  4. Usare il comando seguente per accedere all'API tramite l'endpoint test health check del gateway:

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

  5. 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).

Passaggi successivi