Configuring TAS for VMs to Route Traffic to Apps on Custom Ports

By default, apps only receive requests on port 8080 for both HTTP and TCP routing, and so must be configured, or hardcoded, to listen on this port. Configuring custom app ports allows developers to bring workloads onto TAS for VMs that listen on ports other than 8080. Some example use cases are:

Serving web client requests on one port and offering stats/debug on another
Using TCP protocols that require multiple ports
Running Docker images on TAS for VMs

The procedure below describes how to use the apps and route_mappings Cloud Controller API endpoints to update the ports the app can receive requests on.

Flow of a Request to an App

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 a client sends a request to	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; this must match a port the app is configured to listen on	Diego Cell to app container

The following diagram provides an example data path and Network Address Translation for TCP routing. For HTTP routing, the route port is always 80 or 443.

alt-text=Traffic-flow-diagram

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, you must have:

An app pushed to TAS for VMs that can listen 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 traffic on custom ports:

Retrieve the GUID of your app by running:
```
cf app APP-NAME --guid
```
Where APP-NAME is the name of your app.
Configure TAS for VMs with the ports your app is listening on by running:
```
cf curl /v2/apps/APP-GUID -X PUT -d '{"ports": [PORT1, PORT2, PORT3...]}'
```
Where:
- APP-GUID is the GUID of your app.
- PORT1, PORT2, PORT3... is a comma-separated list of the ports on which you want your app to receive traffic.
Retrieve the GUID of the route to which clients make requests, and for which TAS for VMs routes requests to the app on a custom port. Use one of the following options:
- For a TCP route with a hostname, retrieve its GUID by running:
```
cf curl /v2/routes?q=host:HOST-NAME
```
  Where HOST-NAME is the hostname for the route. By default, this is the name of your app.
- For a TCP route without a hostname, retrieve its GUID by running:
```
cf curl /v2/apps/APP-GUID/routes
```
Check and update the route mappings for your app by running:
```
cf curl /v2/routes/ROUTE-GUID/route_mappings
cf curl /v2/route_mappings -X POST -d '{"app_guid": "APP-GUID", "route_guid": "ROUTE-GUID", "app_port": PORT1}'
```
Where:
- APP-GUID is the GUID of your app.
- ROUTE-GUID is the GUID of the route at which the app serves.
- PORT1 is the app port, or one of the app ports, that you added in the previous step.
Repeat the previous two steps for each port that you want your app to receive requests on.

Important If you are trying to remove an app port, you need to delete the associated route mapping before you can update the app to remove the port.

Additional resources

For additional resources related to configuring custom app ports:

For more information about making requests to the Cloud Controller apps endpoint, see Updating an App in the Cloud Controller API documentation.
For more information about making requests to the Cloud Controller route_mappings endpoint, see Mapping an App and a Route in the Cloud Controller API documentation.
For an example multi-port app, see the cf-acceptance-tests repository on GitHub.
For a demo procedure written by an open source CF user, see the “Multiple App Ports” Demo on Cloud Foundry on GitHub.