Adding GEP 2907: TLS Configuration Placement and Terminology

geps/gep-2907/index.md

@@ -0,0 +1,109 @@
+# GEP-2907: TLS Configuration Placement and Terminology
+
+* Issue: [#2907](https://github.com/kubernetes-sigs/gateway-api/issues/2907)
+* Status: Memorandum
+
+## TLDR
+This GEP aims to define high level TLS terminology and structure within Gateway
+API to ensure that all our independent proposals related to TLS result in a
+coherent set of APIs.
+
+## Goals
+* Define high-level terminology for how we refer to TLS in Gateway API.
+* Define top level fields where TLS configuration can live.
+
+## Non-Goals
+* Add or change fields directly. (This may inspire changes in other GEPs
+  though).
+* Commit to including specific parts of TLS configuration in Gateway API. (This
+  is merely to provide space for future configuration, not a commitment that we
+  will add it to the API.)
+
+## Introduction
+
+There are essentially 4 different "buckets" that could be relevant to TLS
+configuration in Gateway API:
+
+```mermaid
+flowchart LR
+    Frontend -.->|1. Client Cert| Gateway
+    Gateway -.->|2. Server Cert| Frontend
+    Gateway -.->|3. Client Cert| Backend
+    Backend -.->|4. Server Cert| Gateway
+```
+
+### Where it can fit
+We have three different places where this configuration could live:
+
+#### A. Gateways
+We can add config that applies to an entire Gateway. Config attached at this
+layer will apply to everything behind a single VIP.
+
+#### B. Gateway Listeners
+Each Gateway contains multiple “Listeners”. Each Listener in a Gateway must have
+a unique combination of protocol, port, and hostname (SNI in the case of HTTPS).
+TLS configuration attached at this layer needs to be isolated via SNI.
+
+#### C. BackendTLSPolicy
+This policy allows us to attach unique TLS configuration per Backend. Depending
+on the organization, this policy may be owned by the application owner or the LB
+admin. Note that this configuration will be used by all Gateways (potentially
+from different implementations) that are connecting to the backend.
+
+## Proposed Buckets
+Note that this does not represent any form of commitment that any of these
+fields or concepts will exist within Gateway API. If they did, they would follow
+the following naming structure though:
+
+### 1. Validate Client Certificate provided by Source Workload
+
+| Proposed Placement | Name | Status |
+|-|-|-|
+| Gateway Listener | `Listener.TLS.FrontendValidation` | Proposed |
+
+#### Rationale
+Use FrontendValidation to leave room for concepts like trust anchors and trust
+domains. Anything not strictly tied to validation would belong to Listener.TLS
+which is now reserved exclusively for “Frontend” TLS configuration (1+2).
+
+### 2. Configure TLS Termination, including Server Certificate
+
+| Proposed Placement | Name | Status |
+|-|-|-|
+| Gateway Listener | `Listener.TLS` | GA |
+
+#### Rationale
+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 |
+|-|-|-|
+| Gateway | `Gateway.BackendTLS.ClientCertificateRef` | Not Proposed |
+| BackendTLSPolicy | `BackendTLSPolicy.ClientCertificateRef` | Not Proposed |
+
+#### Rationale
+It's not yet obvious which of the above options are preferable, but a case could
+be made for either or both. If we add a `BackendTLS` struct to Gateway it would
+leave room for concepts like TLS version, ALPN, cipher suites, etc.
+
+
+### 4. Validate Server Certificate that is provided by Backend
+| Proposed Placement | Name | Status |
+|-|-|-|
+| Gateway | `Gateway.BackendTLS.Validation` | Not Proposed |
+| BackendTLSPolicy | `BackendTLS.Validation` | Experimental (Different Name) |
+
+#### Rationale
+Rename `BackendTLSPolicy.TLS` to `BackendTLSPolicy.Validation`. Because this is
+already clearly backend-focused, config like TLS Version, ALPN, and cipher
+suites, could live at the same level without confusion. It's also plausible that
+some Gateways may want to express Gateway-wide CAs that are trusted.
+
+## "Frontend" and "Backend"
+A guiding principle in this naming is to use consistent naming for “Upstream”
+(1+2) and “Downstream” (3+4), similar to Envoy. To avoid the confusion with what
+is upstream and downstream, Gateway API will use “Frontend” and “Backend”.

geps/gep-2907/metadata.yaml

@@ -0,0 +1,15 @@
+apiVersion: internal.gateway.networking.k8s.io/v1alpha1
+kind: GEPDetails
+number: 2907
+name: TLS Configuration Placement and Terminology
+status: Memorandum
+authors:
+  - robscott
+relationships:
+  seeAlso:
+    - number: 91
+      name: Client Certificate Verification for Gateway Listeners
+      description: Will use some of the terminology defined by this GEP.
+    - number: 1897
+      name: TLS from Gateway to Backend
+      description: Will use some of the terminology defined by this GEP.

mkdocs.yml

@@ -146,6 +146,7 @@ nav:
       - geps/gep-1324/index.md
       - geps/gep-2659/index.md
       - geps/gep-2722/index.md
+      - geps/gep-2907/index.md
     - Declined:
       - geps/gep-735/index.md
       - geps/gep-1282/index.md