From cbff145b4d8730446581385a428538f6c1fbb628 Mon Sep 17 00:00:00 2001 From: Mattia Lavacca Date: Mon, 8 Jul 2024 09:16:30 +0200 Subject: [PATCH] gep: TLS mode in gep-2907 Signed-off-by: Mattia Lavacca --- geps/gep-2907/index.md | 74 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 67 insertions(+), 7 deletions(-) diff --git a/geps/gep-2907/index.md b/geps/gep-2907/index.md index e3ff1dfcf1..d20cbc64a9 100644 --- a/geps/gep-2907/index.md +++ b/geps/gep-2907/index.md @@ -21,14 +21,12 @@ and [Client Certificate Verification](/geps/gep-91). is merely to provide space for future configuration, not a commitment that we will add it to the API.) -## Out of Initial Scope +## Out of Scope There are a variety of related TLS concepts in Gateway API that are not currently in scope for this GEP. In the future, this GEP may be expanded to include: 1. Automatic mTLS (often associated with Service mesh) -1. TLS Passthrough -1. TLSRoute - +2. TLSRoute ## Introduction @@ -75,6 +73,17 @@ flowchart LR The above diagram depicts these four segments as edges in a graph. +### TLS mode + +TLS can be configured with two distinct modes: + +* **Terminate**: the TLS connection is instantiated between the frontend and the + Gateway. The connection between the Gateway and the backend is left unencrypted + unless a new TLS connection between the two entities is configured via BackendTLSPolicy. +* **Passthrough**: the TLS connection is instantiated between the frontend and the + backend. The traffic flows through the Gateway encrypted, and the Gateway is not + able to decrypt or inspect the TLS stream. + ## Proposed Segments Note that this does not represent any form of commitment that any of these fields or concepts will exist within Gateway API. If or when they do, we propose @@ -125,7 +134,6 @@ for a Gateway is not sufficiently different than the persona that would be responsible for frontend TLS, so the current proposal is likely the best option available to us. - ### 2. Configure TLS Termination, including Server Certificate | Proposed Placement | Name | Status | @@ -137,7 +145,6 @@ This is already finalized in the API and so we're stuck with this name. In hindsight a name that was more clearly tied to frontend TLS would have been ideal here. - ### 3. Configure Client Certificate that Gateway should use to connect to Backend | Proposed Placement | Name | Status | @@ -160,7 +167,6 @@ use when connecting to a backend, it should likely either be tied directly to the Gateway or Backend, but the Listener is not particularly relevant in this context. - ### 4. Validate Server Certificate that is provided by Backend | Proposed Placement | Name | Status | |-|-|-| @@ -207,3 +213,57 @@ would be to introduce a Listener like resource for BackendTLS, resulting in a more consistent naming scheme within Gateway TLS configuration. Although it's not yet clear if we need this additional layer, we should reconsider it as we're further developing Backend TLS. + +### 5. Configure TLS mode + +| Proposed Placement | Name | Status | +|-|-|-| +| Gateway Listener | `Listener.TLS.Mode` | GA | + +#### Rationale + +Similarly to the broader [TLS termination](#2-configure-tls-termination-including-server-certificate) +segment, this field is already finalized in the API. In hindsight, along with a +different naming of `Listener.TLS`, we could have moved this field out of the broader +frontend TLS configuration, as it is not bound to it. + +#### How the TLS configuration is affected + +The TLS mode affects how the frontend TLS should be configured. In case `Terminate` +is set, the `Listener.TLS.CertificateRefs` field has to be populated, as the connection +is intended to be terminated at the Gateway level, while for `Passthrough`, the Certificate +does not need to be provided, as the TLS termination is handled by the backend. + +## Routes and TLS + +Multiple routes can be attached to listeners specifying TLS configuration. This section +intends to clearly state how and when Routes can attach to listeners with TLS configuration. + +### Context + +The `*Route` objects refer the Gateway (or a specific Listener of the Gateway) they +want to be attached to. A successful attachment can be granted by one of the two +following conditions: + +* the `Listener.AllowedRoutes` field allows that specific Route `GroupKind` to be + attached to it, or +* the `Listener.Protocol` field allows that specific Route to be attached to the + Listener. This applies only in case the Gateway's AllowedRoutes field is not set. + +In case the First condition is not satisfied (the Route references a Gateway that +does not explicitly allow such an attachment), the Route `Accepted` condition +is set to False with reason `NotAllowedByListeners`. In case the Route references +a Gateway with no Listener matching the protocol needed by the Route, the Route +`ResolvedRefs` condition is set to False with reason `UnsupportedProtocol`. + +### What Routes are allowed by Listeners with TLS + +The following is a summary of all the Routes and the TLS termination mode they support. + +| Route | TLS with Terminate | TLS with Passthrough | +|-|-|-| +| `HTTPRoute` | yes | no | +| `GRPCRoute` | yes | no | +| `TLSRoute` | yes | yes | +| `TCPRoute` | no | no | +| `UDPRoute` | no | no |