Verwenden des Spring Cloud-Gateways

Artikel
04/23/2024

Hinweis

Azure Spring Apps ist der neue Name für den Azure Spring Cloud-Dienst. Obwohl der Dienst umbenannt wurde, wird der alte Name noch an einigen Stellen verwendet, solange wir Ressourcen wie Screenshots, Videos und Diagramme aktualisieren.

Dieser Artikel gilt für:❌ Basic/Standard ✔️ Enterprise

In diesem Artikel erfahren Sie, wie Sie VMware Spring Cloud Gateway mit dem Azure Spring Apps Enterprise-Plan verwenden, um Anforderungen an Ihre Anwendungen weiterzuleiten.

VMware Spring Cloud Gateway ist eine kommerzielle VMware Tanzu-Komponente, die auf dem Spring Cloud Gateway-Open-Source-Projekt basiert. Spring Cloud Gateway erleichtert die Berücksichtigung übergreifender Aspekte durch API-Entwicklungsteams, z. B. einmaliges Anmelden (SSO), Zugriffssteuerung, Ratenbegrenzung, Resilienz, Sicherheit usw. Sie können die API-Bereitstellung mit modernen cloudnativen Modellen und einer beliebigen Programmiersprache für die API-Entwicklung beschleunigen.

Spring Cloud Gateway umfasst die folgenden Funktionen:

Dynamische Routingkonfiguration, unabhängig von einzelnen Anwendungen, die ohne Neukompilierung angewendet und geändert werden können.
Kommerzielle API-Routenfilter für den Transport von autorisierten JWT-Ansprüchen (JSON Web Token) an Anwendungsdienste.
Clientzertifikatautorisierung.
Ratenbegrenzungsansätze.
Konfiguration von Trennschaltern (Circuit Breakers)
Unterstützung für den Zugriff auf Anwendungsdienste über HTTP-Standardauthentifizierungsanmeldeinformationen.

Um das API-Portal für VMware Tanzu zu integrieren, generiert VMware Spring Cloud Gateway automatisch OpenAPI Version 3-Dokumentation nach allen Routenkonfigurationszufügungen oder -änderungen.

Voraussetzungen

Eine bereits bereitgestellte Azure Spring Apps Enterprise-Plandienstinstanz mit aktiviertem Spring Cloud Gateway. Weitere Informationen finden Sie in der Schnellstartanleitung: Erstellen und Bereitstellen von Apps in Azure Spring Apps mit dem Enterprise-Plan.
Azure CLI-Version 2.0.67 oder höher Verwenden Sie den folgenden Befehl, um die Azure Spring Apps-Erweiterung zu installieren: az extension add --name spring.

Konfigurieren von Routen

In diesem Abschnitt wird beschrieben, wie Sie API-Routen für Apps, die Spring Cloud Gateway verwenden, hinzufügen, aktualisieren und verwalten.

Die Routenkonfigurationsdefinition umfasst die folgenden Komponenten:

OpenAPI-URI: Dieser URI verweist auf eine OpenAPI-Spezifikation. Sie können einen öffentlichen URI-Endpunkt wie https://petstore3.swagger.io/api/v3/openapi.json oder einen konstruierten URI wie http://<app-name>/{relative-path-to-OpenAPI-spec} verwenden, wobei <app-name> der Name einer Anwendung in Azure Spring Apps ist, die die API-Definition enthält. Sowohl OpenAPI 2.0- als auch OpenAPI 3.0-Spezifikationen werden unterstützt. Die Spezifikation wird im API-Portal angezeigt, wenn diese aktiviert ist.
routes: Eine Liste von Routenregeln zum Weiterleiten von Datenverkehr an Apps und Anwenden von Filtern.
protocol: Das Back-End-Protokoll der Anwendung, an die Spring Cloud Gateway Datenverkehr leitet. Die vom Protokoll unterstützten Werte sind HTTP oder HTTPS, und der Standardwert ist HTTP. Um den Datenverkehr von Spring Cloud Gateway zu Ihrer HTTPS-fähigen Anwendung zu sichern, müssen Sie das Protokoll in Ihrer Routenkonfiguration auf HTTPS festlegen.
Routen auf App-Ebene: Es gibt drei Routeneigenschaften, die Sie auf App-Ebene konfigurieren können, um Wiederholungen über alle oder die meisten Routen in der Routenkonfiguration zu vermeiden. Die konkrete Routingregel setzt die Routingregel auf App-Ebene für dieselbe Eigenschaft außer Kraft. Sie können die folgenden Eigenschaften auf App-Ebene definieren: predicates, filters und ssoEnabled. Wenn Sie das OpenAPI URI-Feature zum Definieren von Routen verwenden, ist filters die einzige Routingeigenschaft, die auf App-Ebene unterstützt wird.

Verwenden Sie den folgenden Befehl, um eine Routenkonfiguration zu erstellen. Der --app-name Wert sollte der Name einer in Azure Spring Apps gehosteten App sein, an die die Anforderungen weitergeleitet werden.

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>

Das folgende Beispiel zeigt eine JSON-Datei, die an den Parameter --routes-file im create-Befehl übergeben wird:

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

Die Routendefinitionen sind in den folgenden Tabellen aufgeführt. Alle Eigenschaften sind optional.

Eigenschaft	Beschreibung
title	Ein Titel, der auf Methoden in der generierten OpenAPI-Dokumentation angewendet wird.
Beschreibung	Eine Beschreibung, die auf Methoden in der generierten OpenAPI-Dokumentation angewendet wird.
uri	Der vollständige URI, der den Namen der App überschreibt, an die die Anforderungen weitergeleitet werden.
ssoEnabled	Ein Wert, der angibt, ob SSO-Validierung aktiviert werden soll. Weitere Informationen finden Sie unter Konfigurieren des einmaligen Anmeldens.
tokenRelay	Übergibt das Identitätstoken des derzeit authentifizierten Benutzers an die Anwendung.
Prädikate	Eine Liste mit Prädikaten. Weitere Informationen finden Sie unter Verfügbare Prädikate.
filters	Eine Liste der Filter. Weitere Informationen finden Sie unter Verfügbare Filter.
Reihenfolge	Die Reihenfolge der Routenbearbeitung. Eine niedrigere Reihenfolge wird mit höherer Rangfolge verarbeitet, wie in Spring Cloud Gateway.
Tags	Klassifizierungstags, die auf Methoden in der generierten OpenAPI-Dokumentation angewendet werden.

Hinweis

Aus Sicherheits- bzw. Kompatibilitätsgründen werden nicht alle Filter/Prädikate in Azure Spring Apps unterstützt. Die folgenden werden nicht unterstützt:

BasicAuth
JWTKey

Verwenden von Routen für Spring Cloud Gateway

Führen Sie die folgenden Schritte aus, um mithilfe von Spring Cloud Gateway eine Beispielanwendung zu erstellen.

Verwenden Sie den folgenden Befehl, um eine Testanwendung namens "test-app " in Azure Spring Apps zu erstellen:

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

Weisen Sie dem Gateway einen öffentlichen Endpunkt zu, um darauf zu zugreifen.

Um den Ausführungsstatus und die Ressourcen anzuzeigen, die Spring Cloud Gateway zugewiesen werden, öffnen Sie Ihre Azure Spring Apps-Instanz im Azure-Portal, wählen Sie den Abschnitt Spring Cloud Gateway und dann Übersicht aus.

Wählen Sie Ja neben Endpunkt zuweisen aus, um einen öffentlichen Endpunkt zuzuweisen. Eine URL wird in ein paar Minuten angezeigt. Speichern Sie die URL zur späteren Verwendung.

Sie können auch Azure CLI verwenden, um den Endpunkt zuzuweisen. Verwenden Sie den folgenden Befehl, um den Endpunkt zuzuweisen.
```
az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --assign-endpoint true
```

Erstellen Sie eine Regel für den Zugriff auf den Integritätsprüfungsendpunkt der Test-App über Spring Cloud Gateway.

Speichern Sie den folgenden Inhalt in einer Datei test-api.json. Diese Konfiguration umfasst einen RateLimit-Filter, der 20 Anforderungen alle 10 Sekunden zulässt, und einen RewritePath-Filter, mit dem der Anforderungsendpunkt den standardmäßigen Spring Boot-Integritätsprüfungsendpunkt erreichen kann.

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

Verwenden Sie dann den folgenden Befehl, um die Regel auf die test-app-App anzuwenden:

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

Sie können die Routen auch im Portal anzeigen, wie im folgenden Screenshot gezeigt:

Verwenden Sie den folgenden Befehl, um über den Gatewayendpunkt auf die API test health check zuzugreifen:
```
curl https://<endpoint-url>/test/api/healthcheck
```

Verwenden Sie den folgenden Befehl, um die Routingregeln abzufragen:

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

Filter verwenden

Das Open-Source-Projekt Spring Cloud Gateway enthält viele integrierte Filter für die Verwendung in Gatewayrouten. Spring Cloud Gateway bietet zusätzlich zu den filtern, die im OSS-Projekt enthalten sind, viele benutzerdefinierte Filter.

Das folgende Beispiel zeigt, wie der AddRequestHeadersIfNotPresent Filter auf eine Route angewendet wird:

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

Wenden Sie anschließend die Routendefinition mithilfe des folgenden Azure CLI-Befehls an:

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>

Weitere Informationen zu verfügbaren Routenfiltern finden Sie unter Verwendung von VMware Spring Cloud Gateway Route Filters mit dem Azure Spring Apps Enterprise-Plan.

Verwenden des Spring Cloud-Gateways

Voraussetzungen

Konfigurieren von Routen

Verwenden von Routen für Spring Cloud Gateway

Filter verwenden

Nächste Schritte

Zusätzliche Ressourcen