From 9c620fcae26114e3569ed9129e591ec75a7039b4 Mon Sep 17 00:00:00 2001 From: Ricardo Pchevuzinske Katz Date: Wed, 1 Oct 2025 18:06:10 -0300 Subject: [PATCH 1/7] Fix inconsistencies on TLSRoute documentation --- site-src/concepts/api-overview.md | 8 +++++--- site-src/guides/tls.md | 12 +++++++++--- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/site-src/concepts/api-overview.md b/site-src/concepts/api-overview.md index 20db51b0ab..2551c5909c 100644 --- a/site-src/concepts/api-overview.md +++ b/site-src/concepts/api-overview.md @@ -117,8 +117,10 @@ modifying them in-flight. TLSRoute is for multiplexing TLS connections, discriminated via SNI. It's intended for where you want to use the SNI as the main routing method, and are not interested -in properties of the higher-level protocols like HTTP. The byte stream of the -connection is proxied without any inspection to the backend. +in properties of the higher-level protocols like HTTP. The byte stream of the +connection is proxied without any inspection to the backend when using a `Passthrough` +TLS listener, or proxied unencrypted to the backend when using a `Terminate` TLS +listener. #### TCPRoute and UDPRoute @@ -157,7 +159,7 @@ to allow multiple Routes to share ports on the Listener. |------|---------|---------------------|-----------|-------| |HTTPRoute| Layer 7 | Anything in the HTTP Protocol | Terminated only | HTTP and HTTPS Routing| |TLSRoute| Somewhere between layer 4 and 7| SNI or other TLS properties| Passthrough or Terminated | Routing of TLS protocols including HTTPS where inspection of the HTTP stream is not required.| -|TCPRoute| Layer 4| destination port | Passthrough or Terminated | Allows for forwarding of a TCP stream from the Listener to the Backends | +|TCPRoute| Layer 4| destination port | Terminated | Allows for forwarding of a TCP stream from the Listener to the Backends | |UDPRoute| Layer 4| destination port | None | Allows for forwarding of a UDP stream from the Listener to the Backends. | |GRPCRoute| Layer 7 | Anything in the gRPC Protocol | Terminated only | gRPC Routing over HTTP/2 and HTTP/2 cleartext| diff --git a/site-src/guides/tls.md b/site-src/guides/tls.md index 4d703dce9d..29b505cfd0 100644 --- a/site-src/guides/tls.md +++ b/site-src/guides/tls.md @@ -12,7 +12,7 @@ implementation(s) you're using with Gateway API. !!! info "Experimental Channel" - The `TLSRoute` and `BackendTLSPolicy` resources described below are currently only included in the + The `TLSRoute` resources described below is currently only included in the "Experimental" channel of Gateway API. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md). @@ -26,14 +26,15 @@ For Gateways, there are two connections involved: - **upstream**: This is the connection between the Gateway and backend resources specified by routes. These backend resources will usually be Services. -With Gateway API, TLS configuration of downstream and -upstream connections is managed independently. +With Gateway API, TLS configuration of downstream and upstream connections is +managed independently. For downstream connections, depending on the Listener Protocol, different TLS modes and Route types are supported. | Listener Protocol | TLS Mode | Route Type Supported | |-------------------|-------------|---------------------| | TLS | Passthrough | TLSRoute | +| TLS | Terminate | TLSRoute | | TLS | Terminate | TCPRoute | | HTTPS | Terminate | HTTPRoute | | GRPC | Terminate | GRPCRoute | @@ -47,6 +48,11 @@ upstream TLS configuration. For `HTTPRoute`, the use of both `Terminate` TLS mod Using these together provides what is commonly known as a connection that is terminated and then re-encrypted at the Gateway. +For `TLSRoute`, the use of `Terminate` means that the TLS termination happens on +the `Gateway` and the connection to the backend may happen as a unencrypted TCP connection. +`BackendTLSPolicy` can be used in this case to re-encrypt the connection using different +set of certificate authorities, SNI and other configurations. + ## Downstream TLS Downstream TLS settings are configured using listeners at the Gateway level. From 63f461ffd39f43eb95f65f0f6a7cab0296e367f9 Mon Sep 17 00:00:00 2001 From: Ricardo Pchevuzinske Katz Date: Wed, 1 Oct 2025 18:14:49 -0300 Subject: [PATCH 2/7] Apply suggestions Co-authored-by: Blake Covarrubias --- site-src/guides/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site-src/guides/tls.md b/site-src/guides/tls.md index 29b505cfd0..41233815da 100644 --- a/site-src/guides/tls.md +++ b/site-src/guides/tls.md @@ -12,7 +12,7 @@ implementation(s) you're using with Gateway API. !!! info "Experimental Channel" - The `TLSRoute` resources described below is currently only included in the + The `TLSRoute` resource described below is currently only included in the "Experimental" channel of Gateway API. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md). From 35584cf82b0133b185926ace505a9b24692f269d Mon Sep 17 00:00:00 2001 From: Ricardo Pchevuzinske Katz Date: Thu, 2 Oct 2025 14:11:47 -0300 Subject: [PATCH 3/7] Clarify on TLSRoute termination --- site-src/concepts/api-overview.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/site-src/concepts/api-overview.md b/site-src/concepts/api-overview.md index 2551c5909c..a8e6ec1712 100644 --- a/site-src/concepts/api-overview.md +++ b/site-src/concepts/api-overview.md @@ -119,8 +119,9 @@ TLSRoute is for multiplexing TLS connections, discriminated via SNI. It's intend for where you want to use the SNI as the main routing method, and are not interested in properties of the higher-level protocols like HTTP. The byte stream of the connection is proxied without any inspection to the backend when using a `Passthrough` -TLS listener, or proxied unencrypted to the backend when using a `Terminate` TLS -listener. +TLS listener, or being __TLS Terminated__ by the proxy when using a `Terminate` +TLS listener. In the later case, the proxy may re-encrypt the traffic to the backend +in cases like a `BackendTLSPolicy` is applied. #### TCPRoute and UDPRoute From 58c1951b22620963f17278d86b965bc7e48f1858 Mon Sep 17 00:00:00 2001 From: Ricardo Pchevuzinske Katz Date: Thu, 2 Oct 2025 15:51:08 -0300 Subject: [PATCH 4/7] Reword on TLSRoute termination Co-authored-by: Mike Morris --- site-src/concepts/api-overview.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/site-src/concepts/api-overview.md b/site-src/concepts/api-overview.md index a8e6ec1712..1cf143560f 100644 --- a/site-src/concepts/api-overview.md +++ b/site-src/concepts/api-overview.md @@ -117,11 +117,15 @@ modifying them in-flight. TLSRoute is for multiplexing TLS connections, discriminated via SNI. It's intended for where you want to use the SNI as the main routing method, and are not interested -in properties of the higher-level protocols like HTTP. The byte stream of the -connection is proxied without any inspection to the backend when using a `Passthrough` -TLS listener, or being __TLS Terminated__ by the proxy when using a `Terminate` -TLS listener. In the later case, the proxy may re-encrypt the traffic to the backend -in cases like a `BackendTLSPolicy` is applied. +in properties of the higher-level protocols like HTTP. When using a `Passthrough` +TLS listener, the encrypted byte stream of the connection is proxied directly to +the backend destination (which is then responsible for decrypting the stream) +without any introspection beyond the TLS metadata. When using a `Terminate` +TLS listener, encryption is removed at the gateway to "unwrap" the connection, +allowing traffic inspection and routing based on attributes of the inner request +payload. In this latter case, the gateway may be configured to re-encrypt +the traffic before sending it on to the backend, such as when a +`BackendTLSPolicy` has been applied to the destination. #### TCPRoute and UDPRoute From 278e488002ea9c717487cae0d041aee284bca5f6 Mon Sep 17 00:00:00 2001 From: Ricardo Pchevuzinske Katz Date: Tue, 7 Oct 2025 17:15:21 -0300 Subject: [PATCH 5/7] Remove mention to BTLSPolicy on TLSroute --- site-src/concepts/api-overview.md | 4 +--- site-src/guides/tls.md | 2 -- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/site-src/concepts/api-overview.md b/site-src/concepts/api-overview.md index 1cf143560f..ef683161fb 100644 --- a/site-src/concepts/api-overview.md +++ b/site-src/concepts/api-overview.md @@ -123,9 +123,7 @@ the backend destination (which is then responsible for decrypting the stream) without any introspection beyond the TLS metadata. When using a `Terminate` TLS listener, encryption is removed at the gateway to "unwrap" the connection, allowing traffic inspection and routing based on attributes of the inner request -payload. In this latter case, the gateway may be configured to re-encrypt -the traffic before sending it on to the backend, such as when a -`BackendTLSPolicy` has been applied to the destination. +payload. #### TCPRoute and UDPRoute diff --git a/site-src/guides/tls.md b/site-src/guides/tls.md index 41233815da..99ea9914c3 100644 --- a/site-src/guides/tls.md +++ b/site-src/guides/tls.md @@ -50,8 +50,6 @@ the Gateway. For `TLSRoute`, the use of `Terminate` means that the TLS termination happens on the `Gateway` and the connection to the backend may happen as a unencrypted TCP connection. -`BackendTLSPolicy` can be used in this case to re-encrypt the connection using different -set of certificate authorities, SNI and other configurations. ## Downstream TLS From 56c824362a1170affa7c40bfb40e980aa2127b9f Mon Sep 17 00:00:00 2001 From: Ricardo Pchevuzinske Katz Date: Tue, 7 Oct 2025 18:20:53 -0300 Subject: [PATCH 6/7] clarify that TLSRoute termination is extended feature --- site-src/concepts/api-overview.md | 2 +- site-src/guides/tls.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/site-src/concepts/api-overview.md b/site-src/concepts/api-overview.md index ef683161fb..494ea622f3 100644 --- a/site-src/concepts/api-overview.md +++ b/site-src/concepts/api-overview.md @@ -121,7 +121,7 @@ in properties of the higher-level protocols like HTTP. When using a `Passthrough TLS listener, the encrypted byte stream of the connection is proxied directly to the backend destination (which is then responsible for decrypting the stream) without any introspection beyond the TLS metadata. When using a `Terminate` -TLS listener, encryption is removed at the gateway to "unwrap" the connection, +TLS listener, encryption is terminated at the gateway to "unwrap" the connection, allowing traffic inspection and routing based on attributes of the inner request payload. diff --git a/site-src/guides/tls.md b/site-src/guides/tls.md index 99ea9914c3..ab76711d1f 100644 --- a/site-src/guides/tls.md +++ b/site-src/guides/tls.md @@ -34,7 +34,7 @@ For downstream connections, depending on the Listener Protocol, different TLS mo | Listener Protocol | TLS Mode | Route Type Supported | |-------------------|-------------|---------------------| | TLS | Passthrough | TLSRoute | -| TLS | Terminate | TLSRoute | +| TLS | Terminate | TLSRoute (extended) | | TLS | Terminate | TCPRoute | | HTTPS | Terminate | HTTPRoute | | GRPC | Terminate | GRPCRoute | From 1fabe017796ab7514c37b2b6efd12bddd13cfe35 Mon Sep 17 00:00:00 2001 From: Ricardo Pchevuzinske Katz Date: Tue, 7 Oct 2025 18:22:57 -0300 Subject: [PATCH 7/7] Reword how termination happens on TLSRoute Co-authored-by: Candace Holman --- site-src/guides/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site-src/guides/tls.md b/site-src/guides/tls.md index ab76711d1f..b225fe02ff 100644 --- a/site-src/guides/tls.md +++ b/site-src/guides/tls.md @@ -49,7 +49,7 @@ Using these together provides what is commonly known as a connection that is ter the Gateway. For `TLSRoute`, the use of `Terminate` means that the TLS termination happens on -the `Gateway` and the connection to the backend may happen as a unencrypted TCP connection. +the `Gateway` and the connection to the backend resumes as an unencrypted connection. ## Downstream TLS