custom-ports.html.md.erb

---
title: Configuring Cloud Foundry to route traffic to apps on custom ports
owner: CF for VMs Networking
---

<%# Reset page title based on platform type %>
<% if vars.platform_code != 'CF' %>

<% set_title("Configuring", vars.app_runtime_abbr, "to Route Traffic to Apps on Custom Ports") %>

<% end %>


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
<%= vars.app_runtime_abbr %> that receive requests on ports other than `8080`. Here are some example use cases:

* Serving web client requests on one port, and stats and debugging on another

* Using TCP protocols that require multiple ports

* Running Docker images on <%= vars.app_runtime_abbr %>

To use the `apps` and `route_mappings` Cloud Controller API endpoints to update the ports so the the app can receive requests, see [Procedure](#procedure).

## <a id='flow'></a> Flow of a request to an app

The 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 application 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 application container |

The following diagram shows an example data path and Network Address Translation for TCP routing:

![alt-text="Traffic flow-diagram for data path and Network Address Translation for TCP routing"](./images/route_ports.png)

For HTTP routing, the route port is always `80` or `443`.

## <a id='prerequisite'></a> Prerequisites

Before you follow the procedure to configure routing to your app on custom ports, you must have:

* An app pushed to <%= vars.app_runtime_abbr %> 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.

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.

## <a id='procedure'></a> Procedure

In the following procedure, use API endpoints to map the routes to your app on the ports it uses to receive requests.
For more information about routes, see <a href="deploy-apps/routes-domains.html">Routes and Domains</a>.</p>

To configure your app to receive HTTP or TCP requests on custom ports:

1. Run:

    ```console
    cf app APP-NAME --guid
    ```

    Where `APP-NAME` is the name of your app.

2. From the output, record:
  * Under `guid`, the global unique identifier (GUID) of your app.
  * Under `type`, the process type your app uses.

3. Retrieve the GUIDs of the routes for your app by running one of these commands, depending on whether your app uses HTTP or TCP routes:
    * For HTTP routes, run:

        ```console
        cf curl /v3/apps/APP-GUID/routes?hosts=ROUTE-HOSTNAME
        ```

        Where:
        <ul>
          <li><code>APP-GUID</code> is the GUID of your app that you recorded in an earlier step.</li>
          <li><code>ROUTE-HOSTNAME</code> is the subdomain of the domain associated with the route. For example, in the route <code>example-app.<%= vars.app_domain %></code>, the host name is <code>example-app</code>.</li>
        </ul>
    * For TCP routes, run:

        ```console
        cf curl /v3/apps/APP-GUID/routes?port=PORT
        ```

        Where:
        <ul>
          <li><code>APP-GUID</code> is the GUID of your app that you recorded in an earlier step.</li>
          <li><code>PORT</code> is the port to which the TCP route sends requests.</li>
        </ul>

4. From the output, record the GUIDs of the routes for your app.

5. For each route, update the ports to which it sends requests by running:

    ```console
    cf curl -X PATCH /v3/routes/ROUTE-GUID/destinations -d '{
    "destinations": [
        {
          "app": {
            "guid": "APP-GUID",
            "process": {
              "type": "PROCESS-TYPE"
            }
          },
          "port": PORT,
          "protocol": "PROTOCOL"
        }
      ]
    }'
    ```

    Where:
    <ul>
      <li><code>APP-GUID</code> is the GUID of your app that you recorded in an earlier step.</li>
      <li><code>ROUTE-GUID</code> is the GUID of a route that you recorded in an earlier step.</li>
      <li><code>PORT</code> is a custom port on which your app is configured to receive requests.</li>
      <li><code>PROTOCOL</code> is the protocol that the route uses. For HTTP routes, this value is either <code>http1</code> or <code>http2</code>. For TCP routes, this value is <code>tcp</code>.</li>
      <li><code>PROCESS-TYPE</code> is the value of <code>type</code> that you recorded in an earlier step. This value is usually <code>web</code>.</li>
    </ul>

    <p class="note caution">
    <span class="note__title"><strong>Caution</strong></span>
    This API call removes all destinations for a route and replaces them with the destinations you provide in the API request.</p>

## <a id='additional-resources'></a> Additional resources

* For more information about making requests to the Cloud Controller API (CAPI) `apps` endpoints, see the [CAPI V3 documentation](https://v3-apidocs.cloudfoundry.org/index.html#apps).