TLS Routing Migration
TLS routing is available starting from Teleport
Teleport Cloud manages the Proxy Service's networking configuration for you.
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'
TLS routing is not currently supported in Teleport Cloud.
Starting from version
8.0 Teleport supports TLS routing. In this mode, all
client connections are wrapped in TLS and multiplexed on one Teleport proxy
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.
Existing clusters upgraded to
8.0 will not utilize TLS routing by default and
keep working in backwards-compatibility mode. Follow this guide to migrate your
Teleport installation to TLS routing.
For TLS routing to work, Teleport proxy needs to terminate all client connections.
Thus, it will not work with application load balancers (such as AWS ALB) or load balancers that do TLS termination. Use plain TCP passthrough load balancers (such as AWS NLB) to take advantage of TLS routing.
Pre-8.0 cluster configurations are fully backwards compatible with TLS routing. Existing Trusted Cluster and reverse tunnel connections won't be affected.
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.