Verwenden des Spring Cloud-Gateways

Artikel
10/02/2024

Hinweis

Die Pläne Basic, Standard und Enterprise gelten ab Mitte März 2025 als veraltet und werden über einen Zeitraum von drei Jahren eingestellt. Es wird empfohlen, auf Azure Container Apps umzustellen. Weitere Informationen finden Sie in der Ankündigung zur Einstellung von Azure Spring Apps.

Der Plan Standardverbrauch und dediziert gilt ab dem 30. September 2024 als veraltet und wird nach sechs Monaten vollständig eingestellt. Es wird empfohlen, auf Azure Container Apps umzustellen. Weitere Informationen finden Sie unter Migrieren des Plans „Standardverbrauch und dediziert“ von Azure Spring Apps zu Azure Container Apps.

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 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 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 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 überschreibt die Routingregel auf App-Ebene für dieselbe Eigenschaft. 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.

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.

Freigeben über

Verwenden des Spring Cloud-Gateways

Voraussetzungen

Konfigurieren von Routen

Verwenden von Routen für Spring Cloud Gateway

Filter verwenden

Nächste Schritte

Feedback

Zusätzliche Ressourcen