Use Spring Cloud Gateway
Nóta
The Basic, Standard, and Enterprise plans will be deprecated starting from mid-March, 2025, with a 3 year retirement period. We recommend transitioning to Azure Container Apps. For more information, see the Azure Spring Apps retirement announcement.
The Standard consumption and dedicated plan will be deprecated starting September 30, 2024, with a complete shutdown after six months. We recommend transitioning to Azure Container Apps. For more information, see Migrate Azure Spring Apps Standard consumption and dedicated plan to Azure Container Apps.
This article applies to: ❌ Basic/Standard ✔️ Enterprise
This article shows you how to use VMware Spring Cloud Gateway with the Azure Spring Apps Enterprise plan to route requests to your applications.
VMware Spring Cloud Gateway is a commercial VMware Tanzu component based on the open-source Spring Cloud Gateway project. Spring Cloud Gateway handles cross-cutting concerns for API development teams, such as single sign-on (SSO), access control, rate-limiting, resiliency, security, and more. You can accelerate API delivery using modern cloud native patterns, and any programming language you choose for API development.
Spring Cloud Gateway includes the following features:
- Dynamic routing configuration, independent of individual applications that can be applied and changed without recompilation.
- Commercial API route filters for transporting authorized JSON Web Token (JWT) claims to application services.
- Client certificate authorization.
- Rate-limiting approaches.
- Circuit breaker configuration.
- Support for accessing application services via HTTP Basic Authentication credentials.
To integrate with API portal for VMware Tanzu, VMware Spring Cloud Gateway automatically generates OpenAPI version 3 documentation after any route configuration additions or changes.
- An already provisioned Azure Spring Apps Enterprise plan service instance with Spring Cloud Gateway enabled. For more information, see Quickstart: Build and deploy apps to Azure Spring Apps using the Enterprise plan.
- Azure CLI version 2.0.67 or later. Use the following command to install the Azure Spring Apps extension:
az extension add --name spring
.
This section describes how to add, update, and manage API routes for apps that use Spring Cloud Gateway.
The route configuration definition includes the following parts:
- OpenAPI URI: This URI references an OpenAPI specification. You can use a public URI endpoint such as
https://petstore3.swagger.io/api/v3/openapi.json
or a constructed URI such ashttp://<app-name>/{relative-path-to-OpenAPI-spec}
, where<app-name>
is the name of an application in Azure Spring Apps that includes the API definition. Both OpenAPI 2.0 and OpenAPI 3.0 specs are supported. The specification displays in the API portal if enabled. - routes: A list of route rules to direct traffic to apps and apply filters.
- protocol: The backend protocol of the application to which Spring Cloud Gateway routes traffic. The protocol's supported values are
HTTP
orHTTPS
, and the default isHTTP
. To secure traffic from Spring Cloud Gateway to your HTTPS-enabled application, you need to set the protocol toHTTPS
in your route configuration. - app level routes: There are three route properties that you can configure at the app level to avoid repetition across all or most of the routes in the route configuration. The concrete routing rule overrides the app level routing rule for the same property. You can define the following properties at the app level:
predicates
,filters
, andssoEnabled
. If you use theOpenAPI URI
feature to define routes, the only app level routing property to support isfilters
.
Use the following command to create a route config. The --app-name
value should be the name of an app hosted in Azure Spring Apps that the requests route to.
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>
The following example shows a JSON file that's passed to the --routes-file
parameter in the create command:
{
"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
}
]
}
The following table lists the route definitions. All the properties are optional.
Property | Description |
---|---|
title | A title to apply to methods in the generated OpenAPI documentation. |
description | A description to apply to methods in the generated OpenAPI documentation. |
uri | The full URI, which overrides the name of app that the requests route to. |
ssoEnabled | A value that indicates whether to enable SSO validation. See Configure single sign-on. |
tokenRelay | Passes the currently authenticated user's identity token to the application. |
predicates | A list of predicates. See Available Predicates. |
filters | A list of filters. See Available Filters. |
order | The route processing order. A lower order is processed with higher precedence, as in Spring Cloud Gateway. |
tags | Classification tags that are applied to methods in the generated OpenAPI documentation. |
Nóta
Because of security or compatibility reasons, not all the filters/predicates are supported in Azure Spring Apps. The following aren't supported:
- BasicAuth
- JWTKey
Use the following steps to create a sample application using Spring Cloud Gateway.
Use the following command to create a test application named test-app in Azure Spring Apps:
az spring app create \ name test-app \ resource-group <resource-group-name> \ service <Azure-Spring-Apps-instance-name>
Assign a public endpoint to the gateway to access it.
To view the running state and resources given to Spring Cloud Gateway, open your Azure Spring Apps instance in the Azure portal, select the Spring Cloud Gateway section, then select Overview.
To assign a public endpoint, select Yes next to Assign endpoint. A URL appears in a few minutes. Save the URL to use later.
You can also use Azure CLI to assign the endpoint. Use the following command to assign the endpoint.
az spring gateway update \ --resource-group <resource-group-name> \ --service <Azure-Spring-Apps-instance-name> \ --assign-endpoint true
Create a rule to access the health check endpoint of the test app through Spring Cloud Gateway.
Save the following content to a test-api.json file. This configuration includes a RateLimit filter, which allows 20 requests every 10 seconds, and a RewritePath filter, which allows the request endpoint to reach the standard Spring Boot health check endpoint.
{ "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" ] } ] }
Then, use the following command to apply the rule to the 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
You can also view the routes in the portal, as shown in the following screenshot:
Use the following command to access the
test health check
API through the gateway endpoint:curl https://<endpoint-url>/test/api/healthcheck
Use the following commands to query the routing rules:
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}'
The open-source Spring Cloud Gateway project includes many built-in filters for use in Gateway routes. Spring Cloud Gateway provides many custom filters in addition to the filters included in the OSS project.
The following example shows how to apply the AddRequestHeadersIfNotPresent
filter to a route:
[
{
"predicates": [
"Path=/api/**",
"Method=GET"
],
"filters": [
"AddRequestHeadersIfNotPresent=Content-Type:application/json,Connection:keep-alive"
]
}
]
Then, apply the route definition using the following Azure CLI command:
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>
For more information on available route filters, see How to use VMware Spring Cloud Gateway Route Filters with the Azure Spring Apps Enterprise plan.