Here are instructions for binding 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 Apps and Service Instances 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 the Managing Services and User-provided Service Instances topics.
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 may 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 may 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 the Installing the cf CLI topic.
Gorouter rejects WebSockets 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 the cf bind-route-service command 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
Note When binding a service instance to a route, Cloud Foundry may 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.
The following 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 [email protected]...
OK
The following 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 the Installing the cf CLI topic.
Run the cf unbind-route-service command to unbind a route from an app to a service instance.
The following 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 may 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
