TLS Routing Migration
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
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 Team manages the Proxy Service's networking configuration for you. Get started with a free trial of Teleport Team.
Support for TLS routing behind layer 7 (HTTP/HTTPS) load balancers and reverse
proxies is available starting from Teleport
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
mytenant.teleport.sh with your tenant address:
curl https://mytenant.teleport.sh/webapi/ping | jq '.proxy'
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.
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 ...
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.
tsh logout and log into the cluster with
tsh login again to make sure
tsh starts using TLS routing mode.
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.
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.