You can bind a service instance to a route for the purpose of adding preprocessing to your Cloud Foundry app requests.

NoteThe procedures in this topic use the Cloud Foundry Command Line Interface (cf CLI). You can also manage route services using Apps Manager. For more information, see the Manage Route Services section of the Managing your orgs and spaces using Apps Manager topic.

Route services are a class of Marketplace Services that perform filtering or content transformation on app requests and responses. For more information about Marketplace Services, see Managing services and User-provided service instances.

Route services exist to help remove the burden on developers who would otherwise have to implement these functions themselves. Popular use cases for route services include rate limiting, authorization, and caching. A route service might reject requests or, after some transformation, pass requests to apps.

To use route services, developers must first create a service instance, choosing from compatible Marketplace services. Developers then bind this service instance to a route, and all requests for the route are preprocessed by the service instance. While some services can support instances being bound to both routes and apps, these operations have different effects. For app requests and responses to be routed through a route service, the service instance must be bound to the route.

To view an example demonstrating the use of a sample route service, see Route Services in Pivotal Cloud Foundry on YouTube.

Bind a route to a service instance

You must install the Cloud Foundry Command Line Interface (cf CLI) to bind a route to a service instance. For more information, see Installing the cf CLI.

Important Gorouter rejects WebSocket requests for routes that are bound to route services. These requests return a 503 error and a X-Cf-Routererror route_service_unsupported header.

Run cf bind-route-service to bind a route from an app to a service instance.

The following example binds the route from my-app.shared-domain.example.com to the service instance my-route-service.

$ cf bind-route-service shared-domain.example.com my-route-service --hostname my-app

Binding route my-app.shared-domain.example.com to service instance my-route-service in org my-org / space my-space as developer...
OK

Caution When binding a service instance to a route, Cloud Foundry might have proxy requests for the route to the service instance, or configure a network component already in the request path.

Bind with parameters

Some services support additional configuration parameters supplied with the bind request. You can pass service-specific configuration parameters in a valid JSON object, provided either in-line or in a file. For a list of supported configuration parameters, see the documentation for the particular service offering you bind to.

This example binds the route from my-app.shared-domain.example.com to the service instance my-route-service, and passes configuration parameters in-line.

$ cf bind-route-service shared-domain.example.com my-route-service --hostname my-app -c '{"rate_limit_threshold_rps":10000}'

Binding service my-db to app rails-sample in org console / space development as user@example.com...
OK

This example binds the route from my-app.shared-domain.example.com to the service instance my-route-service, and passes configuration parameters in a file, /tmp/config.json.

$ cf bind-route-service shared-domain.example.com my-route-service --hostname my-app -c /tmp/config.json

Binding route my-app.shared-domain.example.com to service instance my-route-service in org my-org / space my-space as developer...
OK

Unbind a route from a service instance

You must install the Cloud Foundry Command Line Interface (cf CLI) to bind a route to a service instance. For more information, see Installing the cf CLI.

Run the cf unbind-route-service command to unbind a route from an app to a service instance.

This example removes the route from my-app.shared-domain.example.com to the service instance my-route-service.

$ cf unbind-route-service shared-domain.example.com my-route-service --hostname my-app

Unbinding might leave apps mapped to route my-app.shared-domain.example.com vulnerable e.g. if service instance my-route-service provides authentication. Do you want to proceed?> y

Unbinding route my-app.shared-domain.example.com from service instance my-route-service in org my-org / space my-space as developer...
OK