HTTP Routing

Page last updated:

This topic describes features of HTTP routing handled by the Cloud Foundry (CF) router.

Session Affinity

The CF router supports session affinity, or sticky sessions, for incoming HTTP requests to compatible apps.

With sticky sessions, when multiple instances of an app are running on CF, requests from a particular client always reach the same app instance. This allows apps to store session data specific to a user session.

  • To support sticky sessions, configure your app to return a JSESSIONID cookie in responses. The app generates a JSESSIONID as a long hash in the following format:

    1A530637289A03B07199A44E8D531427
    

  • If an app returns a JSESSIONID cookie to a client request, the CF routing tier generates a unique VCAP_ID for the app instance based on its GUID in the following format:

    323f211e-fea3-4161-9bd1-615392327913
    

  • On subsequent requests, the client must provide both the JSESSIONID and VCAP_ID cookies.

The CF routing tier uses the VCAP_ID cookie to forward client requests to the same app instance every time. The JSESSIONID cookie is forwarded to the app instance to enable session continuity. If the app instance identified by the VCAP_ID crashes, the router attempts to route the request to a different instance of the app. If the router finds a healthy instance of the app, it initiates a new sticky session.

Note: CF does not persist or replicate HTTP session data across app instances. If an app instance crashes or is stopped, session data for that instance is lost. If you require session data to persist across crashed or stopped instances, or to be shared by all instances of an app, store session data in a CF marketplace service that offers data persistence.

HTTP Headers

HTTP traffic passed from the CF router to an app includes the following HTTP headers:

  • X-Forwarded-Proto gives the scheme of the HTTP request from the client. The scheme is HTTP if the client made an insecure request or HTTPS if the client made a secure request. Developers can configure their apps to reject insecure requests by inspecting the HTTP headers of incoming traffic and rejecting traffic that includes X-Forwarded-Proto with the scheme of HTTP.

  • X-Forwarded-For gives the IP address of the client originating the request.

If your load balancer terminates TLS upstream from the CF router, it must append these headers to requests forwarded to the CF router.

Zipkin Tracing in HTTP Headers

Zipkin is a tracing system that enables app developers to troubleshoot failures or latency issues. Zipkin provides the ability to trace requests and responses across distributed systems. See Zipkin.io for more information.

The Gorouter examines the HTTP request headers and performs the following:

  • If the X-B3-TraceId and X-B3-SpanId HTTP headers are not present in the request, the Gorouter generates values for these and inserts the headers into the request forwarded to an application. These values are also found in the router access log message for the request: x_b3_traceid and x_b3_spanid).
  • If both X-B3-TraceId and X-B3-SpanId HTTP headers are present in the request, the Gorouter forwards the same value for X-B3-TraceId, generates a new value for X-B3-SpanId, and adds the X-B3-ParentSpan header, and sets to the value of the span id in the request. In addition to these trace and span ids, the router access log message for the request includes x_b3_parentspanid.

Developers can then add Zipkin trace IDs to their application logging in order to trace app requests and responses in Cloud Foundry.

After adding Zipkin HTTP headers to app logs, developers can use cf logs myapp to correlate the trace and span ids logged by the Gorouter with the trace ids logged by their app. To correlate trace ids for a request through multiple apps, each app must forward appropriate values for the headers with requests to other applications.

App Instance Routing in HTTP Headers

Developers who want to obtain debug data for a specific instance of an app can use the HTTP header X-CF-APP-INSTANCE to make a request to an app instance.

Perform the following steps to make an HTTP request to a specific app instance:

  1. Obtain the GUID of your app:
    $ cf app YOUR-APP --guid
  2. List your app instances and retrieve the index number of the instance you want to debug:
    $ cf app YOUR-APP
  3. Make a request to the app route using the HTTP header X-CF-APP-INSTANCE set to the concatenated values of the app GUID and the instance index:
    $ curl app.example.com -H "X-CF-APP-INSTANCE":"YOUR-APP-GUID:YOUR-INSTANCE-INDEX"

SSL/TLS Termination

Depending on your needs, you can configure your deployment to terminate SSL/TLS at the CF router, the CF router and the load balancer, or the load balancer only.

Transparent Retries

If the CF router cannot establish a TCP connection with a selected application instance, the router considers the instance ineligible for requests for 30 seconds, and the router transparently attempts to connect to another application instance. Once the router has established a TCP connection with an application instance, the router forwards the HTTP request.

See the Round-Robin Load Balancing section below for more information about how the router forwards requests to application instances.

Round-Robin Load Balancing

The CF router uses the round-robin algorithm for load balancing incoming requests to application instances. The router maintains a dynamically updated list of application instances for each route, and forwards each request for a given route to the next application instance in the list.

sockets

WebSockets is a protocol providing bi-directional communication over a single, long-lived TCP connection, commonly implemented by web clients and servers. WebSockets are initiated through HTTP as an upgrade request. The CF Router supports this upgrade handshake, and will hold the TCP connection open with the selected application instance.

Was this helpful?
What can we do to improve?
View the source for this page in GitHub