Page last updated:
This topic describes features of HTTP routing handled by the Gorouter, which is part of the Cloud Foundry (CF) routing tier.
The Gorouter 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
JSESSIONIDcookie in responses. The app generates a
JSESSIONIDas a long hash in the following format:
If an app returns a
JSESSIONIDcookie to a client request, the CF routing tier generates a unique
VCAP_IDfor the app instance based on its GUID in the following format:
On subsequent requests, the client must provide both the
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 Gorouter attempts to route the request to a different instance of the app. If the Gorouter 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 traffic passed from the Gorouter to an app includes the following HTTP headers:
X-Forwarded-Protogives 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-Protowith the scheme of HTTP.
X-Forwarded-Forgives the IP address of the client originating the request.
If your load balancer terminates TLS upstream from the Gorouter, it must append these headers to requests forwarded to the Gorouter. For more information, see the Securing Traffic into Cloud Foundry topic.
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.
When the Zipkin feature is enabled in Cloud Foundry, the Gorouter examines the HTTP request headers and performs the following:
- If the
X-B3-SpanIdHTTP 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 Gorouter access log message for the request:
- If both
X-B3-SpanIdHTTP 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-ParentSpanheader, and sets to the value of the span id in the request. In addition to these trace and span ids, the Gorouter access log message for the request includes
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.
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:
- Obtain the GUID of your app:
$ cf app YOUR-APP --guid
- List your app instances and retrieve the index number of the instance you want to debug:
$ cf app YOUR-APP
- Make a request to the app route using the HTTP header
X-CF-APP-INSTANCEset 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"
Applications that require mutual TLS (mTLS) need metadata from client certificates to authorize requests. Cloud Foundry supports this use case without bypassing layer-7 load balancers and the Gorouter.
The HTTP header
X-Forwarded-Client-Cert (XFCC) may be used to pass the originating client certificate along the data path to the application. Each component in the data path must trust that the downstream component has not allowed the header to be tampered with.
If you configure the load balancer to terminate TLS and set the XFCC header from the received client certificate, then you must also configure the load balancer to strip this header if it is present in client requests. This configuration is required to prevent spoofing of the client certificate.
The following sections describe supported deployment configurations.
By default, Gorouter forwards arbitrary headers that are not otherwise mentioned in the docs; this includes the XFCC header.
For applications to receive the XFCC header, configure your load balancer to set the XFCC header with the contents of the client certificate received in the TLS handshake.
This mode is enabled when the TLS terminated for the first time at infrastructure load balancer option is selected in the Networking configuration screen of the PAS tile.
This option allows you to configure support for the XFCC header while leveraging HAProxy. When selected, HAProxy sets the XFCC header to the contents of the client certificate received in the TLS handshake.
Selecting this configuration requires that the load balancer in front of HAProxy is configured to pass through the TLS handshake to HAProxy via TCP.
This mode is enabled when the TLS terminated for the first time at HAProxy option is selected in the Networking configuration screen of the PAS tile.
HAProxy trusts the Diego intermediate certificate authority. This trust is enabled automatically and permits mutual authentication between applications that are running on Pivotal Cloud Foundry.
If the Gorouter is the first component to terminate TLS, such that it receives the certificate of the originating client in the mutual TLS handshake, the operator should select this option. When selected, Gorouter sets the XFCC header to the contents of the client certificate received in the TLS handshake and strips the XFCC header when present in a request.
Selecting this configuration requires that the load balancer in front of Gorouter is configured to pass through TLS handshake to Gorouter via TCP.
This mode is enabled when the TLS terminated for the first time at the Router option is selected in the Networking configuration screen of the PAS tile.
Gorouter trusts the Diego intermediate certificate authority. This trust is enabled automatically and permits mutual authentication between applications that are running on Pivotal Cloud Foundry.
Depending on your needs, you can configure your deployment to terminate SSL/TLS at the Gorouter, at the Gorouter and the load balancer, or at the load balancer only. For more information, see the Securing Traffic into Cloud Foundry topic.
If the Gorouter cannot establish a TCP connection with a selected application instance, the Gorouter considers the instance ineligible for requests for 30 seconds, and the Gorouter transparently attempts to connect to another application instance. Once the Gorouter has established a TCP connection with an application instance, the Gorouter forwards the HTTP request.
See the Round-Robin Load Balancing section below for more information about how the Gorouter forwards requests to application instances.
The Gorouter uses the round-robin algorithm for load balancing incoming requests to application instances. The Gorouter 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.
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 Gorouter supports this upgrade handshake, and will hold the TCP connection open with the selected application instance. To support WebSockets, the operator must configure the load balancer correctly. Depending on the configuration, clients may have to use a different port for WebSocket connections, such as port 4443, or a different domain name. For more information, see the Supporting WebSockets topic.
From Frontend Clients
The Gorouter supports keepalive connections from clients; it will not close the TCP connection with clients immediately after returning an HTTP response. It is up to clients to close these connections.
To Backend Servers
By default, the Gorouter closes the TCP connection with an app instance or system component after receiving an HTTP response.
When Keepalive Connections is enabled Gorouter will maintain established TCP connections to backends, with a configurable maximum that limits the number of total idle connections from each Gorouter. The Gorouter will reuse idle connections for routing of subsequent requests if one exists for the selected backend, lowering latency and increasing throughput. If no idle connection exists, a new connection will be established, and if the Gorouter limit has not been reached that connection will be maintained. The number of idle connections from each Gorouter to an individual backend is limited to 100. Operators should see Router Idle Keepalive Connections for details.