Configuring routes in Spring Cloud Gateway

You can configure a Spring Cloud Gateway service instance with one or more routes. A route is associated with an app and includes the components listed below.

Spring Cloud Gateway for VMware Tanzu is based on the open-source Spring Cloud Gateway project (see the open-source project's documentation).

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 activated 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 using the 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 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 using 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. See also Using blue-green deployment to reduce downtime in the Tanzu Application Service documentation.

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