Verwenden des Spring Cloud-Gateways
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 Enterprise-Plan von Azure Spring Apps 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.
Für die Integration in das API-Portal für VMware Tanzu generiert VMware Spring Cloud Gateway automatisch eine Dokumentation für OpenAPI Version 3, nachdem eine Routenkonfiguration hinzugefügt oder geändert wurde.
Voraussetzungen
- Eine bereits bereitgestellte Azure Spring Apps-Instanz im Enterprise-Plan mit aktiviertem Spring Cloud Gateway. Weitere Informationen finden Sie unter Schnellstart: Erstellen und Bereitstellen von Anwendungen 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 wiehttp://<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 nach der Aktivierung im API-Portal angezeigt. - 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
oderHTTPS
, und der Standardwert istHTTP
. Um den Datenverkehr von Spring Cloud Gateway zu Ihrer HTTPS-fähigen Anwendung zu sichern, müssen Sie das Protokoll in Ihrer Routenkonfiguration aufHTTPS
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 überschreibt die Routingregel auf App-Ebene für dieselbe Eigenschaft. Sie können die folgenden Eigenschaften auf App-Ebene definieren:
predicates
,filters
undssoEnabled
. Wenn Sie dasOpenAPI URI
-Feature zum Definieren von Routen verwenden, istfilters
die einzige Routingeigenschaft, die auf App-Ebene unterstützt wird.
Erstellen Sie mit dem folgenden Befehl eine neue Routenkonfiguration. Der Wert von --app-name
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 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 angewandt 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 in Azure Spring Apps eine Testanwendung namens test-app 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. Nach wenigen Minuten wird eine URL angezeigt. Speichern Sie die URL zur späteren Verwendung.
Sie können auch die Azure-Befehlszeilenschnittstelle 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 angewandt 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-Routenfiltern mit dem Enterprise-Plan von Azure Spring Apps.