TLS Routing Migration
Support for TLS routing behind layer 7 (HTTP/HTTPS) load balancers and
reverse proxies is available in Preview starting from Teleport
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 Cloud manages the Proxy Service's networking configuration for you. Get started with a free trial of Teleport Cloud.
To 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
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.
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
tunnel_listen_addr have the same port in your
proxy configuration), you can skip this step.
Otherwise, update your trusted clusters to point both
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
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
to connect to nodes within your Teleport cluster, you need to regenerate the
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.
version: v2 to your proxy's configuration and remove all listen addresses
version: v2 proxy_service: enabled: "yes" web_listen_addr: 0.0.0.0:443 ...
v2 will prevent other listeners from being created unless
they are explicitly set in the proxy service configuration.
To go back to the legacy separate listeners mode, perform the following steps:
version: v1in the proxy configuration and restart the proxy to make it create legacy listeners.
proxy_listener_mode: separatein auth service configuration to make clients connect to the legacy listeners.
- Reconnect all clients (trusted clusters, reverse tunnel agents,
tsh) as described above.
- If using OpenSSH client, regenerate SSH config using
- Learn how TLS routing works.