Update docs for TLS routing (#9097)

docs/config.json

@@ -53,7 +53,8 @@
             { "title": "Scaling", "slug": "/setup/operations/scaling/" },
             { "title": "Upgrading", "slug": "/setup/operations/upgrading/" },
             { "title": "Backup and Restore", "slug": "/setup/operations/backup-restore/" },
-            { "title": "Cert Authority Rotation", "slug": "/setup/operations/ca-rotation/" }
+            { "title": "Cert Authority Rotation", "slug": "/setup/operations/ca-rotation/" },
+            { "title": "TLS Routing Migration", "slug": "/setup/operations/tls-routing/" }
           ]
         },
         {
@@ -314,7 +315,8 @@
         { "title": "Teleport Nodes", "slug": "/architecture/nodes/" },
         { "title": "Teleport Auth", "slug": "/architecture/authentication/" },
         { "title": "Teleport Proxy", "slug": "/architecture/proxy/" },
-        { "title": "Trusted Clusters", "slug": "/trustedclusters/" }
+        { "title": "Trusted Clusters", "slug": "/trustedclusters/" },
+        { "title": "TLS Routing", "slug": "/architecture/tls-routing/" }
       ]
     }
   ],

docs/pages/architecture/tls-routing.mdx

@@ -0,0 +1,153 @@
+---
+title: TLS Routing
+description: How Teleport implements a single-port setup with TLS routing
+---
+
+<Details
+  title="Version warning"
+  opened={true}
+  scope={["oss", "enterprise"]}
+  scopeOnly={true}
+  min="8.0"
+>
+  TLS routing is available starting from Teleport `8.0`.
+</Details>
+
+In TLS routing mode [Teleport proxy](./proxy.mdx) multiplexes all client
+connections on a single TLS port.
+
+With TLS routing, cluster administrators can simplify network configurations
+since proxy only listens on one port. All connections are authenticated with
+mutual TLS and users are able to tunnel protocols that may be blocked on the
+network such as SSH.
+
+To implement TLS routing, Teleport uses SNI ([Server Name Indication](https://en.wikipedia.org/wiki/Server_Name_Indication))
+and ALPN ([Application-Level Protocol Negotiation](https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation))
+TLS extensions.
+
+## How it works
+
+Starting from version `8.0` Teleport proxy listens for all client connections
+on its `web_listen_addr` by default:
+
+```yaml
+proxy_service:
+  web_listen_addr: "0.0.0.0:443"
+```
+
+All Teleport clients including SSH, web browser, kubectl, database and reverse
+tunnel clients establish a TLS tunnel to the proxy's web port and indicate the
+protocol they're requesting using SNI and ALPN TLS extensions.
+
+Upon accepting a new connection, the proxy inspects the SNI/ALPN value in the
+TLS handshake and forwards the connection to appropriate backend service.
+
+### Local proxy
+
+Clients like `psql` or `mysql` implement TLS handshake as a part of their
+protocol-specific connection negotiation phase (aka [STARTTLS](https://en.wikipedia.org/wiki/Opportunistic_TLS)).
+
+To support these clients, as well as clients that do support TLS but don't allow
+setting custom ALPN values, Teleport's `tsh` client includes ability to start
+a local TLS routing aware proxy.
+
+Such clients connect to the local proxy instead of Teleport proxy directly. The
+local proxy establishes a TLS connection to the Teleport proxy with the proper
+SNI/ALPN values set and tunnels the client's connection over it.
+
+In most cases, clients handle TLS routing transparently when establishing
+connection. For example, `tsh` client starts local proxy and sets appropriate
+SNI/ALPN values automatically. For some clients, like native/GUI database
+clients instead of `tsh db connect`, the user needs to start the local proxy so
+these clients can connect to it.
+
+### Diagram
+
+<Figure align="left" bordered caption="TLS routing">
+  ![TLS routing](../../img/architecture/tls-routing.png)
+</Figure>
+
+Let's take a look at how each protocol Teleport supports implements TLS routing.
+
+## SSH
+
+Teleport client `tsh`, when connecting to an SSH node, first dials Teleport
+proxy over TLS and requests `teleport-ssh-proxy` ALPN protocol.
+
+No local proxy is started in this case as `tsh` uses this TLS connection as a
+transport to establish the SSH connection.
+
+### OpenSSH
+
+To support standard OpenSSH client, Teleport provides a `tsh proxy ssh` command
+which can be used as a `ProxyCommand`.
+
+Similarly to `tsh ssh`, `tsh proxy ssh` establishes a TLS tunnel to Teleport
+proxy with `teleport-ssh-proxy` ALPN protocol, which `ssh` then connects over.
+
+See [OpenSSH client](../server-access/guides/openssh.mdx#use-openssh-client)
+guide for details on how it's configured.
+
+## Reverse tunnels
+
+Reverse tunnel agents for Teleport node, application and database services, as
+well as for trusted clusters, open a TLS tunnel to the cluster's proxy with
+`teleport-reversetunnel` ALPN protocol and then dials SSH over it establishing
+the reverse tunnel connection.
+
+## Kubernetes
+
+Kubernetes client `kubectl` uses HTTPS API and TLS handshake to talk to the API
+server.
+
+As such, it is not possible to request a custom ALPN protocol using `kubectl`.
+Instead, Teleport leverages SNI and sets a `ServerName` prefixed with `kube.`
+when generating a kubeconfig file during `tsh kube login`:
+
+```yaml
+apiVersion: v1
+kind: Config
+clusters:
+- cluster:
+    certificate-authority-data: ...
+    server: https://proxy.example.com:443
+    tls-server-name: kube.proxy.example.com
+  name: example
+```
+
+## Databases
+
+The `tsh db connect` command executes an appropriate database client for the
+database you're connecting to.
+
+In TLS routing mode, `tsh` starts a local proxy which database client connection
+is tunneled through. The local proxy uses one of `teleport-postgres`,
+`teleport-mysql` or `teleport-mongodb` ALPN values depending on the database.
+The proxy is shut down when the database session ends.
+
+### Native and GUI clients
+
+For the native or graphical database clients to work with TLS routing, they
+must be connecting to the local proxy instead of Teleport proxy directly.
+
+Teleport provides a `tsh proxy db` command to launch a local database proxy:
+
+```code
+$ tsh proxy db example-db
+```
+
+See [GUI clients](../database-access/guides/gui-clients.mdx) guide for a usage
+example.
+
+## Web UI, apps and desktops
+
+Application access, desktop access and Teleport web UI are served by the
+Teleport proxy's web listener and don't require a local proxy or any special
+ALPN/SNI negotiation. These web connections use standard `http1.1` and `h2`
+protocols for ALPN.
+
+## Next steps
+
+- See [migration guide](../setup/operations/tls-routing.mdx) to learn how to
+  upgrade an existing cluster to use TLS routing.
+- Read through TLS routing design document [RFD](https://github.com/gravitational/teleport/blob/master/rfd/0039-sni-alpn-teleport-proxy-routing.md).

docs/pages/database-access/guides/cockroachdb-self-hosted.mdx

@@ -164,12 +164,6 @@ $ tsh db connect roach
   in order to be able to connect.
 </Admonition>
 
-To see the native `cockroach` shell connect command, run:
-
-```code
-$ tsh db config --format=cmd roach
-```
-
 To log out of the database and remove credentials:
 
 ```code

docs/pages/database-access/guides/gui-clients.mdx

@@ -8,25 +8,48 @@ description: How to configure graphical database clients for Teleport Database A
 This article describes how to configure popular graphical database clients to
 work with Teleport Database Access.
 
-## Obtain local certificate/key-pair
+## Get connection information
 
-Issue the following command after you login with `tsh`:
+<Tabs>
+<TabItem label="TLS routing">
+If you're using Teleport in [TLS routing](../../setup/operations/tls-routing.mdx)
+mode where each database protocol is multiplexed on the same web proxy port, use
+the following command to start a local TLS proxy your GUI database client will
+be connecting to:
+
+```code
+$ tsh proxy db <database-name>
+Started DB proxy on 127.0.0.1:61740
+
+Use following credentials to connect to the <database-name> proxy:
+  ca_file=/Users/r0mant/.tsh/keys/root.gravitational.io/certs.pem
+  cert_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice-db/root/<database-name>-x509.pem
+  key_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice
+```
+
+Use the displayed local proxy host/port and credentials paths when configuring
+your GUI client below. When entering the hostname, use `localhost` rather than
+`127.0.0.1`.
+</TabItem>
+<TabItem label="Separate ports">
+If you're not using TLS routing, run the following command to see the database
+connection information:
 
 ```code
 # View configuration for the database you're logged in to.
-tsh db config
+$ tsh db config
 # View configuration for the specific database when you're logged into multiple.
-tsh db config example
+$ tsh db config example
 ```
 
-It will display the path to your locally cached PEM files:
+It will display the path to your locally cached certificate and key files:
 
 ```
 Name:      example
 Host:      teleport.example.com
-Port:      3036
-User:      alice
-Database:
+Port:      3080
+User:      postgres
+Database:  postgres
 CA:        /Users/alice/.tsh/keys/teleport.example.com/certs.pem
 Cert:      /Users/alice/.tsh/keys/teleport.example.com/alice-db/root/example-x509.pem
 Key:       /Users/alice/.tsh/keys/teleport.example.com/alice
@@ -35,6 +58,8 @@ Key:       /Users/alice/.tsh/keys/teleport.example.com/alice
 The displayed `CA`, `Cert`, and `Key` files are used to connect through pgAdmin
 4, MySQL Workbench, and other graphical database clients that support mutual
 TLS authentication.
+</TabItem>
+</Tabs>
 
 ## PostgreSQL pgAdmin 4
 
@@ -50,25 +75,18 @@ In the "General" tab of the new server dialog, enter the server connection name:
 
 ![pgAdmin General](../../../img/database-access/[email protected])
 
-In the "Connection" tab, enter the default database name (the *maintenance
-database*) and the connection service name (the same one that you specify when
-connecting through `psql`). Leave all the other fields blank:
+In the "Connection" tab, fill in the hostname, port, user and database name from
+the configuration above:
 
 ![pgAdmin Connection](../../../img/database-access/[email protected])
 
-In the "SSL" tab, set "SSL Mode" to `Verify-Full`:
+In the "SSL" tab, set "SSL Mode" to `Verify-Full` and fill in paths for client
+certificate, key and root certificate from the configuration above:
 
 ![pgAdmin SSL](../../../img/database-access/[email protected])
 
-Click "Save", and pgAdmin should immediately connect.
-
-<Admonition type="note">
-  On a Windows client, use terminal to export a PG Service File env variable:
-
- `$ setx PGSERVICEFILE <path_to_.pg_service.conf_file>`
-
-  Restart the pgAdmin client.
-</Admonition>
+Click "Save", and pgAdmin should immediately connect. If pgAdmin prompts you
+for password, leave the password field empty and click OK.
 
 ## MySQL Workbench
 

docs/pages/database-access/guides/mongodb-atlas.mdx

@@ -189,12 +189,6 @@ $ tsh db connect mongodb-atlas
   able to connect.
 </Admonition>
 
-If you would like to see the native `mongo` shell connect command, run:
-
-```code
-$ tsh db config --format=cmd mongodb-atlas
-```
-
 To log out of the database and remove credentials:
 
 ```code

docs/pages/database-access/guides/mongodb-self-hosted.mdx

@@ -229,12 +229,6 @@ $ tsh db connect example-mongo
   able to connect.
 </Admonition>
 
-If you would like to see the native `mongo` shell connect command, run:
-
-```code
-$ tsh db config --format=cmd example-mongo
-```
-
 To log out of the database and remove credentials:
 
 ```code

docs/pages/database-access/guides/mysql-cloudsql.mdx

@@ -240,12 +240,6 @@ $ tsh db connect cloudsql
   able to connect.
 </Admonition>
 
-If you would like to see the native `mysql` shell connect command, run:
-
-```code
-$ tsh db config --format=cmd cloudsql
-```
-
 To log out of the database and remove credentials:
 
 ```code

docs/pages/database-access/guides/mysql-self-hosted.mdx

@@ -217,12 +217,6 @@ $ tsh db connect example
   able to connect.
 </Admonition>
 
-If you would like to see the native `mysql` shell connect command, run:
-
-```code
-$ tsh db config --format=cmd example
-```
-
 To log out of the database and remove credentials:
 
 ```code

docs/pages/database-access/guides/postgres-cloudsql.mdx

@@ -316,12 +316,6 @@ $ tsh db connect aurora
   able to connect.
 </Admonition>
 
-If you would like to see the native `psql` shell connect command, run:
-
-```code
-$ tsh db config --format=cmd aurora
-```
-
 To log out of the database and remove credentials:
 
 ```code

docs/pages/database-access/guides/postgres-redshift.mdx

@@ -262,12 +262,6 @@ $ tsh db connect aurora
   able to connect.
 </Admonition>
 
-If you would like to see the native `psql` shell connect command, run:
-
-```code
-$ tsh db config --format=cmd aurora
-```
-
 To log out of the database and remove credentials:
 
 ```code

docs/pages/database-access/guides/postgres-self-hosted.mdx

@@ -213,12 +213,6 @@ $ tsh db connect aurora
   able to connect.
 </Admonition>
 
-If you would like to see the native `psql` shell connect command, run:
-
-```code
-$ tsh db config --format=cmd aurora
-```
-
 To log out of the database and remove credentials:
 
 ```code

docs/pages/database-access/guides/rds.mdx

@@ -378,12 +378,6 @@ $ tsh db connect postgres-rds
   available in PATH in order to be able to connect.
 </Admonition>
 
-To see the native database CLI client connect command, run:
-
-```code
-$ tsh db config --format=cmd postgres-rds
-```
-
 To log out of the database and remove credentials:
 
 ```code