Skip to content

Commit f63954f

Browse files
robscottrobscott
authored
Adding GEP 2907: TLS Configuration Placement and Terminology (#2910)
1 parent 3484e34 commit f63954f

File tree

3 files changed

+225
-0
lines changed

3 files changed

+225
-0
lines changed

‎geps/gep-2907/index.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# GEP-2907: TLS Configuration Placement and Terminology
2+
3+
* Issue: [#2907](https://github.com/kubernetes-sigs/gateway-api/issues/2907)
4+
* Status: Memorandum
5+
6+
## TLDR
7+
This GEP aims to define high level TLS terminology and structure within Gateway
8+
API to ensure that all our independent proposals related to TLS result in a
9+
coherent set of APIs. This will result in some adjustments to provisional and
10+
experimental TLS-related GEPs, specifically [BackendTLSPolicy](/geps/gep-1897)
11+
and [Client Certificate Verification](/geps/gep-91).
12+
13+
## Goals
14+
* Define high-level terminology for how we refer to TLS in Gateway API.
15+
* Define top level fields where TLS configuration can live.
16+
17+
## Non-Goals
18+
* Add or change fields directly. (This may inspire changes in other GEPs
19+
though).
20+
* Commit to including specific parts of TLS configuration in Gateway API. (This
21+
is merely to provide space for future configuration, not a commitment that we
22+
will add it to the API.)
23+
24+
## Out of Initial Scope
25+
There are a variety of related TLS concepts in Gateway API that are not currently
26+
in scope for this GEP. In the future, this GEP may be expanded to include:
27+
28+
1. Automatic mTLS (often associated with Service mesh)
29+
1. TLS Passthrough
30+
1. TLSRoute
31+
32+
33+
## Introduction
34+
35+
### Where TLS could be configured
36+
We have three different places where we might want to configure TLS:
37+
38+
#### A. Gateways
39+
Config attached at this layer will apply to everything behind a single address
40+
such as a virtual IP.
41+
42+
#### B. Gateway Listeners
43+
Each Gateway contains multiple “Listeners”. Each HTTPS Listener in a Gateway
44+
must have a unique combination of protocol, port, and SNI (Server Name
45+
Indication). TLS configuration attached at this layer should be [isolated via
46+
SNI](/guides/implementers/#listener-isolation).
47+
48+
#### C. BackendTLSPolicy
49+
This policy allows us to attach unique TLS configuration per Backend. Depending
50+
on the organization, this policy may be owned by the application owner or the
51+
cluster operator. Note that this configuration will be used by all Gateways
52+
(potentially from different implementations) that are connecting to the backend.
53+
54+
### "Frontend" and "Backend"
55+
A guiding principle in this naming is to use consistent naming for “Downstream”
56+
(1+2) and “Upstream” (3+4), similar to Envoy. To avoid the confusion with what
57+
is upstream and downstream, Gateway API will use “Frontend” (1+2) and “Backend”
58+
(3+4).
59+
60+
* **Frontend:** The entity connecting to a Gateway, typically a client
61+
application and/or web browser.
62+
* **Backend:** The entity a Gateway is routing traffic to, typically the
63+
endpoints behind a Service.
64+
65+
There are essentially 4 different segments that could be relevant to TLS
66+
configuration in Gateway API:
67+
68+
```mermaid
69+
flowchart LR
70+
Frontend -.->|1. Client Cert| Gateway
71+
Gateway -.->|2. Server Cert| Frontend
72+
Gateway -.->|3. Client Cert| Backend
73+
Backend -.->|4. Server Cert| Gateway
74+
```
75+
76+
The above diagram depicts these four segments as edges in a graph.
77+
78+
## Proposed Segments
79+
Note that this does not represent any form of commitment that any of these
80+
fields or concepts will exist within Gateway API. If or when they do, we propose
81+
the following naming structure:
82+
83+
### 1. Validate Client Certificate provided by Frontend
84+
85+
| Proposed Placement | Name | Status |
86+
|-|-|-|
87+
| Gateway Listener | `Listener.TLS.FrontendValidation` | Proposed |
88+
89+
#### Rationale
90+
Use FrontendValidation to leave room for concepts like trust anchors and trust
91+
domains. Anything not strictly tied to validation would belong to Listener.TLS
92+
which is now reserved exclusively for “Frontend” TLS configuration (1+2).
93+
94+
#### Why Not Frontend.Validation?
95+
Part of the idea behind this GEP is that Listener.TLS is really entirely focused
96+
on 1+2 - the bits of TLS between frontend and Gateway. That means that if we
97+
were to add any additional TLS configuration in the Listener.TLS struct, it
98+
would tied to that limited scope, and thus we don't really need a separate
99+
Frontend struct.
100+
101+
One could make an argument that Listener.TLS.Validation should be the field name
102+
here to avoid any ambiguity, but in this specific context, we think that it's
103+
probably helpful to specifically spell out frontend.
104+
105+
#### Why Not FrontendTLSPolicy?
106+
It could be reasonable to try to mirror BackendTLSPolicy for Frontend TLS. As we
107+
considered that possibility, we evaluated why BackendTLSPolicy exists as a
108+
separate policy resource:
109+
110+
1. Some parts of the config, such as the SNI that should be used to connect to
111+
the Service/backend only make sense when attached per Service - it's very
112+
unlikely that you'd want to use the same SNI to connect to all backends from
113+
a Gateway.
114+
1. The Service API is overloaded and very slow to change, Gateway API has taken
115+
the approach of exposing config at that level via policy resources that are
116+
tied to specific personas (why Session Persistence config and Backend TLS are
117+
in different resources).
118+
119+
We don't think either of those reasons really apply to frontend TLS. Instead,
120+
frontend TLS could theoretically be configured either for an entire Gateway, or
121+
a specific Gateway listener. Given that many implementations already support
122+
distinguishing this config per SNI, it seems to make sense to start with
123+
listener level attachment. We think that the persona that would be responsible
124+
for a Gateway is not sufficiently different than the persona that would be
125+
responsible for frontend TLS, so the current proposal is likely the best option
126+
available to us.
127+
128+
129+
### 2. Configure TLS Termination, including Server Certificate
130+
131+
| Proposed Placement | Name | Status |
132+
|-|-|-|
133+
| Gateway Listener | `Listener.TLS` | GA |
134+
135+
#### Rationale
136+
This is already finalized in the API and so we're stuck with this name. In
137+
hindsight a name that was more clearly tied to frontend TLS would have been
138+
ideal here.
139+
140+
141+
### 3. Configure Client Certificate that Gateway should use to connect to Backend
142+
143+
| Proposed Placement | Name | Status |
144+
|-|-|-|
145+
| Gateway | `Gateway.Spec.BackendTLS.ClientCertificateRef` | Not Proposed |
146+
| BackendTLSPolicy | `BackendTLSPolicy.Spec.ClientCertificateRef` | Not Proposed |
147+
148+
#### Rationale
149+
It's not yet obvious which of the above options are preferable, but a case could
150+
be made for either or both. If we add a `BackendTLS` struct to Gateway it would
151+
leave room for concepts like TLS version, ALPN, cipher suites, etc.
152+
153+
#### Why Not Listener level to match FrontendValidation?
154+
In general, we'd expect this identity to represent a Gateway as a whole, and
155+
thus per-Listener configuration probably does not make sense here. Having
156+
FrontendValidation at the Listener level allows a Gateway to accept different
157+
client certs per SNI (a matching attribute of the frontend -> Gateway
158+
connection). On the other hand, when determining the identity a Gateway should
159+
use when connecting to a backend, it should likely either be tied directly to
160+
the Gateway or Backend, but the Listener is not particularly relevant in this
161+
context.
162+
163+
164+
### 4. Validate Server Certificate that is provided by Backend
165+
| Proposed Placement | Name | Status |
166+
|-|-|-|
167+
| Gateway | `Gateway.Spec.BackendTLS.Validation` | Not Proposed |
168+
| BackendTLSPolicy | `BackendTLSPolicy.Spec.Validation` | Experimental (Different Name) |
169+
170+
#### Rationale
171+
Rename `BackendTLSPolicy.TLS` to `BackendTLSPolicy.Validation`. Because this is
172+
already clearly backend-focused, config like TLS Version, ALPN, and cipher
173+
suites, could live at the same level without confusion. It's also plausible that
174+
some Gateways may want to express Gateway-wide CAs that are trusted.
175+
176+
#### Why BackendTLS on Gateways?
177+
Although this GEP is intentionally not committing to adding new fields or
178+
features, it's possible that at some point in the future we may want to have
179+
some kind of Backend TLS config at the Gateway level. For example, it may be
180+
useful to configure a set of CAs that a Gateway trusts or a client cert that a
181+
Gateway should use to connect to all backends. If this existed, there would
182+
likely be some overlap in config with BackendTLSPolicy, and if a future GEP
183+
proposed this, it would need to include how overlapping config should be
184+
handled.
185+
186+
#### Why the inconsistency between Frontend and Backend TLS config on Gateways?
187+
If we were to populate all the possible fields described in this GEP, we'd end
188+
up with the following config on Gateways:
189+
190+
```
191+
Gateway.Spec.Listeners.TLS.FrontendValidation
192+
Gateway.Spec.Listeners.TLS
193+
Gateway.Spec.BackendTLS.ClientCertificateRef
194+
Gateway.Spec.BackendTLS.Validation
195+
```
196+
197+
This is all tied to the need to provide backwards compatibility with the TLS
198+
config that is already GA on Listeners (`Listener.TLS`). If we were naming that
199+
field today with the broader vision of TLS configuration throughout Gateway API
200+
we would almost certainly choose a more descriptive name that was more clearly
201+
tied to Frontend TLS. Unfortunately we're too late to change that name, but we
202+
can try to make the rest of the terminology clearly tied to frontend or backend
203+
TLS.
204+
205+
One [suggestion by @candita](https://github.com/kubernetes-sigs/gateway-api/pull/2910#discussion_r1552534017)
206+
would be to introduce a Listener like resource for BackendTLS, resulting in a
207+
more consistent naming scheme within Gateway TLS configuration. Although it's
208+
not yet clear if we need this additional layer, we should reconsider it as we're
209+
further developing Backend TLS.

‎geps/gep-2907/metadata.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
apiVersion: internal.gateway.networking.k8s.io/v1alpha1
2+
kind: GEPDetails
3+
number: 2907
4+
name: TLS Configuration Placement and Terminology
5+
status: Memorandum
6+
authors:
7+
- robscott
8+
relationships:
9+
seeAlso:
10+
- number: 91
11+
name: Client Certificate Verification for Gateway Listeners
12+
description: Will use some of the terminology defined by this GEP.
13+
- number: 1897
14+
name: TLS from Gateway to Backend
15+
description: Will use some of the terminology defined by this GEP.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,7 @@ nav:
147147
- geps/gep-1324/index.md
148148
- geps/gep-2659/index.md
149149
- geps/gep-2722/index.md
150+
- geps/gep-2907/index.md
150151
- Declined:
151152
- geps/gep-735/index.md
152153
- geps/gep-1282/index.md

0 commit comments

Comments
 (0)