Fork me on GitHub
Teleport

TLS Routing Migration

Improve

TLS routing is available starting from Teleport 8.0.

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 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.

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.

Requirements

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.

Step 1/7. Upgrade to Teleport 8.0

Download Teleport 8.0 or later 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.

Pre-8.0 cluster configurations are fully backwards compatible with TLS routing. Existing trusted cluster and reverse tunnel agent connections won't be affected.

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 OpenSSH client 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.
Have a suggestion or can’t find something?
IMPROVE THE DOCS