Skip to main content
Version: 16.x

TLS Routing Migration

In TLS routing mode, all Teleport client connections are wrapped in TLS and multiplexed on one Teleport Proxy Service port.

TLS routing has multiple benefits compared to the deployment where each protocol is served on a separate port:

  • Simpler network policy configurations since all clients connect to Teleport proxy over a single port.
  • Communication between any client and Teleport proxy is authenticated by mutual TLS.
  • Users are able to tunnel protocols that may normally be blocked on the internal network like SSH.

Upgrading Teleport will not enable TLS routing by default and the cluster will keep working in backwards-compatibility mode. Follow this guide to migrate your Teleport installation to TLS routing.

Teleport Enterprise Cloud manages the Proxy Service's networking configuration for you. Get started with a free trial of Teleport Enterprise Cloud.

Prerequisites​

Support for TLS routing behind layer 7 (HTTP/HTTPS) load balancers and reverse proxies is available starting from Teleport 13.0.

If you use Teleport Cloud, see which ports and networking settings the Proxy Service is configured to use in your Teleport Cloud tenant. Run the following command, replacing mytenant.teleport.sh with your tenant address:

$ curl https://mytenant.teleport.sh/webapi/ping | jq '.proxy'

Step 1/7. Upgrade Teleport​

Download Teleport from the downloads page or your enterprise portal and follow the standard upgrade procedure. Make sure to upgrade both root and leaf clusters as well as tsh client.

Step 2/7. Enable proxy multiplexing​

Update your root cluster auth server's configuration to set proxy listener mode to "multiplex":

auth_service:
  proxy_listener_mode: multiplex

This setting will indicate to the clients (such as tsh or reverse tunnel agents) that they should connect to the web proxy port using TLS routing.

Compatibility

Turning multiplexing on will not affect existing connections of trusted clusters, reverse tunnel agents and tsh/ssh clients. As long as the legacy listeners are enabled (see step 7 below), all clients will keep connecting in the backwards compatibility mode until restarted or relogged in/reconfigured in case of tsh/ssh as described below.

Step 3/7. Reconnect trusted clusters​

If you're already multiplexing trusted cluster connections on the web proxy port (i.e. web_listen_addr and tunnel_listen_addr have the same port in your proxy configuration), you can skip this step.

Otherwise, update your trusted clusters to point both web_proxy_addr and tunnel_addr to the root cluster's web proxy address and recreate them:

kind: trusted_cluster
version: v2
metadata:
   name: "root"
spec:
   enabled: true
   web_proxy_addr: root.example.com:443
   tunnel_addr: root.example.com:443
   ...

Step 4/7. Reconnect reverse tunnel agents​

Restart all SSH, Kubernetes, application and database agents that connect to the cluster's proxy over reverse tunnels.

This will make them reconnect to the cluster in TLS routing mode.

Step 5/7. Relogin with tsh​

Do tsh logout and log into the cluster with tsh login again to make sure tsh starts using TLS routing mode.

Step 6/7. Update OpenSSH config​

If you're using OpenSSH client ssh with the config generated by tsh config to connect to nodes within your Teleport cluster, you need to regenerate the config.

Run tsh config command again so it generates SSH config compatible with SSH routing setup. See our OpenSSH guide docs for reference.

Step 7/7. Disable legacy listeners​

At this point, all root cluster's clients connect to its web proxy port in TLS routing mode. The final step is to instruct the Teleport proxy not to create legacy listeners for SSH, reverse tunnels, Kubernetes and database clients by default.

Add version: v2 to your proxy's configuration and remove all listen addresses except for web_listen_addr:

version: v2
proxy_service:
  enabled: "yes"
  web_listen_addr: 0.0.0.0:443
  ...

Config version v2 will prevent other listeners from being created unless they are explicitly set in the proxy service configuration.

Rollback​

To go back to the legacy separate listeners mode, perform the following steps:

  1. Set version: v1 in the proxy configuration and restart the proxy to make it create legacy listeners.
  2. Set proxy_listener_mode: separate in auth service configuration to make clients connect to the legacy listeners.
  3. Reconnect all clients (trusted clusters, reverse tunnel agents, tsh) as described above.
  4. If using OpenSSH client, regenerate SSH config using tsh config command.

Next steps​

  • Learn how TLS routing works.