Fix inconsistencies on TLSRoute documentation #4139

rikatz · 2025-10-01T21:07:16Z

What type of PR is this?
/kind documentation

What this PR does / why we need it:
TLSRoute documentation has some inconsistencies between what is supported, and how it is supported. This PR fixes these inconsistencies on the documentation.

Which issue(s) this PR fixes:
Fixes #1474

Does this PR introduce a user-facing change?:

NONE

rikatz · 2025-10-01T21:08:34Z

/cc @mikemorris

site-src/guides/tls.md

site-src/concepts/api-overview.md

mikemorris

LGTM aside from a minor nit about backend connections from the Gateway after TLS termination not necessarily being unencrypted.

/lgtm

rikatz · 2025-10-02T17:14:22Z

Thanks @mikemorris , I have fixed/tried to reword, let me know if this works

site-src/concepts/api-overview.md

rikatz · 2025-10-02T18:51:20Z

sounds good, commited here! thank you!

site-src/guides/tls.md

site-src/concepts/api-overview.md

Co-authored-by: Blake Covarrubias <[email protected]>

Co-authored-by: Mike Morris <[email protected]>

site-src/concepts/api-overview.md

site-src/guides/tls.md

Co-authored-by: Candace Holman <[email protected]>

rostislavbobo · 2025-10-09T15:13:09Z

site-src/concepts/api-overview.md

+allowing traffic inspection and routing based on attributes of the inner request
+payload.


What are the TLS "attributes of the inner request payload"?

we don't support ECH yet to route based on ClientHelloInner

TLSRoute is restricted to SNI-based routing and doesn't use other TLS metadata that requires decryption

TLSRoute doesn't rout based on the properties of higher-level protocols such as HTTP (as mentioned above)

yes, I had the same feeling of it, but I would say right now this should be clarified on the GEP + the routing is decided specifically on SNI.

Do you have a proposal to improve this text?

Added my suggestion.

In both TLS Passthrough and Terminate modes, TLSRoute makes routing decisions by inspecting unencrypted TLS metadata.

I'd reword "use the SNI as the main routing method" to "route based on TLS metadata" so that when we add ALPN we don't need to rework this section again.

A side note: Even when we add ECH support, it won't change this much, as both TLS Passthrough and Terminate modes will have access to ESNI.

mikemorris · 2025-10-09T17:39:49Z

site-src/guides/tls.md

 the Gateway.

+For `TLSRoute`, the use of `Terminate` means that the TLS termination happens on 
+the `Gateway` and the connection to the backend resumes as an unencrypted connection. 


Suggested change

the `Gateway` and the connection to the backend resumes as an unencrypted connection.

the `Gateway` and the connection to the backend resumes as an unencrypted connection,

unless the connection from the Gateway to the backend is encrypted by some other

mechanism.

I'm specifically thinking of mesh-integrated ingress gateways here, whether Istio's ingress which can initiate mTLS to a backend, or Linkerd deploying a sidecar next to an ingress, and trying to avoid any explicit mention of BackendTLSPolicy. Does this sound okay to you @candita?

I think we don't need this section here, it can be removed. We already say this in https://github.com/kubernetes-sigs/gateway-api/pull/4139/files#diff-631650e61708a9c464016c50834d5def9b4967b7daade9fcd5d8c2c175c3e317R120-R126.

If we keep it, the two sections should express consistent views.

ok I have removed the session and kept only the phrase

"The use of Terminate on TLSRoute is available on Extended [Support Level]." as we may want to be explicit that Terminate is Extended support level

candita · 2025-10-09T18:50:51Z

site-src/concepts/api-overview.md

+without any introspection beyond the TLS metadata. When using a `Terminate`
+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.


Suggested change

without any introspection beyond the TLS metadata. When using a `Terminate`

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.

without any introspection beyond the TLS metadata. When using a `Terminate`

TLS listener, the encryption is terminated at the gateway.

rostislavbobo · 2025-10-09T20:03:41Z

site-src/concepts/api-overview.md

 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. 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 terminated at the gateway to "unwrap" the connection,
+allowing traffic inspection and routing based on attributes of the inner request
+payload.


Suggested change

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. 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 terminated at the gateway to "unwrap" the connection,

allowing traffic inspection and routing based on attributes of the inner request

payload.

for where you want to route based on TLS metadata, and are not interested 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 destination backend,

which is then responsible for decrypting the stream. When using a `Terminate` TLS

listener, encryption is terminated at the gateway.

The "unwrap" metaphor doesn't really add much here. Reminds me of a gift or a sandwich.

Agree, dropping it makes the sentence clean and clearer without impacting the meaning.
Updated.

I will have to copy/paste on my own commit here because Github is being annoying and not allowing me to add it directly

rostislavbobo · 2025-10-09T20:04:19Z

site-src/concepts/api-overview.md

+allowing traffic inspection and routing based on attributes of the inner request
+payload.


Added my suggestion.

In both TLS Passthrough and Terminate modes, TLSRoute makes routing decisions by inspecting unencrypted TLS metadata.

I'd reword "use the SNI as the main routing method" to "route based on TLS metadata" so that when we add ALPN we don't need to rework this section again.

A side note: Even when we add ECH support, it won't change this much, as both TLS Passthrough and Terminate modes will have access to ESNI.

rostislavbobo · 2025-10-10T18:35:30Z

Thanks @rikatz !

/ok-to-test
/lgtm
/approve

candita · 2025-10-10T22:28:17Z

/lgtm
/assign @robscott

robscott · 2025-10-10T23:29:00Z

Thanks @rikatz!

/approve

k8s-ci-robot · 2025-10-10T23:29:08Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: mikemorris, rikatz, robscott, rostislavbobo

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~site-src/OWNERS~~ [robscott]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

* Fix inconsistencies on TLSRoute documentation * Apply suggestions Co-authored-by: Blake Covarrubias <[email protected]> * Clarify on TLSRoute termination * Reword on TLSRoute termination Co-authored-by: Mike Morris <[email protected]> * Remove mention to BTLSPolicy on TLSroute * clarify that TLSRoute termination is extended feature * Reword how termination happens on TLSRoute Co-authored-by: Candace Holman <[email protected]> * Finalize TLSRoute wording --------- Co-authored-by: Blake Covarrubias <[email protected]> Co-authored-by: Mike Morris <[email protected]> Co-authored-by: Candace Holman <[email protected]>

k8s-ci-robot requested review from howardjohn and robscott October 1, 2025 21:07

k8s-ci-robot requested a review from mikemorris October 1, 2025 21:08

blake reviewed Oct 1, 2025

View reviewed changes

site-src/guides/tls.md Outdated Show resolved Hide resolved

mikemorris reviewed Oct 2, 2025

View reviewed changes

site-src/concepts/api-overview.md Outdated Show resolved Hide resolved

mikemorris reviewed Oct 2, 2025

View reviewed changes

site-src/concepts/api-overview.md Show resolved Hide resolved

mikemorris approved these changes Oct 2, 2025

View reviewed changes

mikemorris reviewed Oct 2, 2025

View reviewed changes

site-src/concepts/api-overview.md Outdated Show resolved Hide resolved

candita reviewed Oct 3, 2025

View reviewed changes

site-src/guides/tls.md Outdated Show resolved Hide resolved

candita reviewed Oct 3, 2025

View reviewed changes

site-src/concepts/api-overview.md Outdated Show resolved Hide resolved

rikatz and others added 5 commits October 7, 2025 17:11

Fix inconsistencies on TLSRoute documentation

9c620fc

Apply suggestions

63f461f

Co-authored-by: Blake Covarrubias <[email protected]>

Clarify on TLSRoute termination

35584cf

Reword on TLSRoute termination

58c1951

Co-authored-by: Mike Morris <[email protected]>

Remove mention to BTLSPolicy on TLSroute

278e488

rikatz force-pushed the docs-tls-support branch from cdbd11a to 278e488 Compare October 7, 2025 20:15

candita reviewed Oct 7, 2025

View reviewed changes

site-src/concepts/api-overview.md Outdated Show resolved Hide resolved

candita reviewed Oct 7, 2025

View reviewed changes

site-src/guides/tls.md Outdated Show resolved Hide resolved

candita reviewed Oct 7, 2025

View reviewed changes

site-src/guides/tls.md Outdated Show resolved Hide resolved

rikatz and others added 2 commits October 7, 2025 18:20

clarify that TLSRoute termination is extended feature

56c8243

Reword how termination happens on TLSRoute

615bf11

Co-authored-by: Candace Holman <[email protected]>

rikatz force-pushed the docs-tls-support branch from 1fabe01 to 615bf11 Compare October 9, 2025 12:47

rikatz requested a review from candita October 9, 2025 12:49

rikatz requested review from mikemorris and rostislavbobo October 9, 2025 12:49

rostislavbobo approved these changes Oct 9, 2025

View reviewed changes

mikemorris reviewed Oct 9, 2025

View reviewed changes

candita reviewed Oct 9, 2025

View reviewed changes

rostislavbobo reviewed Oct 9, 2025

View reviewed changes

Finalize TLSRoute wording

21d2f55

rikatz requested review from candita, mikemorris and rostislavbobo October 10, 2025 17:26

k8s-ci-robot added the ok-to-test Indicates a non-member PR verified by an org member that is safe to test. label Oct 10, 2025

k8s-ci-robot assigned rostislavbobo Oct 10, 2025

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Oct 10, 2025

rostislavbobo approved these changes Oct 10, 2025

View reviewed changes

k8s-ci-robot assigned robscott and candita Oct 10, 2025

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Oct 10, 2025

k8s-ci-robot merged commit 5f1a339 into kubernetes-sigs:main Oct 10, 2025
20 checks passed

		allowing traffic inspection and routing based on attributes of the inner request
		payload.

-the `Gateway` and the connection to the backend resumes as an unencrypted connection.
+the `Gateway` and the connection to the backend resumes as an unencrypted connection,
+unless the connection from the Gateway to the backend is encrypted by some other
+mechanism.

Fix inconsistencies on TLSRoute documentation #4139

Fix inconsistencies on TLSRoute documentation #4139

Uh oh!

Conversation

rikatz commented Oct 1, 2025

Uh oh!

rikatz commented Oct 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mikemorris left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rikatz commented Oct 2, 2025

Uh oh!

Uh oh!

rikatz commented Oct 2, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

candita Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rostislavbobo Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rostislavbobo Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rostislavbobo commented Oct 10, 2025

Uh oh!

candita commented Oct 10, 2025

Uh oh!

robscott commented Oct 10, 2025

Uh oh!

k8s-ci-robot commented Oct 10, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

mikemorris left a comment •

edited

Loading

candita Oct 10, 2025 •

edited

Loading

rostislavbobo Oct 9, 2025 •

edited

Loading

rostislavbobo Oct 10, 2025 •

edited

Loading