Configuring Routes

Page last updated:

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
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 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
id The ID of the route. Optional.
{ "id": "myapp" }
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 }

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.

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.

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
  1. 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.

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

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