forked from cloudfoundry/docs-dev-guide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
custom-ports.html.md.erb
103 lines (76 loc) · 4.83 KB
/
custom-ports.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
---
title: Configuring CF to Route Traffic to Apps on Custom Ports
owner: Routing
---
This topic describes how to configure <%= vars.first_product_name %> to route traffic to your apps listening on custom ports.
## <a id="overview"></a> Overview
By default, apps only receive requests on port 8080 for both HTTP and TCP routing, and so must be configured, or hard coded, to listen on this port. Configuring custom app ports allows developers to bring workloads onto <%= vars.product_short %> that listen on ports other than 8080. Here are some example use cases:
* Serving web client requests on one port and offering stats/debug on another
* Using TCP protocols that require multiple ports
* Running Docker images on <%= vars.product_short %>
The [Procedure](#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.
### <a id="flow"></a> 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. The procedure in this document discusses configuring _app ports_ specifically.
<table>
<tr>
<th>Port Type</th>
<th>Description</th>
<th>Network Hop</th>
</tr>
<tr>
<td>Route port</td>
<td>The port a client sends a request to</td>
<td>Client to load balancer, load balancer to Gorouter</td>
</tr>
<tr>
<td>Backend port</td>
<td>The port on the VM where an app container is hosted, which is unique to the container</td>
<td>Gorouter to Diego Cell</td>
</tr>
<tr>
<td>App port</td>
<td>The port on the container; this must match a port the app is configured to listen on</td>
<td>Diego Cell to app container</td>
</tr>
</table>
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`.
## <a id="prerequisite"></a> Prerequisites
Before following the procedure to configure routing to your app on custom ports, you must have the following:
* An app pushed to <%= vars.product_short %> that can listen on one or more custom ports.
* Routes for which you want traffic forwarded to your app on custom ports.
* If your app listens on two ports and you want clients to be able to send requests to both of them, create two routes. These can be from HTTP or TCP domains (see [Routes and Domains](./deploy-apps/routes-domains.html) for more info). Consider an example in which you have two routes: `foo.example.com` and `bar.example.com`. In the following procedure, you use API endpoints to map these routes to your app on the ports it is listening.
## <a id="procedure"></a> Procedure
To configure your app to receive HTTP or TCP traffic on custom ports, do the following:
1. Retrieve the GUID of your app:
```
cf app APP-NAME --guid
```
Where `APP-NAME` is the name of your app
1. Configure <%= vars.product_short %> with the ports your app is listening on:
```
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.
1. Retrieve the GUID of the route to which clients will make requests, and for which Cloud Foundry will route requests to the app on a custom port:
```
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.
1. Update the route mapping for your app:
```
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.
1. Repeat the previous two steps for each port that you want your app to receive requests on.
## <a id="additional-resources"></a> Additional Resources
Here are additional resources related to configuring custom app ports:
* For more information about making requests to the Cloud Controller `apps` endpoint, see [Updating an App](https://apidocs.cloudfoundry.org/6.10.0/apps/updating_an_app.html) 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](https://apidocs.cloudfoundry.org/6.10.0/routes_mapping/mapping_an_app_and_a_route.html).
* For an example multi-port app, see the [cf-acceptance-tests](https://github.com/cloudfoundry/cf-acceptance-tests/tree/master/assets/multi-port-app) repository.
* For a demo procedure written by an open source CF user, see ["Multiple App Ports" Demo on Cloud Foundry](https://gist.github.com/nota-ja/ef56ea0584ae2b37d6d3a535efe2d4ee).