Route Services

Page last updated:

This documentation is intended for service authors who are interested in offering a service to a Cloud Foundry services marketplace. Developers interested in consuming these services can read the Manage Application Requests with Route Services topic.

Note: Route Services require Diego. Your deployment must use the Diego architecture or you must enable Diego for your app.


Cloud Foundry application developers may wish to apply transformation or processing to requests before they reach an application. Common examples of use cases are authentication, rate limiting, and caching services. Route Services are a new kind of Marketplace Service that developers can use to apply various transformations to application requests by binding an application’s route to a service instance. Through integrations with service brokers and optionally with the Cloud Foundry routing tier, providers can offer these services to developers with a familiar automated, self-service, and on-demand user experience.


Cloud Foundry supports three models for Route Services: fully-brokered services; static, brokered services; and user-provided services. In each case, you configure a route service to process traffic addressed to an app.

Fully-Brokered Service

In this model, the CF router receives all traffic to apps in the deployment before any processing by the route service. Developers can bind a route service to any app, and if an app is bound to a route service, the CF router sends its traffic to the service. After the route service processes requests, it sends them back to the load balancer in front of the CF router. The second time through, the CF router recognizes that the route service has already handled them, and forwards them directly to app instances.

Fully brokered

The route service can run inside or outside of CF, so long as it fulfills the Service Instance Responsibilities to integrate it with the CF router. A service broker publishes the route service to the CF marketplace, making it available to developers. Developers can then create an instance of the service and bind it to their apps with the following commands:


Developers configure the service either through the service provider’s web interface or by passing arbitrary parameters to their cf create-service call, through the -c flag.


  • Developers can use a Service Broker to dynamically configure how the route service processes traffic to specific applications.
  • Adding route services requires no manual infrastructure configuration.
  • Traffic to apps that do not use the service makes fewer network hops; requests for those apps do not pass through the route service.


  • Traffic to apps that use the route service makes additional network hops, as compared to the static model.

Static, Brokered Service

In this model, an operator installs a static routing service, which might be a piece of hardware, in front of the Load Balancer. The routing service runs outside of Cloud Foundry and receives traffic to all apps running in the CF deployment. The service provider creates a service broker to publish the service to the CF marketplace. As with a fully-brokered service, a developer can use the service by instantiating it with cf create-service and binding it to an app with cf bind-route-service.

Static, brokered

In this model, you configure route services on an app-by-app basis. When you bind a service to an app, the service broker directs the routing service to process that app’s traffic rather than pass the requests through unchanged.


  • Developers can use a Service Broker to dynamically configure how the route service processes traffic to specific applications.
  • Traffic to apps that use the route service takes fewer network hops.


  • Adding route services requires manual infrastructure configuration.
  • Unnecessary network hops for traffic to apps that do not use the route service; requests for all apps hosted by the deployment pass through the route service component.

User-Provided Service

If a route service is not listed in the CF marketplace by a broker, a developer can still bind it to their app as a User-Provided service. The service can run anywhere, either inside or outside of CF, but it must fulfill the integration requirements described in Service Instance Responsibilities. The service also needs to be reachable by an outbound connection from the CF router.


This model is identical to the fully-brokered service model, except without the broker. Developers configure the service manually, outside of Cloud Foundry. They can then create a user-provided service instance and bind it to their application with the following commands, supplying the URL of their route service:

cf create-user-provided-service SERVICE_INSTANCE -r ROUTE_SERVICE_URL cf bind-route-service DOMAIN SERVICE_INSTANCE [--hostname HOSTNAME]


  • Adding route services requires no manual infrastructure configuration.
  • Traffic to apps that do not use the service makes fewer network hops; requests for those apps do not pass through the route service.


  • Developers must manually provision/configure route services out of the context of Cloud Foundry; no service broker automates these operations.
  • Traffic to apps that use the route service makes additional network hops, as compared to the static model.

Architecture Comparison

The models above require the broker and service instance responsibilities below, as summarized in the following table:

Route Services Architecture Fulfills CF Service Instance Responsibilities Fulfills CF Broker Responsibilities
Fully-Brokered Yes Yes
Static Brokered No Yes
User-Provided Yes No

Enabling Route Services in Cloud Foundry

To enable support for Route Services in a Cloud Foundry deployment, the operator must provide a passphrase used by Gorouter to encrypt a header that is sent with the request to the route service. Gorouter uses this header to validate the request sent by the route service to the application route. The passphrase is configured in the cf-release manifest.
route_services_secret: YOUR-SECRET-PASSPHRASE

Note: The route_services_secret property should be a robust passphrase. See the Gorouter spec in cf-release for more details.

Route Service instances should send requests to the value of x-cf-forwarded-url, obeying the scheme. The scheme is https by default; for environments that don’t support TLS termination, this property can be set to false.
route_services_recommend_https: true
The CF router will only forward requests to Route Services over SSL. By default, certificates provided by Route Services must be signed by a trusted CA. If they are not, the CF router will reject the request. In development environments this concern may be unreasonable. To disable SSL cert validation, modify the following property:
ssl_skip_validation: true

Service Instance Responsibilities

The following applies only when a broker returns route_service_url in the bind response.

How It Works

Binding a service instance to a route will associate the route_service_url with the route in the Cloud Foundry router. All requests for the route will be proxied to the URL specified by route_service_url.

Once a route service completes its function, it is expected to forward the request to the route the original request was sent to. The Cloud Foundry router will include a header that provides the address of the route, as well as two headers that are used by the route itself to validate the request sent by the route service.


The X-CF-Forwarded-Url header contains the URL of the application route. The route service should forward the request to this URL.

The route service should not strip off the X-CF-Proxy-Signature and X-CF-Proxy-Metadata, as the Gorouter relies on these headers to validate the request.

SSL Certificates

When Cloud Foundry is deployed in a development environment, certificates hosted by the load balancer will be self-signed (not signed by a trusted certificate authority). When the route service has finished processing an inbound request, and makes a call to the value of X-CF-Forwarded-Url, be prepared to accept the self-signed certificate when integrating with a non-production deployment of Cloud Foundry.


Route services must forward the request to the application route within the number of seconds configured by the router.route_service_timeout property (default 60 seconds).

In addition, all requests must respond in the number of seconds configured by the request_timeout_in_seconds property (default 900 seconds).

Timeouts are configurable for the router using the cf-release BOSH deployment manifest. For more information, see the spec.

Broker Responsibilities

Catalog Endpoint

Brokers must include requires: ["route_forwarding"] for a service in the catalog endpoint. If this is not present, Cloud Foundry will not permit users to bind an instance of the service to a route.

Binding Endpoint

When users bind a route to a service instance, Cloud Foundry will send a bind request to the broker, including the route address with bind_resource.route. A route is an address used by clients to reach apps mapped to the route. The broker may return route_service_url, containing a URL where Cloud Foundry should proxy requests for the route. This URL must have a https scheme, otherwise the Cloud Controller will reject the binding. route_service_url is optional; not returning this field enables a broker to dynamically configure a network component already in the request path for the route, requiring no change in the Cloud Foundry router.

Example Route Services

  • Logging Route Service: This route service can be pushed as an app to Cloud Foundry. It fulfills the service instance responsibilities above and logs requests received and sent. It can be used to see the route service integration in action by tailing its logs.
  • Rate Limiting Route Service: This example route service is a simple Cloud Foundry app that provides rate limiting to control the rate of traffic to an application.
  • Spring Boot Example: Logs requests received and sent; written in Spring Boot


The following instructions show how to use the Logging Route Service described in Example Route Services to verify that when a route service is bound to a route, requests for that route are proxied to the route service.

A video of this tutorial is available on Youtube.

Requires CLI version 6.16 or above.

  1. Push the Logging Route Service as an app.

    $ cf push logger
  2. Create a user-provided service instance, and include the route of the Logging Route Service you pushed as route_service_url. Be sure to use https for the scheme.

    $ cf create-user-provided-service mylogger -r
  3. Push a sample app like Spring Music. By default this will create a route

    $ cf push spring-music
  4. Bind the user-provided service instance to the route of your sample app. The bind-route-service command takes a route and a service instance; the route is specified in the following example by domain and hostname spring-music.

    $ cf bind-route-service mylogger --hostname spring-music
  5. Tail the logs for your route service.

    $ cf logs logger
  6. Send a request to the sample app and see in the route service logs that the request is forwarded to it.

    $ curl
Create a pull request or raise an issue on the source for this page in GitHub