You can offer a service to a VMware Tanzu Application Service for VMs (TAS for VMs) services Marketplace.
For information about consuming these services, see Managing apps and services using Apps Manager.
TAS for VMs app developers might want to apply transformation or processing to requests before they reach an app. Common use cases include authentication, rate limiting, and caching services.
Route services are a kind of Marketplace service that you 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 TAS for VMs routing tier, providers can offer these services with a familiar, automated, self-service, and on-demand user experience.
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 Route Services section of the Managing Apps and Service Instances using Apps Manager topic.
TAS for VMs supports the following models for route services, each of which is described in this topic:
In each model, you configure a route service to process traffic addressed to an app.
In the fully-brokered service model, the TAS for VMs router receives all traffic to apps in the deployment before any processing by the route service. You can bind a route service to any app, and if an app is bound to a route service, the TAS for VMs router sends the traffic to the service. After the route service processes requests, it sends it back to the load balancer in front of the TAS for VMs router. The second time through, the TAS for VMs router recognizes that the route service has already handled them, and forwards them directly to app instances.
The route service can run inside or outside of TAS for VMs, as long as it fulfills the Service Instance responsibilities to integrate it with the TAS for VMs router.
A service broker publishes the route service to the TAS for VMs marketplace, and makes it available to developers.
You can then create an instance of the service and bind it to your 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]
You can configure the service either through the service provider web interface or by passing arbitrary parameters to their cf create-service
call through the -c
flag.
Advantages:
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.
Disadvantages:
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 TAS for VMs and receives traffic to all apps running in the TAS for VMs deployment. The service provider creates a service broker to publish the service to the TAS for VMs marketplace. As with a fully-brokered service, you can use the service by instantiating it with cf create-service
and binding it to an app with cf bind-route-service
.
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 passing the requests through unchanged.
Advantages:
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.
Disadvantages:
If a route service is not listed in the TAS for VMs marketplace by a broker, you can still bind it to your app as a user provided service. The service can run anywhere, either inside or outside of TAS for VMs, 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 TAS for VMs router.
This model is identical to the fully-brokered service model, except without the broker. You can configure the service manually, outside of TAS for VMs.
You can then create a user provided service instance and bind it to your app with the following commands,that supply 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]
Advantages:
Disadvantages:
The previous models require the broker and service instance responsibilities summarized in the following table:
Route Services Architecture | Fulfills TAS for VMs Service Instance Responsibilities (1) |
Fulfills TAS for VMs Broker Responsibilities (2) |
---|---|---|
Fully-Brokered | Yes | Yes |
Static Brokered | No | Yes |
User-Provided | Yes | No |
2 - See Broker Responsibilities
The following information applies only when a broker returns route_service_url
in a bind response.
Binding a service instance to a route associates the route_service_url
with the route in the TAS for VMs router. All requests for the route are proxied to the URL specified by route_service_url
.
The TAS for VMs router includes the X-CF-Forwarded-Url
header containing the originally requested URL, as well as the X-CF-Proxy-Signature
and X-CF-Proxy-Metadata
headers used by the router to validate that the route-service sent the request. These headers are described in the Headers section.
The route service must handle requests by either:
2xx
HTTP status codeWhen forwarding a request to the originally requested URL, the route service must forward the X-CF-Forwarded-Url
, X-CF-Proxy-Signature
, and X-CF-Proxy-Metadata
headers on the request. If it doesn’t, it is rejected. When forwarding a request to a location other than the originally requested URL, the route service strips these headers.
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 might choose to forward the request to this URL or to another.
When the Gorouter receives a request with this header, it accepts and forwards the request to the app only if the URL of the request matches the one associated with the token, and the request was received on time. Otherwise, the request is rejected.
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. The route service needs to forward these headers in subsequent requests to the orignal requested URL, so that it knows not to send the request back to the route service but to the app. The headers must NOT be sent in the HTTP response to the GoRouter, only in the new HTTP request to the GoRouter.
CF-hosted Route Services cannot be chained: If the route service forwards the request to a URL to resolve a route for a different app on TAS for VMs, the route must not have a bound route service. Otherwise, the request is rejected as the requested URL does not match the one in the forwarded X-CF-Proxy-Signature
header.
ImportantThe
X-CF-Proxy-Signature
header is an access token. Anyone possessing yourX-CF-Proxy-Signature
token can bypass the route service. Do not share your yourX-CF-Proxy-Signature
token with anyone.
The X-CF-Proxy-Metadata
header aids in the encryption and description of X-CF-Proxy-Signature
.
When TAS for VMs 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 TAS for VMs.
Route services must forward the request to the app route within 60 seconds.
In addition, all requests must respond in 900 seconds.
Brokers must include requires: ["route_forwarding"]
for a service in the catalog endpoint. If this is not present, TAS for VMs does not permit users to bind an instance of the service to a route.
When you bind a route to a service instance, TAS for VMs 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 might return route_service_url
, containing a URL where TAS for VMs proxies 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 allows a broker to dynamically configure a network component already in the request path for the route, requiring no change in the TAS for VMs router.
For more information about bind requests, see the Binding section of the Open Service Broker API (v2.13) specification on GitHub.
Logging Route Service: This route service can be pushed as an app to TAS for VMs. It fulfills the service instance responsibilities 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 TAS for VMs app that provides rate limiting to control the rate of traffic to an app.
The following instructions show how to use the Logging Route Service described in Route Services examples 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 require the Cloud Foundry Command Line Interface (cf CLI) v6.16 or later.
To use the logging route service:
Push the logging route service as an app by running:
cf push logger
Create a user provided service instance, and include the route of the logging route service you pushed as route_service_url
. Make sure to use https
for the scheme.
Run:
cf create-user-provided-service mylogger -r https://logger.cf.example.com
Push a sample app such as Spring Music. By default, this creates a route spring-music.cf.example.com
.
Run:
cf push spring-music
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 cf.example.com
and hostname spring-music
.
Run:
cf bind-route-service cf.example.com mylogger --hostname spring-music
Tail the logs for your route service by running:
cf logs logger
Send a request to the sample app and view in the route service logs that the request is forwarded to it by running:
curl spring-music.cf.example.com