Configuring Routes

Page last updated:

Pivotal Spring Cloud Gateway 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
ID An arbitrary ID given to the route. Optional.
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 Pivotal Spring Cloud Gateway, see Route Filters. For more information about configuring routes for a Pivotal Spring Cloud Gateway service instance, see the following sections.

Using Internal Routes and Container-to-Container Networking

If you have enabled container-to-container networking, you can allow your apps to communicate using internal routes. When using internal routes and container-to-container networking, you can use the lb scheme (as lb://) to refer to an app. This ensures use of TLS/SSL through the entire request to the service app and automatic load balancing across all of the service app’s instances.

Pivotal recommends use of internal routes via container-to-container networking and use of the lb scheme for app URLs given to Pivotal Spring Cloud Gateway service instances. The examples given in this topic assume this approach.

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.

Parameter Function Example in a Route JSON Object
id The ID of the route. Optional.
{ "id": "myapp" }
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" ] }
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 }

If you omit one or more of the uri, predicates, or filters parameters, the Gateway service instance will use default values gathered from Pivotal 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.

Adding Routes When Binding an App

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.