Skip to content

Commit a415539

Browse files
kflynnkflynn
committed
GEP-3949, Mesh resource
Signed-off-by: Flynn <[email protected]>
1 parent a48921a commit a415539

File tree

2 files changed

+297
-0
lines changed

2 files changed

+297
-0
lines changed

‎geps/gep-3949/index.md

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# GEP-3949: Mesh Resource
2+
3+
* Issue: [#3949](https://github.com/kubernetes-sigs/gateway-api/issues/3949)
4+
* Status: Provisional
5+
6+
(See [status definitions](../overview.md#gep-states).)
7+
8+
[Chihiro]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#chihiro
9+
[Ian]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#ian
10+
[Ana]: https//gateway-api.sigs.k8s.io/concepts/roles-and-personas/#ana
11+
12+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
13+
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
14+
document are to be interpreted as described in BCP 14 [RFC8174] when, and only
15+
when, they appear in all capitals, as shown here.
16+
17+
[RFC8174]: https://www.rfc-editor.org/rfc/rfc8174
18+
19+
## User Story
20+
21+
**[Chihiro] and [Ian] would like a Mesh resource,
22+
parallel to the Gateway resource,
23+
that allows them to
24+
supply mesh-wide configuration
25+
and
26+
shows what features
27+
a given mesh implementation supports.**
28+
29+
## Background
30+
31+
Gateway API has long had a GatewayClass resource
32+
that represents a class of Gateways
33+
that can be instantiated in a cluster.
34+
GatewayClass both
35+
allows configuring the class as a whole
36+
and provides a way for [Chihiro] and [Ian] to see
37+
what features Gateways in that class support.
38+
We have,
39+
to date,
40+
avoided such a resource for meshes,
41+
but as we work on
42+
improving mesh conformance tests and reports
43+
and start work on
44+
supporting Out-of-Cluster Gateways (OCGs),
45+
we will need ways to
46+
show what features a given mesh implementation supports
47+
and represent mesh-wide configuration.
48+
49+
Unlike Gateways, we do not expect
50+
multiple instances of meshes to be instantiated
51+
in a single cluster.
52+
This implies that a MeshClass resource is not needed;
53+
instead, we will simply define a Mesh resource.
54+
55+
## Goals
56+
57+
- Define a Mesh resource
58+
that allows for
59+
mesh-wide configuration
60+
and feature discovery.
61+
62+
## Non-Goals
63+
64+
- Support multiple instances of a mesh
65+
in a single cluster at the same time.
66+
67+
At some point, we may choose to
68+
change this goal,
69+
but it is definitely out of scope
70+
for this GEP.
71+
72+
- Support meshes interoperating with each other.
73+
74+
As always,
75+
we will not rule out future work
76+
in this area,
77+
but it is out of scope
78+
for this GEP.
79+
80+
- Support off-cluster gateways.
81+
82+
This is covered in a separate GEP
83+
and will not be discussed here.
84+
85+
## API
86+
87+
The purpose
88+
of the Mesh resource
89+
is to support both
90+
mesh-wide configuration
91+
as well as feature discovery.
92+
However,
93+
as of the writing of this GEP,
94+
there is
95+
no mesh-wide configuration
96+
that is portable across implementations.
97+
Therefore,
98+
the Mesh resource
99+
is currently pretty simple:
100+
101+
```yaml
102+
apiVersion: networking.x-k8s.io/v1alpha1
103+
kind: Mesh
104+
metadata:
105+
name: one-mesh-to-mesh-them-all
106+
spec:
107+
# required, must be domain-prefixed
108+
controllerName: one-mesh.example.com/one-mesh
109+
parametersRef:
110+
# optional ParametersReference
111+
...
112+
```
113+
114+
- The `controllerName` field
115+
is analogous to
116+
the `controllerName` field
117+
in the GatewayClass resource:
118+
it defines the name
119+
of the mesh implementation
120+
that is responsible for
121+
this Mesh resource.
122+
123+
Although we expect
124+
that there will be
125+
only one mesh
126+
in a given cluster, the
127+
`controllerName` field
128+
MUST be supplied,
129+
and a given mesh implementation
130+
MUST ignore
131+
a Mesh resource
132+
that does not have
133+
a `controllerName` field
134+
that matches its own name.
135+
136+
If a MeshClass resource
137+
is later defined,
138+
the Mesh resource
139+
will gain a
140+
`meshClassName` field,
141+
the `controllerName` field
142+
will be deprecated,
143+
and a
144+
Mesh resource
145+
that includes
146+
both `controllerName` and `meshClassName`
147+
will be invalid.
148+
149+
- The `parametersRef` field
150+
is analogous to
151+
the `parametersRef` field
152+
in the GatewayClass resource:
153+
it allows specifying
154+
a reference to a resource
155+
that contains configuration
156+
specific to the mesh
157+
implementation.
158+
159+
### `status`
160+
161+
The `status` stanza
162+
of the Mesh resource
163+
is used to indicate
164+
whether the Mesh resource
165+
has been accepted by
166+
a mesh implementation,
167+
whether the mesh is
168+
ready to use,
169+
and
170+
what features
171+
the mesh supports.
172+
173+
```yaml
174+
apiVersion: networking.x-k8s.io/v1
175+
kind: Mesh
176+
metadata:
177+
name: one-mesh-to-mesh-them-all
178+
namespace: mesh-namespace
179+
spec:
180+
controllerName: one-mesh.example.com/one-mesh
181+
status:
182+
conditions:
183+
# MUST include Accepted and Ready conditions if the Mesh resource is active.
184+
- type: Accepted # Becomes true when the controller accepts the Mesh resource
185+
status: "True"
186+
reason: MeshAccepted
187+
lastTransitionTime: "2023-10-01T12:00:00Z"
188+
message: Mesh resource accepted by one-mesh v1.2.3 in namespace one-mesh
189+
- type: Ready # Becomes true when the mesh is actually running
190+
status: "True"
191+
reason: MeshReady
192+
lastTransitionTime: "2023-10-01T12:00:15Z"
193+
message: one-mesh v1.2.3 is running
194+
...
195+
supportedFeatures:
196+
# List of SupportedFeature
197+
- name: MeshHTTPRoute
198+
- name: MeshConsumerRoute
199+
- name: OffClusterGateway
200+
...
201+
```
202+
203+
Although it is
204+
explicitly
205+
not a goal of this GEP
206+
to support multiple meshes
207+
running in the same cluster at the same time,
208+
meshes still MUST provide
209+
human-readable information
210+
in the `Accepted` condition
211+
about which mesh instance
212+
has claimed a given Mesh resource,
213+
and SHOULD provide human-readable
214+
information in the `Ready` condition,
215+
in support of future expansion work.
216+
This information is meant to be used
217+
by [Chihiro] and [Ian] as confirmation
218+
that the mesh instance
219+
is doing what they expect it to do.
220+
221+
The mesh implementation
222+
MUST set `status.SupportedFeatures`
223+
to indicate which features
224+
the mesh supports.
225+
226+
### API Type Definitions
227+
228+
TBA.
229+
230+
## Conformance Details
231+
232+
TBA.
233+
234+
#### Feature Names
235+
236+
No feature name is defined
237+
for the Mesh resource itself;
238+
filling out the `status` stanza
239+
of the Mesh resource
240+
is a conformance requirement,
241+
and is sufficient indication
242+
that the Mesh resource is supported.
243+
244+
### Conformance tests
245+
246+
TBA.
247+
248+
## Alternatives
249+
250+
We did not find any
251+
particularly compelling alternatives
252+
to having a Mesh resource
253+
to meet these needs.
254+
We considered having both
255+
MeshClass and Mesh resources,
256+
but decided that
257+
there was no clear need for both,
258+
and that a Mesh resource
259+
better served the use cases.
260+
261+
## References
262+
263+
TBA.

‎geps/gep-3949/metadata.yaml

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
apiVersion: internal.gateway.networking.k8s.io/v1alpha1
2+
kind: GEPDetails
3+
number: 3949
4+
name: Mesh Resource
5+
status: Provisional
6+
# Any authors who contribute to the GEP in any way should be listed here using
7+
# their GitHub handle.
8+
authors:
9+
- kflynn
10+
- karthikbox
11+
relationships:
12+
# obsoletes indicates that a GEP makes the linked GEP obsolete, and completely
13+
# replaces that GEP. The obsoleted GEP MUST have its obsoletedBy field
14+
# set back to this GEP, and MUST be moved to Declined.
15+
obsoletes: {}
16+
obsoletedBy: {}
17+
# extends indicates that a GEP extends the linked GEP, adding more detail
18+
# or additional implementation. The extended GEP MUST have its extendedBy
19+
# field set back to this GEP.
20+
extends: {}
21+
extendedBy: {}
22+
# seeAlso indicates other GEPs that are relevant in some way without being
23+
# covered by an existing relationship.
24+
seeAlso: {}
25+
# references is a list of hyperlinks to relevant external references.
26+
# It's intended to be used for storing GitHub discussions, Google docs, etc.
27+
references: {}
28+
# featureNames is a list of the feature names introduced by the GEP, if there
29+
# are any. This will allow us to track which feature was introduced by which GEP.
30+
# This is the value added to supportedFeatures and the conformance tests, in string form.
31+
featureNames: {}
32+
# changelog is a list of hyperlinks to PRs that make changes to the GEP, in
33+
# ascending date order.
34+
changelog: {}

0 commit comments

Comments
 (0)