Route Services

Page last updated:

Warning: Pivotal Application Service (PAS) v2.8 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

This topic provides guidance for offering a service to a Pivotal Application Service (PAS) services marketplace. For information about consuming these services, see Manage App Requests with Route Services.


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

Note: The 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.


PAS supports the following three models for route services:

In each model, you configure a route service to process traffic addressed to an app.

Fully-Brokered Service

In the fully-brokered service model, the PAS 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 PAS 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 PAS router. The second time through, the PAS 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 PAS, so long as it fulfills the Service Instance Responsibilities to integrate it with the PAS router. A service broker publishes the route service to the PAS 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:

cf create-service BROKER-SERVICE-PLAN SERVICE-INSTANCE cf bind-route-service YOUR-APP-DOMAIN SERVICE-INSTANCE [--hostname HOSTNAME] [--path PATH]

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 apps.
  • Adding route services requires no manual infrastructure configuration.
  • Traffic to apps that do not use the service makes fewer network hops because 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 the static, brokered service 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 PAS and receives traffic to all apps running in the PAS deployment. The service provider creates a service broker to publish the service to the PAS 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 apps.
  • Traffic to apps that use the route service takes fewer network hops.


  • Adding route services requires manual infrastructure configuration.
  • Traffic to apps that do not use the route service make unnecessary network hops. 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 PAS 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 PAS, 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 PAS router.


This model is identical to the fully-brokered service model, except without the broker. Developers configure the service manually, outside of PAS. They can then create a user-provided service instance and bind it to their app 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 because requests for those apps do not pass through the route service.


  • Developers must manually provision and configure route services out of the context of PAS because 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 summarized in the following table:

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

Enabling Route Services in PAS

You configure Route Services for your deployment in the PAS tile, in the Networking pane. For more information, see Configuring PAS.

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 associates the route_service_url with the route in the PAS router. All requests for the route are proxied to the URL specified by route_service_url.

Once a route service completes its function it may choose to forward the request to the originally requested URL or to another location, or it may choose to reject the request; rejected requests will be returned to the originating requestor. The PAS router includes a header that provides the originally requested URL, as well as two headers that are used by the router itself to validate the request sent by the route service. These headers are described in the sections below.


The following HTTP headers are added by the Gorouter to requests forwarded to route services.


The X-CF-Forwarded-Url header contains the originally requested URL. The route service may choose to forward the request to this URL or to another.


The X-CF-Proxy-Signature header contains an encrypted value which only the Gorouter can decrypt.

The header contains the originally requested URL and a timestamp. When this header is present, the Gorouter rejects the request if the requested URL does not match that in the header, or if a timeout has expired.

X-CF-Proxy-Signature also signals to the Gorouter that a request has transited a route service. If this header is present, the Gorouter does not forward the request to a route service, preventing recursive loops. For this reason, route services should not strip off the X-CF-Proxy-Signature and X-CF-Proxy-Metadata headers.

If the route service forwards the request to a URL different from the originally requested one, and the URL resolves to a route for an app on PAS, the route must not have a bound route service or the request is rejected, as the requested URL does not match the one in the X-CF-Proxy-Signature header.

= X-CF-Proxy-Metadata

The X-CF-Proxy-Metadata header aids in the encryption and description of X-CF-Proxy-Signature.

SSL Certificates

When PAS is deployed in a development environment, certificates hosted by the load balancer are self-signed, and not signed by a trusted Certificate Authority. When the route service finishes 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 PAS.


Route services must forward the request to the app route within 60 seconds.

In addition, all requests must respond in 900 seconds.

Broker Responsibilities

Catalog Endpoint

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

Binding Endpoint

When users bind a route to a service instance, PAS sends 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 PAS should proxy requests for the route. This URL must have an https scheme, or the Cloud Controller rejects the binding. route_service_url is optional, and 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 PAS router.

For more information about bind requests, see the Binding section of the Open Service Broker API (v2.13) spec on GitHub.

Example Route Services

  • Logging Route Service: This route service can be pushed as an app to PAS. 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 PAS app that provides rate limiting to control the rate of traffic to an app.

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

For a video of this tutorial, see Route Services in Pivotal Cloud Foundry 1.7 on YouTube.

These commands requires the Cloud Foundry Command Line Interface (cf CLI) v6.16 or later.

To use the logging route service:

  1. Push the logging route service as an app by running:

    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. Run:

    cf create-user-provided-service mylogger -r
  3. Push a sample app like Spring Music. By default, this creates a route Run:

    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. Run:

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

    cf logs logger
  6. Send a request to the sample app and view in the route service logs that the request is forwarded to it by running: