From f979986dbe197926911255daca716e96565728a6 Mon Sep 17 00:00:00 2001 From: Gus Luxton Date: Tue, 16 Apr 2024 10:20:56 -0300 Subject: [PATCH 1/7] docs: Add clarity on reverse proxies and supported versions to troubleshooting section --- .../includes/tls-multiplexing-warnings.mdx | 32 +++++++++++++++---- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/pages/includes/tls-multiplexing-warnings.mdx b/docs/pages/includes/tls-multiplexing-warnings.mdx index b30c68b55fe94..aaf0a39caa2f6 100644 --- a/docs/pages/includes/tls-multiplexing-warnings.mdx +++ b/docs/pages/includes/tls-multiplexing-warnings.mdx @@ -1,6 +1,4 @@ -Prior to Teleport `13.0`, using Teleport's TLS routing mode behind a layer 7 (HTTP/HTTPS) proxy is generally not supported, due to -these proxies terminating TLS themselves and then rewriting their requests to the upstream service, stripping -the additional SNI/ALPN parts of the request in the process. +#### Teleport version 13.0+ Support for TLS routing behind layer 7 (HTTP/HTTPS) load balancers and reverse proxies is available starting from Teleport `13.0`. Please ensure your Teleport @@ -8,10 +6,30 @@ cluster and Teleport clients are up to date. If the problem persists, please submit a [GitHub issue](https://github.com/gravitational/teleport/issues/new/choose). +You must ensure that your reverse proxy is communicating with Teleport using HTTPS. +When running Teleport in Kubernetes and using nginx as an ingress, this requires adding +an annotation to the chart values: + +```yaml +annotations: + ingress: + nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" +``` + +Deploying Teleport behind Cloudflare, whether using its proxy ("orange-clouding") or tunnels +(`cloudflared`) should work with Teleport version 15.1 or higher. See the [TLS Routing FAQ] +(../../architecture/tls-routing/#will-tls-routing-work-behind-my-reverse-proxy) for more details. + +#### Prior to Teleport version 13.0 + +Prior to Teleport version `13.0`, using Teleport's TLS routing mode behind a layer 7 (HTTP/HTTPS) proxy is not supported, +due to these proxies terminating TLS themselves and then rewriting their requests to the upstream service, stripping +the additional SNI/ALPN parts of the request in the process. + For older versions, in order for ALPN to work correctly, the Teleport Proxy Service must terminate TLS itself. -Broadly, this means that Teleport's TLS routing functionality is incompatible with: +Broadly, this means that prior to Teleport version `13.0`, Teleport's TLS routing functionality is incompatible with: - AWS ALBs (Application Load Balancers) - AWS NLBs (Network Load Balancers), when using a TLS listener and a public ACM (Amazon Certificate Manager) certificate - Commonly used HTTP reverse proxies including nginx, Apache, Caddy, Traefik, HAProxy and many others @@ -25,10 +43,10 @@ of a correctly configured Teleport cluster. If in doubt, remove all load balancers/proxies from the equation and connect Teleport clients or agent processes directly to Teleport's web port to isolate the issue. -To use Teleport behind a reverse proxy, you should either: +To use Teleport behind a reverse proxy prior to Teleport version `13.0`, you should either: - use a layer 4 (TCP) proxy which forwards TCP streams directly to Teleport (which will in turn handle TLS termination itself) - disable Teleport's TLS routing mode by adding `version: v1` to your config file and removing `proxy_listener_mode: multiplex` - + You can get an example `v1` config file using `teleport configure --version=v1 --public-addr=teleport.example.com:443` (change the public address to your own domain) -If disabling TLS routing, you can find the list of default ports to use for connecting different Teleport services at [ports without TLS routing](../reference/networking.mdx#ports-without-tls-routing) +If disabling TLS routing, you can find the list of default ports to use for connecting different Teleport services at [ports without TLS routing](../reference/networking.mdx#ports-without-tls-routing) \ No newline at end of file From f97108875628454a00de1fab1f44a567b3510fc2 Mon Sep 17 00:00:00 2001 From: Gus Luxton Date: Tue, 16 Apr 2024 12:21:26 -0300 Subject: [PATCH 2/7] Fix version numbers Co-authored-by: Zac Bergquist --- docs/pages/includes/tls-multiplexing-warnings.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/pages/includes/tls-multiplexing-warnings.mdx b/docs/pages/includes/tls-multiplexing-warnings.mdx index aaf0a39caa2f6..312dfde8b263f 100644 --- a/docs/pages/includes/tls-multiplexing-warnings.mdx +++ b/docs/pages/includes/tls-multiplexing-warnings.mdx @@ -1,7 +1,7 @@ #### Teleport version 13.0+ Support for TLS routing behind layer 7 (HTTP/HTTPS) load balancers and reverse -proxies is available starting from Teleport `13.0`. Please ensure your Teleport +proxies is available starting from Teleport 13.0. Please ensure your Teleport cluster and Teleport clients are up to date. If the problem persists, please submit a [GitHub issue](https://github.com/gravitational/teleport/issues/new/choose). @@ -22,14 +22,14 @@ Deploying Teleport behind Cloudflare, whether using its proxy ("orange-clouding" #### Prior to Teleport version 13.0 -Prior to Teleport version `13.0`, using Teleport's TLS routing mode behind a layer 7 (HTTP/HTTPS) proxy is not supported, +Prior to Teleport version 13.0, using Teleport's TLS routing mode behind a layer 7 (HTTP/HTTPS) proxy is not supported, due to these proxies terminating TLS themselves and then rewriting their requests to the upstream service, stripping the additional SNI/ALPN parts of the request in the process. For older versions, in order for ALPN to work correctly, the Teleport Proxy Service must terminate TLS itself. -Broadly, this means that prior to Teleport version `13.0`, Teleport's TLS routing functionality is incompatible with: +Broadly, this means that prior to Teleport version 13.0, Teleport's TLS routing functionality is incompatible with: - AWS ALBs (Application Load Balancers) - AWS NLBs (Network Load Balancers), when using a TLS listener and a public ACM (Amazon Certificate Manager) certificate - Commonly used HTTP reverse proxies including nginx, Apache, Caddy, Traefik, HAProxy and many others @@ -43,7 +43,7 @@ of a correctly configured Teleport cluster. If in doubt, remove all load balancers/proxies from the equation and connect Teleport clients or agent processes directly to Teleport's web port to isolate the issue. -To use Teleport behind a reverse proxy prior to Teleport version `13.0`, you should either: +To use Teleport behind a reverse proxy prior to Teleport version 13.0, you should either: - use a layer 4 (TCP) proxy which forwards TCP streams directly to Teleport (which will in turn handle TLS termination itself) - disable Teleport's TLS routing mode by adding `version: v1` to your config file and removing `proxy_listener_mode: multiplex` From e38b18ca5047d65f914b1cf99165a3ab3d04593c Mon Sep 17 00:00:00 2001 From: Gus Luxton Date: Tue, 16 Apr 2024 12:21:46 -0300 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Paul Gottschling --- docs/pages/includes/tls-multiplexing-warnings.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/includes/tls-multiplexing-warnings.mdx b/docs/pages/includes/tls-multiplexing-warnings.mdx index 312dfde8b263f..3ea9f5b9ccc5e 100644 --- a/docs/pages/includes/tls-multiplexing-warnings.mdx +++ b/docs/pages/includes/tls-multiplexing-warnings.mdx @@ -49,4 +49,4 @@ To use Teleport behind a reverse proxy prior to Teleport version 13.0, you shoul You can get an example `v1` config file using `teleport configure --version=v1 --public-addr=teleport.example.com:443` (change the public address to your own domain) -If disabling TLS routing, you can find the list of default ports to use for connecting different Teleport services at [ports without TLS routing](../reference/networking.mdx#ports-without-tls-routing) \ No newline at end of file +If disabling TLS routing, consult the [list of default ports](../reference/networking.mdx#ports-without-tls-routing) to use for connecting different Teleport services. \ No newline at end of file From 11c2ce8f48c95fb2ff46e7dc9cfef49e1fe83add Mon Sep 17 00:00:00 2001 From: Gus Luxton Date: Tue, 16 Apr 2024 12:23:35 -0300 Subject: [PATCH 4/7] Fix markdown --- docs/pages/includes/tls-multiplexing-warnings.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/includes/tls-multiplexing-warnings.mdx b/docs/pages/includes/tls-multiplexing-warnings.mdx index 3ea9f5b9ccc5e..b6138091a24a4 100644 --- a/docs/pages/includes/tls-multiplexing-warnings.mdx +++ b/docs/pages/includes/tls-multiplexing-warnings.mdx @@ -17,8 +17,8 @@ annotations: ``` Deploying Teleport behind Cloudflare, whether using its proxy ("orange-clouding") or tunnels -(`cloudflared`) should work with Teleport version 15.1 or higher. See the [TLS Routing FAQ] -(../../architecture/tls-routing/#will-tls-routing-work-behind-my-reverse-proxy) for more details. +(`cloudflared`) should work with Teleport version 15.1 or higher. See the +[TLS Routing FAQ](../../architecture/tls-routing/#will-tls-routing-work-behind-my-reverse-proxy) for more details. #### Prior to Teleport version 13.0 From fb9086c3310e6eb6355a012b6fb6fb1be69cf046 Mon Sep 17 00:00:00 2001 From: Gus Luxton Date: Tue, 16 Apr 2024 15:56:32 -0300 Subject: [PATCH 5/7] Add cloudflared to cspell.json --- docs/cspell.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cspell.json b/docs/cspell.json index 5136f2ff7eea8..7f83ef94b330f 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -337,6 +337,7 @@ "clientid", "clis", "cloudbuild", + "cloudflared", "cloudhsmv2", "cloudkms", "cloudsql", From a324d7eda496b7b32fb28f7751608d1543e43dcb Mon Sep 17 00:00:00 2001 From: Gus Luxton Date: Wed, 17 Apr 2024 09:34:52 -0300 Subject: [PATCH 6/7] Update docs/pages/includes/tls-multiplexing-warnings.mdx --- docs/pages/includes/tls-multiplexing-warnings.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/includes/tls-multiplexing-warnings.mdx b/docs/pages/includes/tls-multiplexing-warnings.mdx index b6138091a24a4..9a91aa04c0172 100644 --- a/docs/pages/includes/tls-multiplexing-warnings.mdx +++ b/docs/pages/includes/tls-multiplexing-warnings.mdx @@ -18,7 +18,7 @@ annotations: Deploying Teleport behind Cloudflare, whether using its proxy ("orange-clouding") or tunnels (`cloudflared`) should work with Teleport version 15.1 or higher. See the -[TLS Routing FAQ](../../architecture/tls-routing/#will-tls-routing-work-behind-my-reverse-proxy) for more details. +[TLS Routing FAQ](../../architecture/tls-routing.mdx#will-tls-routing-work-behind-my-reverse-proxy) for more details. #### Prior to Teleport version 13.0 From 48cbf7dccd88c5dce41cd4bd1ae69a3a75c2d418 Mon Sep 17 00:00:00 2001 From: Gus Luxton Date: Wed, 17 Apr 2024 09:58:25 -0300 Subject: [PATCH 7/7] Update docs/pages/includes/tls-multiplexing-warnings.mdx --- docs/pages/includes/tls-multiplexing-warnings.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/includes/tls-multiplexing-warnings.mdx b/docs/pages/includes/tls-multiplexing-warnings.mdx index 9a91aa04c0172..507dc09bb9b2c 100644 --- a/docs/pages/includes/tls-multiplexing-warnings.mdx +++ b/docs/pages/includes/tls-multiplexing-warnings.mdx @@ -18,7 +18,7 @@ annotations: Deploying Teleport behind Cloudflare, whether using its proxy ("orange-clouding") or tunnels (`cloudflared`) should work with Teleport version 15.1 or higher. See the -[TLS Routing FAQ](../../architecture/tls-routing.mdx#will-tls-routing-work-behind-my-reverse-proxy) for more details. +[TLS Routing FAQ](../architecture/tls-routing.mdx#will-tls-routing-work-behind-my-reverse-proxy) for more details. #### Prior to Teleport version 13.0