Spring Cloud Gateway for VMware Tanzu is based on the open-source Spring Cloud Gateway project (see the open-source project's documentation). A Gateway service instance is configured with one or more routes. A route is associated with an app and includes the components listed below.

Component Explanation
URI The destination URI of the route.
Predicates A collection of Java 8 predicates used to match various pieces of the incoming HTTP request.
Filters A collection of Spring WebFilters (GatewayFilters) used to modify the request or response before or after sending the response.

The open-source Spring Cloud Gateway project includes a number of built-in predicate factories and filter factories. For more information about these factories, see the open-source project's documentation about Route Predicate Factories and GatewayFilter Factories.

For information about the custom route filters added by Spring Cloud Gateway for VMware Tanzu, see Route Filters. For more information about configuring routes for a Spring Cloud Gateway for VMware Tanzu service instance, see the following sections.

Route Parameters

You can configure routes for a Gateway service instance using the Cloud Foundry Command Line Interface (cf CLI) tool. When running cf cLI commands such as cf bind-service, you can use the -c flag to provide a JSON object that specifies the route configuration.

Route parameters accepted for the Gateway are listed in the following table. The example JSON objects shown in the table are not valid configuration.

Note: The path /scg-dashboard is reserved for the Gateway service instance's dashboard and cannot be used in the path of a route.

Parameter Function Example in a Route JSON Object
order Added in v1.0.3. The order of the route, used by the Gateway to determine which route to use when paths and predicates of multiple routes match a single request. Optional.
{ "order": 1 }
uri The destination URI of the route. Optional when binding an app to a Gateway service.
{ "uri": 
"lb://greeting.apps.internal" }
path The path of the route. Adds the Path predicate, with the specified path, to the route's list of predicates, and adds the StripPrefix=1 filter to the route's list of filters. Optional.
{ "path": "/greeting" }
method The HTTP request method(s) to use for the route. Adds the Method predicate, with the specified HTTP method(s), to the route's list of predicates. Optional.
{ "method": "GET,POST" }
predicates The collection of predicates applied for the route. Optional.
{ "predicates": 
[ "Header=X-Request-Id, \d+" ] }
filters The collection of filters applied for the route. Optional.
{ "filters": [ "StripPrefix=1" ] }
metadata.connect-timeout In milliseconds, the connection timeout to use for the route.
{ "metadata": { "connect-timeout": 300 } }
metadata.response-timeout In milliseconds, the response timeout to use for the route.
{ "metadata": { "response-timeout": 500 } }
sso-enabled Valid values: true, false. If set to true, adds the SsoLogin filter to the route's list of filters. Optional. Default false.
{ "sso-enabled": true }
roles When using SSO, an array of roles required for the user to access the route.
{ "roles": ["ADMIN", "AUDITOR"] }
scopes When using SSO, an array of scopes to request.
{ "scopes": ["my-resource.read", 
"my-resource.write"] }
token-relay Valid values: true, false. If set to true, causes the SSO authorization token for the route to be relayed to the service app. Optional. Default false.
{ "token-relay": true }
tags An array of tags that this API should be grouped under in generated OpenAPI endpoint.
{ "tags": ["Clothing", "Kids"] }

If you omit one or more of the uri, predicates, or filters parameters, the Gateway service instance will use default values gathered from the platform. For example, given the following JSON object:

{ "routes": [ { "path": "/cook/**" } ] }

The Gateway service instance will route all requests to the path /cook/** to an internal URI if the app has been configured with one, or to an external URI if not. The Gateway service instance will also apply the filter StripPrefix=1 to the route.

Configuring App Routes

Spring Cloud Gateway for VMware Tanzu provides a way to dynamically update route configurations either via service binding or via an API after an application has already been bound to a service instance. The following sections will describe each approach.

If you have enabled container-to-container networking, Spring Cloud Gateway for VMware Tanzu will default to using internal routes when updating route configuration to applications.

Updating Routes For a Bound App via API

After an app has been bound to a Gateway service instance, follow the steps below to update the app's route configuration via API. These steps assume that you have an existing app named animals whose route configuration has been updated for a new version in a file named gateway-route-config.json. It is also assumed that animals is already bound to a Gateway service instance named my-gateway.

  1. Retrieve the unique GUID represening the animals app.

    $ cf app animals --guid
    6e41a492-a17c-4b27-83b0-78635baa54b4
    
  2. Obtain the URL of a service instance's backing app for my-gateway.

    $ cf service my-gateway
    Showing info of service my-gateway in org myorg / space dev as user...
    
    name:             my-gateway
    service:          p.gateway
    tags:
    plan:             standard
    description:      Spring Cloud Gateway for VMware Tanzu
    documentation:
    dashboard:        https://my-gateway.apps.example.com/scg-dashboard
    

    Copy the URL given for dashboard, removing the /scg-dashboard path. This is the URL of the service instance's backing app. In the example above, this would be:

    https://my-gateway.apps.example.com
    
  3. Update route configuration for the app animals via the routes actuator endpoint on the my-gateway service instance:

    $ curl -k -X PUT https://my-gateway.apps.example.com/actuator/bound-apps/6e41a492-a17c-4b27-83b0-78635baa54b4/routes -d "@./gateway-route-config.json" -H "Authorization: $(cf oauth-token)" -H "Content-Type: application/json"
    ...
    < HTTP/1.1 204 No Content
    ...
    

    Note: A HTTP response of `204 No Content` represents a successful update of the route configuration for the application on the service instance.

  4. Verify that the new app and updated route configuration function as desired.

Adding Routes When Binding an App

NOTE: It is recommended to use update routes for a bound application via API rather than binding. The reason for this is updates are directly updated on the API gateway instance rather than starting Cloud Foundry API calls that could cause unnecessary restarts. There is a chance that this could cause downtime when running with a single instance count.

You can add routes when binding an app to an existing Gateway service instance by passing route configuration parameters to the cf bind-service command. To bind an app called "cook" to an existing Gateway service instance, adding a route for the app, you might run:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**" } ] }'

Apps bound to an existing Gateway service instance with route configuration can ensure that all access to their routes goes through the Gateway by using an internal route. The Spring Cloud Gateway service broker will automatically configure the network policy to allow access between the Spring Cloud Gateway backing app for the service instance and the bound app. If you map only an internal route to the app, all communication must come through the Gateway routes configured during binding.

Important: If an app has both internal and external routes and you include route configuration when binding the app to a Gateway service instance, the Gateway will use the app's internal route. If the app has multiple internal routes, the Gateway will use the app's first internal route.

Updating Routes For a Bound App via Rebind

If you have added route configuration for an app when binding the app to a Gateway service instance, follow the steps below to update the app's route configuration. These steps assume that you have an existing app named animals, which is bound to a Gateway service instance named my-gateway.

Note: The following steps use a blue-green deployment process to prevent downtime when updating routes for a bound app. These steps are not necessary when only pushing a new version of the app itself, without changing its existing route configuration.

  1. Push the app again, appending the suffix -green to the app's name. Do not yet bind this app to the Gateway service instance.

    $ cf push animals-green
    
  2. Rename the existing app, appending the suffix -blue to the app's name.

    $ cf rename animals animals-blue
    
  3. Bind the new version of the app to the Gateway service instance, providing the updated route configuration.

    $ cf bind-service animals-green my-gateway -c '{ "routes": [ { ... } ] }'
    
  4. Verify that the new app and updated route configuration function as desired.

  5. Unbind the old version of the app from the Gateway service instance.

    $ cf unbind-service animals-blue my-gateway
    
  6. Delete the old version of the app.

    $ cf delete animals-blue
    

Service Parameters

In order to avoid repetition across all or most API routes in their route configuration, the following properties can be defined at service level:

Parameter Function Example in a Route JSON Object
predicates The collection of predicates to be applied to all routes. Optional.
{ "service": { "predicates": 
[ "Header=X-Request-Id, \d+" ] }, "routes": [ ... ] }
filters The collection of filters to be applied to all routes. Optional.
{ "service": { "filters": [ "StripPrefix=1" ] }, "routes": [ ... ] }
sso-enabled Valid values: true, false. If set to true, adds the SsoLogin filter to all routes, except when overriden with sso-enabled set to false at route level. Optional. Default false.
{ "service": { "sso-enabled": true }, "routes": [ ... ] }
token-relay Valid values: true, false. If set to true, causes the SSO authorization token for all routes to be relayed to the service app, except when overriden with token-relay set to false at route level. Optional. Default false.
{ "service": { "token-relay": true }, "routes": [ ... ] }

OpenApi Schema References

OpenApi references can be used by multiple API routes so that they don't have to duplicate definitions in route configuration. It works via the $ref property, which targets an object in the openapi section. Currently, this feature is only supported for requests and responses.

In the following example, we're referencing PetBody and Pet:

{
  "routes": [
    {
      "path": "/api/animals/{animalId}/adoption-requests",
      "method": "POST",
      "model": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/requestBodies/PetBody",
                "required": [ "adopterName", "email" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          }
        }
      }
    }
  ],
  "openapi": {
    "components": {
      "requestBodies": {
        "PetBody": {
          "$ref": "#/components/schemas/Pet"
        }
      },
      "schemas": {
        "Pet": {
          "type": "object",
          "properties": {
            "adopterName": {
              "type": "string"
            },
            "email": {
              "type": "string",
              "format": "email"
            },
            "notes": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
check-circle-line exclamation-circle-line close-line
Scroll to top icon