Skip to main content

Forward a TCP port

Not every service speaks HTTP. A database, a message broker or a device protocol talks over a plain TCP or UDP connection. A stream route forwards such connections: it takes the connections that arrive at one port of the gateway and hands each to a backend node. The bytes go through as they are, and the backend node's answer comes back on the same connection. This guide forwards port 5432 to two read replicas of a PostgreSQL database. At the end, database clients connect to the gateway on 5432, and each connection reaches one of the two replicas behind it.

Before you start​

  • A port the gateway already listens on for streams. The gateway opens no port for a stream route. Its stream proxy listens only on the ports set in the gateway's own configuration, and whoever runs the gateway knows them. This guide uses 5432.
  • The address and port of each backend node, reachable from the gateway nodes. This guide uses 10.0.2.10 and 10.0.2.11, each on 5432.
  • The host name of your gateway. In the console it is the first part of the Address line on an HTTP route's Overview tab; a stream route has no such line. Whoever runs the gateway knows whether anything in front of it forwards this port too.
  • This guide creates a new stream route with no plugin.
  • The Editor or Environment administrator role in this environment.

Steps​

1. Open a new stream route and name it​

In the menu, select Routes, then the Stream routes tab, then New stream route. Under General, set Name to postgres-replicas. The name is for people; the gateway does not match on it.

2. Say which connections the stream route takes​

Under Matching, set Server port to 5432. Leave Server address and Client address empty, and keep Any server name chosen. The stream route then takes every connection that arrives at the port.

3. Send the connections to your two backend nodes​

Under Target, choose Nodes on this stream route. Nodes is already chosen inside. Select Add entry and fill in the first row, then select it again for the second row.

HostPortWeight
10.0.2.1054321
10.0.2.1154321

Keep Type at roundrobin and leave the other settings of the section as they are.

4. Create the stream route​

Select Create stream route. The stream route is saved like this:

The Matching section of the new stream route form, with the listening port and the client address filled in.
stream_route · as the console saves it
{
  "name": "postgres-replicas",
  "server_port": 5432,
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "10.0.2.10:5432": 1,
      "10.0.2.11:5432": 1
    }
  }
}

Check it​

Connect to the gateway's host name on port 5432 with psql, or with any other TCP client, as you would connect to a replica. One of the two replicas answers on the connection, and the gateway passes its answer back as it is.

The next two sections show two other ways to forward port 1883 to MQTT brokers. They are alternatives, not two stream routes to create side by side: pick the one that fits how your brokers run.

Keep each client on the same backend node​

Pick this when a client must reach the same broker each time it connects. Some protocols expect a client to reach the same backend node each time it connects, an MQTT broker that keeps the client's session for example. Choose chash as the Type. Two more fields appear. Set Hash on to vars, which says that Key names a variable. Set Key to remote_addr, the variable that holds the client's address. The example below forwards port 1883 to two brokers this way:

stream_route · as the console saves it
{
  "name": "mqtt-sticky",
  "server_port": 1883,
  "upstream": {
    "type": "chash",
    "hash_on": "vars",
    "key": "remote_addr",
    "nodes": {
      "10.0.2.30:1883": 1,
      "10.0.2.31:1883": 1
    }
  }
}

The gateway groups the connections by the key, so a client that keeps its address keeps its backend node. This example is shown for its shape only.

Find the backend nodes through DNS​

Pick this when the brokers are found by a name in DNS rather than listed by address. When the backend nodes change and a DNS name lists them, the gateway can read them from DNS instead of a fixed list. Under the stream route's target, choose Service discovery in place of Nodes. Set Discovery type to dns and Service name to the name with its port, brokers.internal.example.com:1883 here.

stream_route · as the console saves it
{
  "name": "mqtt-brokers",
  "server_port": 1883,
  "upstream": {
    "type": "roundrobin",
    "discovery_type": "dns",
    "service_name": "brokers.internal.example.com:1883"
  }
}

DNS discovery has to be turned on in the gateway's own configuration first, by whoever runs the gateway.

What to know​

  • A stream route carries stream plugins only. On its Plugins tab, the picker lists them, and an HTTP plugin like key-auth is refused when you save. The stream plugins are ip-restriction, limit-conn, mqtt-proxy, syslog and traffic-split.
  • No global rule runs on a stream route. From a service, only its stream plugins run, and the stream route's own copy of a plugin wins over the service's.
  • Client address limits the stream route to clients of one address or network, 10.0.0.0/8 for example.
  • Keep Any server name for plain TCP. Where you choose One server name or Several server names, the form shows this caution. Read only by a TLS stream listener: a plain TCP connection never matches a stream route that names an SNI.
  • The port is a number up to 65535. 65536 is refused when you save.
  • Deleting a stream route makes the connections it matched fail at once.
G8 dev