Configuring CF to Route Traffic to Apps on Custom Ports
Page last updated:
This topic describes how to configure Cloud Foundry to route requests to apps that receive requests on custom ports.
Overview
By default, apps only receive requests on port 8080
for both HTTP and TCP routing. Configuring custom app ports allows developers to bring workloads onto
Cloud Foundry that receive requests on ports other than 8080
. The following list describes some example use cases:
Serving web client requests on one port and offering stats and debugging on another
Using TCP protocols that require multiple ports
Running Docker images on Cloud Foundry
To use the apps
and route_mappings
Cloud Controller API endpoints to update the ports on which the app can receive requests, see Procedure below.
Flow of a Request to an App
The following table describes the Network Address Translation that occurs in the data path of a client request.
Port Type | Description | Network Hop |
---|---|---|
Route port | The port to which a client sends a request | Client to load balancer, load balancer to Gorouter |
Back end port | The port on the VM where an app container is hosted, which is unique to the container | Gorouter to Diego Cell |
App port | The port on the container, which must match a port on which the app is configured to receive requests | Diego Cell to app container |
The procedure in this document discusses configuring app ports.
The following diagram shows an example data path and Network Address Translation for TCP routing:
For HTTP routing, the route port is always 80
or 443
.
Prerequisites
Before following the procedure to configure routing to your app on custom ports, ensure that you have the following:
An app pushed to Cloud Foundry that can receive requests on one or more custom ports.
Routes for which you want traffic forwarded to your app on custom ports, which are mapped to the app.
Note: If your app receives requests on two ports, and you want clients to be able to send requests to both of them, create two routes. These routes can be from HTTP or TCP domains. In Procedure below, you use API endpoints to map these routes to your app on the ports it uses to receive requests. For more information, see Routes and Domains.
Procedure
To configure your app to receive HTTP or TCP requests on custom ports:
In a terminal window, run:
cf app APP-NAME --guid
Where
APP-NAME
is the name of your app.From the terminal output, record the following:
- Under
guid
, the global unique identifier (GUID) of your app. - Under
type
, the process type your app uses.
- Under
Retrieve the GUIDs of the routes for your app by running one of the following commands, depending on whether your app uses HTTP or TCP routes:
For HTTP routes, run:
cf curl /v3/apps/APP-GUID/routes?hosts=ROUTE-HOSTNAME
Where:
APP-GUID
is the GUID of your app that you recorded in the previous step.ROUTE-HOSTNAME
is the subdomain of the domain associated with the route. For example, in the routeexample-app.shared-domain.example.com
, the hostname isexample-app
.
For TCP routes, run:
cf curl /v3/apps/APP-GUID/routes?port=PORT
Where:
APP-GUID
is the GUID of your app that you recorded in the previous step.PORT
is the port to which the TCP route sends requests.
From the terminal output, record the GUIDs of the routes for your app.
For each route, update the ports to which it sends requests by running:
cf curl -X PATCH /v3/routes/ROUTE-GUID/destinations -d '{ "destinations": [ { "app": { "guid": "APP-GUID", "process": { "type": "PROCESS-TYPE" } }, "port": PORT, "protocol": "PROTOCOL" } ] }'
Where:
APP-GUID
is the GUID of your app that you recorded in a previous step.ROUTE-GUID
is the GUID of a route that you recorded in the previous step.PORT
is a custom port on which your app is configured to receive requests.PROTOCOL
is the protocol that the route uses. For HTTP routes, this value is eitherhttp1
orhttp2
. For TCP routes, this value istcp
.PROCESS-TYPE
is the value oftype
that you recorded in a previous step. This value is usuallyweb
.
Note: This API call removes all destinations for a route and replaces them with the destinations you provide in the API request.
Additional Resources
The following additional resources provide more information about configuring custom app ports:
For more information about making requests to the Cloud Controller API’s
apps
endpoints, see the CAPI V3 documentation.For more information about making requests to the Cloud Controller API’s
routes
endpoints, see the CAPI V3 documentation.