Use Spring Cloud Gateway

Note

Azure Spring Apps is the new name for the Azure Spring Cloud service. Although the service has a new name, you'll see the old name in some places for a while as we work to update assets such as screenshots, videos, and diagrams.

This article applies to: ❌ Basic/Standard tier ✔️ Enterprise tier

This article shows you how to use VMware Spring Cloud Gateway with Azure Spring Apps Enterprise tier 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.

Prerequisites

Configure routes

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 as http://<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 will also be shown 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 or HTTPS, and the default is HTTP. To secure traffic from Spring Cloud Gateway to your HTTPS-enabled application, you need to set the protocol to HTTPS 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 will override the app level routing rule for the same property. You can define the following properties at the app level: predicates, filters, and ssoEnabled. If you use the OpenAPI URI feature to define routes, the only app level routing property to support is filters.

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 will route to.

az spring gateway route-config create \
    --name <route-config-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 will override 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 will be applied to methods in the generated OpenAPI documentation.

Note

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 routes for Spring Cloud Gateway

Use the following steps to create a sample application using Spring Cloud Gateway.

  1. Create a test application in Azure Spring Apps by using the following command:

    az spring app create test-app
    
  2. 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. You'll get a URL in a few minutes. Save the URL to use later.

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

    You can also use Azure CLI to assign the endpoint, as shown in the following command:

    az spring gateway update --assign-endpoint
    
  3. 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 \
        --app-name test-app \
        --routes-file test-api.json
    

    You can also view the routes in the portal, as shown in the following screenshot:

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

  4. Use the following command to access the test health check API through the gateway endpoint:

    curl https://<endpoint-url>/test/api/healthcheck
    
  5. Use the following commands to query the routing rules:

    az configure --defaults group=<resource group name> spring=<service name>
    
    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}'
    

Use filters

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.

Use filters included in Spring Cloud Gateway OSS

You can use Spring Cloud Gateway OSS filters in Spring Cloud Gateway for Kubernetes. Spring Cloud Gateway OSS includes many GatewayFilter factories that are used to create filters for routes. For a complete list of these factories, see the GatewayFilter Factories section in the Spring Cloud Gateway documentation.

Use commercial filters

For more examples of commercial filters, see Commercial Route Filters in the VMware Spring Cloud Gateway documentation. These examples are written using Kubernetes resource definitions.

The following example shows how to use the AddRequestHeadersIfNotPresent filter by converting the Kubernetes resource definition.

Start with the following resource definition in YAML:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayRouteConfig
metadata:
  name: my-gateway-routes
spec:
  service:
    name: myapp
  routes:
  - predicates:
      - Path=/api/**
    filters:
      - AddRequestHeadersIfNotPresent=Content-Type:application/json,Connection:keep-alive

Then, convert spec.routes into the following JSON format:

[
  {
    "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 my-gateway-routes \
    --app myapp
    --routes-file <json-file-with-routes>

Next steps