From 7ad3e03257bf726bf61637cb37e89d498e1fbb04 Mon Sep 17 00:00:00 2001 From: Flynn Date: Wed, 23 Jul 2025 14:38:13 -0400 Subject: [PATCH 01/20] GEP-3949, Mesh resource Signed-off-by: Flynn --- geps/gep-3949/index.md | 263 ++++++++++++++++++++++++++++++++++++ geps/gep-3949/metadata.yaml | 34 +++++ 2 files changed, 297 insertions(+) create mode 100644 geps/gep-3949/index.md create mode 100644 geps/gep-3949/metadata.yaml diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md new file mode 100644 index 0000000000..834d0b144d --- /dev/null +++ b/geps/gep-3949/index.md @@ -0,0 +1,263 @@ +# GEP-3949: Mesh Resource + +* Issue: [#3949](https://github.com/kubernetes-sigs/gateway-api/issues/3949) +* Status: Provisional + +(See [status definitions](../overview.md#gep-states).) + +[Chihiro]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#chihiro +[Ian]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#ian +[Ana]: https//gateway-api.sigs.k8s.io/concepts/roles-and-personas/#ana + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted as described in BCP 14 [RFC8174] when, and only +when, they appear in all capitals, as shown here. + +[RFC8174]: https://www.rfc-editor.org/rfc/rfc8174 + +## User Story + +**[Chihiro] and [Ian] would like a Mesh resource, +parallel to the Gateway resource, +that allows them to +supply mesh-wide configuration +and +shows what features +a given mesh implementation supports.** + +## Background + +Gateway API has long had a GatewayClass resource +that represents a class of Gateways +that can be instantiated in a cluster. +GatewayClass both +allows configuring the class as a whole +and provides a way for [Chihiro] and [Ian] to see +what features Gateways in that class support. +We have, +to date, +avoided such a resource for meshes, +but as we work on +improving mesh conformance tests and reports +and start work on +supporting Out-of-Cluster Gateways (OCGs), +we will need ways to +show what features a given mesh implementation supports +and represent mesh-wide configuration. + +Unlike Gateways, we do not expect +multiple instances of meshes to be instantiated +in a single cluster. +This implies that a MeshClass resource is not needed; +instead, we will simply define a Mesh resource. + +## Goals + +- Define a Mesh resource + that allows for + mesh-wide configuration + and feature discovery. + +## Non-Goals + +- Support multiple instances of a mesh + in a single cluster at the same time. + + At some point, we may choose to + change this goal, + but it is definitely out of scope + for this GEP. + +- Support meshes interoperating with each other. + + As always, + we will not rule out future work + in this area, + but it is out of scope + for this GEP. + +- Support off-cluster gateways. + + This is covered in a separate GEP + and will not be discussed here. + +## API + +The purpose +of the Mesh resource +is to support both +mesh-wide configuration +as well as feature discovery. +However, +as of the writing of this GEP, +there is +no mesh-wide configuration +that is portable across implementations. +Therefore, +the Mesh resource +is currently pretty simple: + +```yaml +apiVersion: networking.x-k8s.io/v1alpha1 +kind: Mesh +metadata: + name: one-mesh-to-mesh-them-all +spec: + # required, must be domain-prefixed + controllerName: one-mesh.example.com/one-mesh + parametersRef: + # optional ParametersReference + ... +``` + +- The `controllerName` field + is analogous to + the `controllerName` field + in the GatewayClass resource: + it defines the name + of the mesh implementation + that is responsible for + this Mesh resource. + + Although we expect + that there will be + only one mesh + in a given cluster, the + `controllerName` field + MUST be supplied, + and a given mesh implementation + MUST ignore + a Mesh resource + that does not have + a `controllerName` field + that matches its own name. + + If a MeshClass resource + is later defined, + the Mesh resource + will gain a + `meshClassName` field, + the `controllerName` field + will be deprecated, + and a + Mesh resource + that includes + both `controllerName` and `meshClassName` + will be invalid. + +- The `parametersRef` field + is analogous to + the `parametersRef` field + in the GatewayClass resource: + it allows specifying + a reference to a resource + that contains configuration + specific to the mesh + implementation. + +### `status` + +The `status` stanza +of the Mesh resource +is used to indicate +whether the Mesh resource +has been accepted by +a mesh implementation, +whether the mesh is +ready to use, +and +what features +the mesh supports. + +```yaml +apiVersion: networking.x-k8s.io/v1 +kind: Mesh +metadata: + name: one-mesh-to-mesh-them-all + namespace: mesh-namespace +spec: + controllerName: one-mesh.example.com/one-mesh +status: + conditions: + # MUST include Accepted and Ready conditions if the Mesh resource is active. + - type: Accepted # Becomes true when the controller accepts the Mesh resource + status: "True" + reason: MeshAccepted + lastTransitionTime: "2023-10-01T12:00:00Z" + message: Mesh resource accepted by one-mesh v1.2.3 in namespace one-mesh + - type: Ready # Becomes true when the mesh is actually running + status: "True" + reason: MeshReady + lastTransitionTime: "2023-10-01T12:00:15Z" + message: one-mesh v1.2.3 is running + ... + supportedFeatures: + # List of SupportedFeature + - name: MeshHTTPRoute + - name: MeshConsumerRoute + - name: OffClusterGateway + ... +``` + +Although it is +explicitly +not a goal of this GEP +to support multiple meshes +running in the same cluster at the same time, +meshes still MUST provide +human-readable information +in the `Accepted` condition +about which mesh instance +has claimed a given Mesh resource, +and SHOULD provide human-readable +information in the `Ready` condition, +in support of future expansion work. +This information is meant to be used +by [Chihiro] and [Ian] as confirmation +that the mesh instance +is doing what they expect it to do. + +The mesh implementation +MUST set `status.SupportedFeatures` +to indicate which features +the mesh supports. + +### API Type Definitions + +TBA. + +## Conformance Details + +TBA. + +#### Feature Names + +No feature name is defined +for the Mesh resource itself; +filling out the `status` stanza +of the Mesh resource +is a conformance requirement, +and is sufficient indication +that the Mesh resource is supported. + +### Conformance tests + +TBA. + +## Alternatives + +We did not find any +particularly compelling alternatives +to having a Mesh resource +to meet these needs. +We considered having both +MeshClass and Mesh resources, +but decided that +there was no clear need for both, +and that a Mesh resource +better served the use cases. + +## References + +TBA. diff --git a/geps/gep-3949/metadata.yaml b/geps/gep-3949/metadata.yaml new file mode 100644 index 0000000000..d4696a94bf --- /dev/null +++ b/geps/gep-3949/metadata.yaml @@ -0,0 +1,34 @@ +apiVersion: internal.gateway.networking.k8s.io/v1alpha1 +kind: GEPDetails +number: 3949 +name: Mesh Resource +status: Provisional +# Any authors who contribute to the GEP in any way should be listed here using +# their GitHub handle. +authors: + - kflynn + - karthikbox +relationships: + # obsoletes indicates that a GEP makes the linked GEP obsolete, and completely + # replaces that GEP. The obsoleted GEP MUST have its obsoletedBy field + # set back to this GEP, and MUST be moved to Declined. + obsoletes: {} + obsoletedBy: {} + # extends indicates that a GEP extends the linked GEP, adding more detail + # or additional implementation. The extended GEP MUST have its extendedBy + # field set back to this GEP. + extends: {} + extendedBy: {} + # seeAlso indicates other GEPs that are relevant in some way without being + # covered by an existing relationship. + seeAlso: {} +# references is a list of hyperlinks to relevant external references. +# It's intended to be used for storing GitHub discussions, Google docs, etc. +references: {} +# featureNames is a list of the feature names introduced by the GEP, if there +# are any. This will allow us to track which feature was introduced by which GEP. +# This is the value added to supportedFeatures and the conformance tests, in string form. +featureNames: {} +# changelog is a list of hyperlinks to PRs that make changes to the GEP, in +# ascending date order. +changelog: {} From dbc2d1b59c5e2ef1b763150a9fdc80dd47bc0d99 Mon Sep 17 00:00:00 2001 From: Flynn Date: Wed, 23 Jul 2025 14:39:54 -0400 Subject: [PATCH 02/20] Tweak punctuation Signed-off-by: Flynn --- geps/gep-3949/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 834d0b144d..5aaa64028d 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -11,8 +11,8 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this -document are to be interpreted as described in BCP 14 [RFC8174] when, and only -when, they appear in all capitals, as shown here. +document are to be interpreted as described in BCP 14 ([RFC8174]) when, and +only when, they appear in all capitals, as shown here. [RFC8174]: https://www.rfc-editor.org/rfc/rfc8174 From cf82eebbb749b058a5de42130382b10fc77baf11 Mon Sep 17 00:00:00 2001 From: Flynn Date: Wed, 23 Jul 2025 16:07:48 -0400 Subject: [PATCH 03/20] Update to experimental API group and resource name Signed-off-by: Flynn --- geps/gep-3949/index.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 5aaa64028d..c2553b10c3 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -99,8 +99,8 @@ the Mesh resource is currently pretty simple: ```yaml -apiVersion: networking.x-k8s.io/v1alpha1 -kind: Mesh +apiVersion: gateway.networking.x-k8s.io/v1alpha1 +kind: XMesh metadata: name: one-mesh-to-mesh-them-all spec: @@ -111,6 +111,15 @@ spec: ... ``` +- Although we call this the Mesh resource, + as an experimental API + it must be named XMesh + in the `gateway.networking.x-k8s.io` API group. + + When the API graduates to standard, + it will be renamed to `Mesh` + in the `gateway.networking.k8s.io` API group. + - The `controllerName` field is analogous to the `controllerName` field @@ -171,8 +180,8 @@ what features the mesh supports. ```yaml -apiVersion: networking.x-k8s.io/v1 -kind: Mesh +apiVersion: gateway.networking.x-k8s.io/v1 +kind: XMesh metadata: name: one-mesh-to-mesh-them-all namespace: mesh-namespace From 0809e1539e206f2b523cf574498f34784c753315 Mon Sep 17 00:00:00 2001 From: Flynn Date: Wed, 23 Jul 2025 16:10:48 -0400 Subject: [PATCH 04/20] More tweak Signed-off-by: Flynn --- geps/gep-3949/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index c2553b10c3..ae93a92eee 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -180,7 +180,7 @@ what features the mesh supports. ```yaml -apiVersion: gateway.networking.x-k8s.io/v1 +apiVersion: gateway.networking.x-k8s.io/v1alpha1 kind: XMesh metadata: name: one-mesh-to-mesh-them-all From 0ee67e65fd64358b2d3ecaa3ec13e36656d571c5 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 00:21:09 -0400 Subject: [PATCH 05/20] Indentation fix Signed-off-by: Flynn --- geps/gep-3949/index.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index ae93a92eee..048912a755 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -132,15 +132,15 @@ spec: Although we expect that there will be only one mesh - in a given cluster, the - `controllerName` field - MUST be supplied, - and a given mesh implementation - MUST ignore - a Mesh resource - that does not have - a `controllerName` field - that matches its own name. + in a given cluster, the + `controllerName` field + MUST be supplied, + and a given mesh implementation + MUST ignore + a Mesh resource + that does not have + a `controllerName` field + that matches its own name. If a MeshClass resource is later defined, From a403a68bb0557cdf41580b531ca75f1e7ad72188 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 00:21:38 -0400 Subject: [PATCH 06/20] Note that changing GAMMA's position on multiple meshes is a non-goal Signed-off-by: Flynn --- geps/gep-3949/index.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 048912a755..ed1b06ab07 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -82,6 +82,16 @@ instead, we will simply define a Mesh resource. This is covered in a separate GEP and will not be discussed here. +- Change GAMMA's position on + multiple meshes running simultaneously + in a single cluster. + + GAMMA has always taken the position + that multiple meshes running simultaneously + in a single cluster + is not a goal, but neither is it forbidden. + This GEP does not change that position. + ## API The purpose From f942bfac00f82a089928af7679069e3c6c3072ec Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 00:21:54 -0400 Subject: [PATCH 07/20] Review feedback Signed-off-by: Flynn --- geps/gep-3949/index.md | 48 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index ed1b06ab07..fc31e1b851 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -121,6 +121,9 @@ spec: ... ``` +- The Mesh resource is cluster-scoped, + so there is no `metadata.namespace` field. + - Although we call this the Mesh resource, as an experimental API it must be named XMesh @@ -242,6 +245,51 @@ MUST set `status.SupportedFeatures` to indicate which features the mesh supports. +### Life Cycle + +A mesh implementation MUST NOT create a Mesh resource +if one does not already exist. + +If a mesh implementation does not find a Mesh resource +with a matching `controllerName` at startup: + +- It SHOULD warn the user + (in whatever way is appropriate for the mesh) + that the Mesh resource is missing. + +- It MUST act as if a Mesh resource was found + with an empty `spec` + (other than the `controllerName` field). + Optional configuration MUST remain in its default state, + and features that require a Mesh resource + (such as OCG support) + MUST NOT be enabled. + +Obviously, if no matching Mesh resource exists, +the mesh will not be able to publish support features, +which may lead to assumptions +that the mesh does not support any features. + +Meshes SHOULD provide a default Mesh resource +when the mesh is installed, +so that neither [Chihiro] or [Ian] need to know +the `controllerName` +before installing the mesh. +(For example, +a mesh's Helm chart might include +a default Mesh resource +with only the `controllerName` field set, +with the assumption +that [Chihiro] or [Ian] will later edit the resource.) + +This is in contrast to the GatewayClass resource, +which must be explicitly created by [Ian] +when the Gateway controller is installed. +This is primarily because GAMMA meshes +have historically not had a Mesh resource, +so requiring [Chihiro] or [Ian] to create one by hand +is a significant barrier to mesh adoption. + ### API Type Definitions TBA. From d9e19e7b809aa5c4df82d702816db29e200a2876 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 11:15:22 -0400 Subject: [PATCH 08/20] Fix list-element indentation Signed-off-by: Flynn --- geps/gep-3949/index.md | 88 +++++++++++++++++++++--------------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index fc31e1b851..7d76870e5d 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -64,33 +64,33 @@ instead, we will simply define a Mesh resource. - Support multiple instances of a mesh in a single cluster at the same time. - At some point, we may choose to - change this goal, - but it is definitely out of scope - for this GEP. + At some point, we may choose to + change this goal, + but it is definitely out of scope + for this GEP. - Support meshes interoperating with each other. - As always, - we will not rule out future work - in this area, - but it is out of scope - for this GEP. + As always, + we will not rule out future work + in this area, + but it is out of scope + for this GEP. - Support off-cluster gateways. - This is covered in a separate GEP - and will not be discussed here. + This is covered in a separate GEP + and will not be discussed here. - Change GAMMA's position on multiple meshes running simultaneously in a single cluster. - GAMMA has always taken the position - that multiple meshes running simultaneously - in a single cluster - is not a goal, but neither is it forbidden. - This GEP does not change that position. + GAMMA has always taken the position + that multiple meshes running simultaneously + in a single cluster + is not a goal, but neither is it forbidden. + This GEP does not change that position. ## API @@ -129,9 +129,9 @@ spec: it must be named XMesh in the `gateway.networking.x-k8s.io` API group. - When the API graduates to standard, - it will be renamed to `Mesh` - in the `gateway.networking.k8s.io` API group. + When the API graduates to standard, + it will be renamed to `Mesh` + in the `gateway.networking.k8s.io` API group. - The `controllerName` field is analogous to @@ -142,31 +142,31 @@ spec: that is responsible for this Mesh resource. - Although we expect - that there will be - only one mesh - in a given cluster, the - `controllerName` field - MUST be supplied, - and a given mesh implementation - MUST ignore - a Mesh resource - that does not have - a `controllerName` field - that matches its own name. - - If a MeshClass resource - is later defined, - the Mesh resource - will gain a - `meshClassName` field, - the `controllerName` field - will be deprecated, - and a - Mesh resource - that includes - both `controllerName` and `meshClassName` - will be invalid. + Although we expect + that there will be + only one mesh + in a given cluster, the + `controllerName` field + MUST be supplied, + and a given mesh implementation + MUST ignore + a Mesh resource + that does not have + a `controllerName` field + that matches its own name. + + If a MeshClass resource + is later defined, + the Mesh resource + will gain a + `meshClassName` field, + the `controllerName` field + will be deprecated, + and a + Mesh resource + that includes + both `controllerName` and `meshClassName` + will be invalid. - The `parametersRef` field is analogous to From ded3c901782bb0b0e66975228d15d58ca0fff099 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 11:25:13 -0400 Subject: [PATCH 09/20] Add a mkdocs.yml entry. :man_facepalming: Signed-off-by: Flynn --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index d29e212746..99e9b4012d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -132,6 +132,7 @@ nav: - geps/gep-2648/index.md - geps/gep-3779/index.md - geps/gep-3792/index.md + - geps/gep-3949/index.md - Implementable: - geps/gep-91/index.md - geps/gep-3567/index.md From e393c2d68da8a06ee0a66cc70f32b0588415e6c3 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 11:32:36 -0400 Subject: [PATCH 10/20] Review feedback Signed-off-by: Flynn --- geps/gep-3949/index.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 7d76870e5d..50740c8d2d 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -205,14 +205,9 @@ status: # MUST include Accepted and Ready conditions if the Mesh resource is active. - type: Accepted # Becomes true when the controller accepts the Mesh resource status: "True" - reason: MeshAccepted + reason: Accepted lastTransitionTime: "2023-10-01T12:00:00Z" message: Mesh resource accepted by one-mesh v1.2.3 in namespace one-mesh - - type: Ready # Becomes true when the mesh is actually running - status: "True" - reason: MeshReady - lastTransitionTime: "2023-10-01T12:00:15Z" - message: one-mesh v1.2.3 is running ... supportedFeatures: # List of SupportedFeature From f4e814a5c9340ebe605b5f47c79fada82d1ebecc Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 15:47:54 -0400 Subject: [PATCH 11/20] Initial type definition Signed-off-by: Flynn --- geps/gep-3949/index.md | 138 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 136 insertions(+), 2 deletions(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 50740c8d2d..da2be602b3 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -172,7 +172,7 @@ spec: is analogous to the `parametersRef` field in the GatewayClass resource: - it allows specifying + it allows optionally specifying a reference to a resource that contains configuration specific to the mesh @@ -287,7 +287,141 @@ is a significant barrier to mesh adoption. ### API Type Definitions -TBA. +```go +// Mesh is a Cluster level resource. +type Mesh struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + // Spec defines the desired state of Mesh. + Spec MeshSpec `json:"spec"` + + // Status defines the current state of Mesh. + // + // Implementations MUST populate status on all Mesh resources which + // specify their controller name. + // + // +kubebuilder:default={conditions: {{type: "Accepted", status: "Unknown", message: "Waiting for controller", reason: "Pending", lastTransitionTime: "1970-01-01T00:00:00Z"}}} + Status MeshStatus `json:"status,omitempty"` +} + +// MeshSpec defines the desired state of a Mesh. +type MeshSpec struct { + // ControllerName is the name of the controller that is managing this + // Mesh. The value of this field MUST be a domain prefixed path. + // + // Example: "example.com/awesome-mesh". + // + // This field is not mutable and cannot be empty. + // + // Support: Core + // + // +kubebuilder:validation:XValidation:message="Value is immutable",rule="self == oldSelf" + ControllerName string `json:"controllerName"` + + // ParametersRef is an optional reference to a resource that contains + // implementation-specific for this Mesh. If no implementation-specific + // parameters are needed, this field MUST be omitted. + // + // ParametersRef can reference a standard Kubernetes resource, i.e. + // ConfigMap, or an implementation-specific custom resource. The resource + // can be cluster-scoped or namespace-scoped. + // + // If the referent cannot be found, refers to an unsupported kind, or when + // the data within that resource is malformed, the Mesh MUST be rejected + // with the "Accepted" status condition set to "False" and an + // "InvalidParameters" reason. + // + // Support: Implementation-specific + // + // +optional + ParametersRef *ParametersReference `json:"parametersRef,omitempty"` +} + +// MeshConditionType is the type for status conditions on Mesh resources. +// This type should be used with the MeshStatus.Conditions field. +type MeshConditionType string + +// MeshConditionReason defines the set of reasons that explain why a +// particular Mesh condition type has been raised. +type MeshConditionReason string + +const ( + // This condition indicates whether the Mesh has been accepted by the + // controller requested in the `spec.controller` field. + // + // This condition defaults to Unknown, and MUST be set by a controller + // when it sees a Mesh using its controller string. The status of this + // condition MUST be set to True if the controller will accept the Mesh + // resource. Otherwise, this status MUST be set to False. If the status + // is set to False, the controller MUST set a Message and Reason as an + // explanation. + // + // Possible reasons for this condition to be true are: + // + // * "Accepted" + // + // Possible reasons for this condition to be False are: + // + // * "InvalidParameters" + // + // Controllers should prefer to use the values of MeshConditionReason + // for the corresponding Reason, where appropriate. + MeshConditionStatusAccepted MeshConditionType = "Accepted" + + // This reason is used with the "Accepted" condition when the condition is + // true. + MeshConditionReasonAccepted MeshConditionReason = "Accepted" + + // This reason is used with the "Accepted" condition when the Mesh + // was not accepted because the parametersRef field refers to + // * a namespaced resource but the Namespace field is not set, or + // * a cluster-scoped resource but the Namespace field is set, or + // * a nonexistent object, or + // * an unsupported resource or kind, or + // * an existing resource but the data within that resource is malformed. + MeshConditionReasonInvalidParameters MeshConditionReason = "InvalidParameters" + + // This reason is used with the "Accepted" condition when the + // requested controller has not yet made a decision about whether + // to accept the Mesh. It is the default Reason on a new Mesh. + MeshConditionReasonPending MeshConditionReason = "Pending" +) + +// MeshStatus is the current status for the Mesh. +type MeshStatus struct { + // Conditions is the current status from the controller for + // this Mesh. + // + // Controllers should prefer to publish conditions using values + // of MeshConditionType for the type of each Condition. + // + // +optional + // +listType=map + // +listMapKey=type + // +kubebuilder:validation:MaxItems=8 + // +kubebuilder:default={{type: "Accepted", status: "Unknown", message: "Waiting for controller", reason: "Pending", lastTransitionTime: "1970-01-01T00:00:00Z"}} + Conditions []metav1.Condition `json:"conditions,omitempty"` + + // SupportedFeatures is the set of features the Mesh support. + // It MUST be sorted in ascending alphabetical order by the Name key. + // +optional + // +listType=map + // +listMapKey=name + // + // +kubebuilder:validation:MaxItems=64 + SupportedFeatures []SupportedFeature `json:"supportedFeatures,omitempty"` +} + +// +kubebuilder:object:root=true + +// MeshList contains a list of Mesh +type MeshList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + Items []Mesh `json:"items"` +} +``` ## Conformance Details From ef7519a74602d2fdfccb075b01797317eb3f805d Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 17:21:22 -0400 Subject: [PATCH 12/20] Drop comment that was breaking rendering? Signed-off-by: Flynn --- geps/gep-3949/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index da2be602b3..124067c703 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -301,7 +301,7 @@ type Mesh struct { // Implementations MUST populate status on all Mesh resources which // specify their controller name. // - // +kubebuilder:default={conditions: {{type: "Accepted", status: "Unknown", message: "Waiting for controller", reason: "Pending", lastTransitionTime: "1970-01-01T00:00:00Z"}}} + // Defaults to Accepted condition with status Unknown and reason Pending. Status MeshStatus `json:"status,omitempty"` } From ef8255012808aaddc6999ef553ed8e43002b1368 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 17:21:50 -0400 Subject: [PATCH 13/20] Tabs -> spaces Signed-off-by: Flynn --- geps/gep-3949/index.md | 192 ++++++++++++++++++++--------------------- 1 file changed, 96 insertions(+), 96 deletions(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 124067c703..6451d4d533 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -290,52 +290,52 @@ is a significant barrier to mesh adoption. ```go // Mesh is a Cluster level resource. type Mesh struct { - metav1.TypeMeta `json:",inline"` - metav1.ObjectMeta `json:"metadata,omitempty"` - - // Spec defines the desired state of Mesh. - Spec MeshSpec `json:"spec"` - - // Status defines the current state of Mesh. - // - // Implementations MUST populate status on all Mesh resources which - // specify their controller name. - // - // Defaults to Accepted condition with status Unknown and reason Pending. - Status MeshStatus `json:"status,omitempty"` + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + // Spec defines the desired state of Mesh. + Spec MeshSpec `json:"spec"` + + // Status defines the current state of Mesh. + // + // Implementations MUST populate status on all Mesh resources which + // specify their controller name. + // + // Defaults to Accepted condition with status Unknown and reason Pending. + Status MeshStatus `json:"status,omitempty"` } // MeshSpec defines the desired state of a Mesh. type MeshSpec struct { - // ControllerName is the name of the controller that is managing this - // Mesh. The value of this field MUST be a domain prefixed path. - // - // Example: "example.com/awesome-mesh". - // - // This field is not mutable and cannot be empty. - // - // Support: Core - // - // +kubebuilder:validation:XValidation:message="Value is immutable",rule="self == oldSelf" - ControllerName string `json:"controllerName"` - - // ParametersRef is an optional reference to a resource that contains + // ControllerName is the name of the controller that is managing this + // Mesh. The value of this field MUST be a domain prefixed path. + // + // Example: "example.com/awesome-mesh". + // + // This field is not mutable and cannot be empty. + // + // Support: Core + // + // +kubebuilder:validation:XValidation:message="Value is immutable",rule="self == oldSelf" + ControllerName string `json:"controllerName"` + + // ParametersRef is an optional reference to a resource that contains // implementation-specific for this Mesh. If no implementation-specific // parameters are needed, this field MUST be omitted. - // - // ParametersRef can reference a standard Kubernetes resource, i.e. + // + // ParametersRef can reference a standard Kubernetes resource, i.e. // ConfigMap, or an implementation-specific custom resource. The resource // can be cluster-scoped or namespace-scoped. - // - // If the referent cannot be found, refers to an unsupported kind, or when - // the data within that resource is malformed, the Mesh MUST be rejected + // + // If the referent cannot be found, refers to an unsupported kind, or when + // the data within that resource is malformed, the Mesh MUST be rejected // with the "Accepted" status condition set to "False" and an - // "InvalidParameters" reason. - // - // Support: Implementation-specific - // - // +optional - ParametersRef *ParametersReference `json:"parametersRef,omitempty"` + // "InvalidParameters" reason. + // + // Support: Implementation-specific + // + // +optional + ParametersRef *ParametersReference `json:"parametersRef,omitempty"` } // MeshConditionType is the type for status conditions on Mesh resources. @@ -347,79 +347,79 @@ type MeshConditionType string type MeshConditionReason string const ( - // This condition indicates whether the Mesh has been accepted by the - // controller requested in the `spec.controller` field. - // - // This condition defaults to Unknown, and MUST be set by a controller + // This condition indicates whether the Mesh has been accepted by the + // controller requested in the `spec.controller` field. + // + // This condition defaults to Unknown, and MUST be set by a controller // when it sees a Mesh using its controller string. The status of this - // condition MUST be set to True if the controller will accept the Mesh + // condition MUST be set to True if the controller will accept the Mesh // resource. Otherwise, this status MUST be set to False. If the status // is set to False, the controller MUST set a Message and Reason as an // explanation. - // - // Possible reasons for this condition to be true are: - // - // * "Accepted" - // - // Possible reasons for this condition to be False are: - // - // * "InvalidParameters" - // - // Controllers should prefer to use the values of MeshConditionReason - // for the corresponding Reason, where appropriate. - MeshConditionStatusAccepted MeshConditionType = "Accepted" - - // This reason is used with the "Accepted" condition when the condition is - // true. - MeshConditionReasonAccepted MeshConditionReason = "Accepted" - - // This reason is used with the "Accepted" condition when the Mesh - // was not accepted because the parametersRef field refers to - // * a namespaced resource but the Namespace field is not set, or - // * a cluster-scoped resource but the Namespace field is set, or - // * a nonexistent object, or - // * an unsupported resource or kind, or - // * an existing resource but the data within that resource is malformed. - MeshConditionReasonInvalidParameters MeshConditionReason = "InvalidParameters" - - // This reason is used with the "Accepted" condition when the - // requested controller has not yet made a decision about whether - // to accept the Mesh. It is the default Reason on a new Mesh. - MeshConditionReasonPending MeshConditionReason = "Pending" + // + // Possible reasons for this condition to be true are: + // + // * "Accepted" + // + // Possible reasons for this condition to be False are: + // + // * "InvalidParameters" + // + // Controllers should prefer to use the values of MeshConditionReason + // for the corresponding Reason, where appropriate. + MeshConditionStatusAccepted MeshConditionType = "Accepted" + + // This reason is used with the "Accepted" condition when the condition is + // true. + MeshConditionReasonAccepted MeshConditionReason = "Accepted" + + // This reason is used with the "Accepted" condition when the Mesh + // was not accepted because the parametersRef field refers to + // * a namespaced resource but the Namespace field is not set, or + // * a cluster-scoped resource but the Namespace field is set, or + // * a nonexistent object, or + // * an unsupported resource or kind, or + // * an existing resource but the data within that resource is malformed. + MeshConditionReasonInvalidParameters MeshConditionReason = "InvalidParameters" + + // This reason is used with the "Accepted" condition when the + // requested controller has not yet made a decision about whether + // to accept the Mesh. It is the default Reason on a new Mesh. + MeshConditionReasonPending MeshConditionReason = "Pending" ) // MeshStatus is the current status for the Mesh. type MeshStatus struct { - // Conditions is the current status from the controller for - // this Mesh. - // - // Controllers should prefer to publish conditions using values - // of MeshConditionType for the type of each Condition. - // - // +optional - // +listType=map - // +listMapKey=type - // +kubebuilder:validation:MaxItems=8 - // +kubebuilder:default={{type: "Accepted", status: "Unknown", message: "Waiting for controller", reason: "Pending", lastTransitionTime: "1970-01-01T00:00:00Z"}} - Conditions []metav1.Condition `json:"conditions,omitempty"` - - // SupportedFeatures is the set of features the Mesh support. - // It MUST be sorted in ascending alphabetical order by the Name key. - // +optional - // +listType=map - // +listMapKey=name - // - // +kubebuilder:validation:MaxItems=64 - SupportedFeatures []SupportedFeature `json:"supportedFeatures,omitempty"` + // Conditions is the current status from the controller for + // this Mesh. + // + // Controllers should prefer to publish conditions using values + // of MeshConditionType for the type of each Condition. + // + // +optional + // +listType=map + // +listMapKey=type + // +kubebuilder:validation:MaxItems=8 + // +kubebuilder:default={{type: "Accepted", status: "Unknown", message: "Waiting for controller", reason: "Pending", lastTransitionTime: "1970-01-01T00:00:00Z"}} + Conditions []metav1.Condition `json:"conditions,omitempty"` + + // SupportedFeatures is the set of features the Mesh support. + // It MUST be sorted in ascending alphabetical order by the Name key. + // +optional + // +listType=map + // +listMapKey=name + // + // +kubebuilder:validation:MaxItems=64 + SupportedFeatures []SupportedFeature `json:"supportedFeatures,omitempty"` } // +kubebuilder:object:root=true // MeshList contains a list of Mesh type MeshList struct { - metav1.TypeMeta `json:",inline"` - metav1.ListMeta `json:"metadata,omitempty"` - Items []Mesh `json:"items"` + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + Items []Mesh `json:"items"` } ``` From 9690eeebb5710cd8fc8153a2e70c4eef20040b20 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 17:28:14 -0400 Subject: [PATCH 14/20] Implementable, not Provisional Signed-off-by: Flynn --- geps/gep-3949/index.md | 2 +- geps/gep-3949/metadata.yaml | 2 +- mkdocs.yml | 3 +-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 6451d4d533..ea0a5999ac 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -1,7 +1,7 @@ # GEP-3949: Mesh Resource * Issue: [#3949](https://github.com/kubernetes-sigs/gateway-api/issues/3949) -* Status: Provisional +* Status: Implementable (See [status definitions](../overview.md#gep-states).) diff --git a/geps/gep-3949/metadata.yaml b/geps/gep-3949/metadata.yaml index d4696a94bf..de9c3639e7 100644 --- a/geps/gep-3949/metadata.yaml +++ b/geps/gep-3949/metadata.yaml @@ -2,7 +2,7 @@ apiVersion: internal.gateway.networking.k8s.io/v1alpha1 kind: GEPDetails number: 3949 name: Mesh Resource -status: Provisional +status: Implementable # Any authors who contribute to the GEP in any way should be listed here using # their GitHub handle. authors: diff --git a/mkdocs.yml b/mkdocs.yml index 99e9b4012d..18393ce4c6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -132,11 +132,10 @@ nav: - geps/gep-2648/index.md - geps/gep-3779/index.md - geps/gep-3792/index.md - - geps/gep-3949/index.md - Implementable: - geps/gep-91/index.md - geps/gep-3567/index.md - - geps/gep-3793/index.md + - geps/gep-3949/index.md - Experimental: - geps/gep-1619/index.md - geps/gep-1713/index.md From d35977ca8aae9f70a89217ccc0f21db5bcff33c7 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 17:33:10 -0400 Subject: [PATCH 15/20] Fix the other place a kubebuilder default was breaking rendering Signed-off-by: Flynn --- geps/gep-3949/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index ea0a5999ac..2213b7a794 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -400,7 +400,7 @@ type MeshStatus struct { // +listType=map // +listMapKey=type // +kubebuilder:validation:MaxItems=8 - // +kubebuilder:default={{type: "Accepted", status: "Unknown", message: "Waiting for controller", reason: "Pending", lastTransitionTime: "1970-01-01T00:00:00Z"}} + // Defaults to Accepted condition with status Unknown and reason Pending. Conditions []metav1.Condition `json:"conditions,omitempty"` // SupportedFeatures is the set of features the Mesh support. From 623558506066552b8ddc0332a482d7a729688731 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 17:35:48 -0400 Subject: [PATCH 16/20] Tweak Signed-off-by: Flynn --- geps/gep-3949/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 2213b7a794..9abbd0bb9e 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -202,7 +202,7 @@ spec: controllerName: one-mesh.example.com/one-mesh status: conditions: - # MUST include Accepted and Ready conditions if the Mesh resource is active. + # MUST include Accepted condition if the Mesh resource is active. - type: Accepted # Becomes true when the controller accepts the Mesh resource status: "True" reason: Accepted From 2d1946ebfa55686753416eeaeca78aa34230f449 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 25 Jul 2025 17:40:26 -0400 Subject: [PATCH 17/20] Formatting fixes Signed-off-by: Flynn --- geps/gep-3792/index.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/geps/gep-3792/index.md b/geps/gep-3792/index.md index 802d729c97..2441074466 100644 --- a/geps/gep-3792/index.md +++ b/geps/gep-3792/index.md @@ -42,10 +42,10 @@ In this GEP: wrangling the mTLS meshes! Supporting non-mTLS meshes will be a separate GEP. - **Note:** It's important to separate mTLS and HTTPS here. Saying that the - mTLS meshes use mTLS for secure communication does not preclude them from - using custom protocols on top of mTLS, and certainly does not mean that - they must use only HTTPS. + **Note:** It's important to separate mTLS and HTTPS here. Saying that the + mTLS meshes use mTLS for secure communication does not preclude them from + using custom protocols on top of mTLS, and certainly does not mean that + they must use only HTTPS. 3. _Authentication_ is the act of verifying the identity of some _principal_; what the principal actually is depends on context. For this GEP we will @@ -56,21 +56,21 @@ In this GEP: can't trust what the OCG says about the user unless the OCG successfully authenticates itself as a workload. - **Note:** A single workload will have only one identity, but in practice we - often see a single identity being used for multiple workloads (both because - multiple replicas of a single workload need to share the same identity, and - because some low-security workloads may be grouped together under a single - identity). + **Note:** A single workload will have only one identity, but in practice we + often see a single identity being used for multiple workloads (both because + multiple replicas of a single workload need to share the same identity, and + because some low-security workloads may be grouped together under a single + identity). 4. Finally, we'll distinguish between _inbound_ and _outbound_ behaviors. - Inbound behaviors are those that are applied to a request _arriving_ at a - given workload. Authorization and rate limiting are canonical examples - of inbound behaviors. + Inbound behaviors are those that are applied to a request _arriving_ at a + given workload. Authorization and rate limiting are canonical examples + of inbound behaviors. - Outbound behaviors are those that are applied to a request _leaving_ a - given workload. Load balancing, retries, and circuit breakers are canonical - examples of outbound behaviors. + Outbound behaviors are those that are applied to a request _leaving_ a + given workload. Load balancing, retries, and circuit breakers are canonical + examples of outbound behaviors. ## Goals @@ -197,7 +197,7 @@ is sent. (For example, Linkerd requires the originating proxy to send transport metadata right after the TLS handshake, and it will reject a connection which doesn't do that correctly.) -#### 4. The Discovery Problem +#### 3. The Discovery Problem When using a mesh, not every workload in the cluster is required to be meshed (for example, it's fairly common to have some namespaces meshed and other From 0bc0a2bc11f2013a0fa749dd00c01bd46a4320b1 Mon Sep 17 00:00:00 2001 From: Flynn Date: Mon, 28 Jul 2025 23:17:50 -0400 Subject: [PATCH 18/20] Review feedback. Signed-off-by: Flynn --- geps/gep-3949/index.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 9abbd0bb9e..09fe72cb32 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -265,9 +265,10 @@ the mesh will not be able to publish support features, which may lead to assumptions that the mesh does not support any features. -Meshes SHOULD provide a default Mesh resource +Meshes SHOULD provide an easy way +for [Chihiro] or [Ian] to obtain a default Mesh resource when the mesh is installed, -so that neither [Chihiro] or [Ian] need to know +so that they do not need to know the `controllerName` before installing the mesh. (For example, @@ -276,14 +277,8 @@ a default Mesh resource with only the `controllerName` field set, with the assumption that [Chihiro] or [Ian] will later edit the resource.) - -This is in contrast to the GatewayClass resource, -which must be explicitly created by [Ian] -when the Gateway controller is installed. -This is primarily because GAMMA meshes -have historically not had a Mesh resource, -so requiring [Chihiro] or [Ian] to create one by hand -is a significant barrier to mesh adoption. +Any such mechanism for obtaining a default Mesh resource +MUST NOT unconditionally overwrite an existing Mesh resource, though. ### API Type Definitions From 0d3f1ed6cdeaf9fa248e5bd61dfc98b7c9edc684 Mon Sep 17 00:00:00 2001 From: Flynn Date: Wed, 30 Jul 2025 00:13:15 -0400 Subject: [PATCH 19/20] Review feedback Signed-off-by: Flynn --- geps/gep-3949/index.md | 206 +++++++++++++++++++++++++++++------------ 1 file changed, 146 insertions(+), 60 deletions(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 09fe72cb32..2d89e68876 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -46,6 +46,13 @@ we will need ways to show what features a given mesh implementation supports and represent mesh-wide configuration. +This GEP therefore defines a Mesh resource +which represents a running instance of a service mesh, +allowing [Chihiro] and [Ian] to +supply mesh-wide configuration, +and allowing the mesh implementation +to indicate what features it supports. + Unlike Gateways, we do not expect multiple instances of meshes to be instantiated in a single cluster. @@ -59,15 +66,11 @@ instead, we will simply define a Mesh resource. mesh-wide configuration and feature discovery. -## Non-Goals - -- Support multiple instances of a mesh - in a single cluster at the same time. +- Avoid making it more difficult for [Chihiro] and [Ian] + to adopt a mesh + (or to experiment with adopting a mesh). - At some point, we may choose to - change this goal, - but it is definitely out of scope - for this GEP. +## Non-Goals - Support meshes interoperating with each other. @@ -89,7 +92,7 @@ instead, we will simply define a Mesh resource. GAMMA has always taken the position that multiple meshes running simultaneously in a single cluster - is not a goal, but neither is it forbidden. + is not an explicit goal, but neither is it forbidden. This GEP does not change that position. ## API @@ -142,6 +145,14 @@ spec: that is responsible for this Mesh resource. + A given mesh implementation will define its controller name + at build time. + It MUST be a domain-prefixed path, + for example `linkerd.io/linkerd` or `istio.io/istio`. + It MUST NOT be empty. + It MAY be configurable at runtime, + although this is not expected to be common. + Although we expect that there will be only one mesh @@ -155,19 +166,6 @@ spec: a `controllerName` field that matches its own name. - If a MeshClass resource - is later defined, - the Mesh resource - will gain a - `meshClassName` field, - the `controllerName` field - will be deprecated, - and a - Mesh resource - that includes - both `controllerName` and `meshClassName` - will be invalid. - - The `parametersRef` field is analogous to the `parametersRef` field @@ -217,24 +215,24 @@ status: ... ``` -Although it is -explicitly -not a goal of this GEP -to support multiple meshes +Although GAMMA does not fully support multiple meshes running in the same cluster at the same time, meshes still MUST provide human-readable information in the `Accepted` condition about which mesh instance -has claimed a given Mesh resource, -and SHOULD provide human-readable -information in the `Ready` condition, -in support of future expansion work. +has claimed a given Mesh resource. This information is meant to be used by [Chihiro] and [Ian] as confirmation that the mesh instance is doing what they expect it to do. +Mesh implementations MUST +reject Mesh resources in which `spec.parametersRef` +references a resource that does not exist +or is not supported by the mesh implementation, +setting the `Reason` to `InvalidParameters`. + The mesh implementation MUST set `status.SupportedFeatures` to indicate which features @@ -242,43 +240,121 @@ the mesh supports. ### Life Cycle -A mesh implementation MUST NOT create a Mesh resource -if one does not already exist. - -If a mesh implementation does not find a Mesh resource -with a matching `controllerName` at startup: - -- It SHOULD warn the user - (in whatever way is appropriate for the mesh) - that the Mesh resource is missing. +One of the explicit goals of this GEP +is to avoid making it more difficult for [Chihiro] and [Ian] +to adopt a mesh. +In turn, this implies that we MUST NOT require [Chihiro] or [Ian] +to manually create a Mesh resource in order to use a mesh. + +The simplest way to achieve this is +for the mesh implementation to create a Mesh resource +when it starts up, +if one does not already exist +with a matching `controllerName` field. +This raises questions around +what the Mesh resource should be named, +and how the mesh implementation can avoid overwriting +any modifications [Chihiro] or [Ian] make +to the Mesh resource after it is created. + +To manage these concerns +while still minimizing added friction, +mesh implementations MUST define a default `metadata.name` +for the Mesh resource they will look for, +and SHOULD allow overriding this name at install time. +This default name SHOULD be +an obvious derivative of the mesh implementation name, +such as "linkerd" or "istio"; +its purpose is to make it easy for [Chihiro] and [Ian] +to find the Mesh resource +while also allowing for the possibility +that there will need to be more than one +Mesh resource in a cluster. + +At startup, then: + +- The mesh implementation MUST look for a Mesh resource + with the expected `metadata.name` field. + +- If no Mesh resource exists with the expected `metadata.name`, + the implementation MUST create a Mesh resource + with the expected `metadata.name` + and `spec.controllerName` fields. + + - The mesh MUST NOT set any other fields + in the `spec` of the Mesh resource + that it creates. + + In particular, the mesh MUST NOT set `parametersRef` + when it creates the Mesh resource. + +- Otherwise + (a Mesh resource already exists with the expected `metadata.name`), + the implementation MUST NOT modify the `spec` + of that Mesh resource + in **any way**. + Instead, it MUST check the `spec.controllerName` field: + + - If the Mesh resource has a matching `spec.controllerName` field: + + - The implementation MUST set the `status` stanza + of the Mesh resource + to indicate whether or not it has accepted the Mesh resource + and, if accepted, what features the mesh supports. + + - Otherwise + (the Mesh resource does not have + a matching `spec.controllerName` field): + + - The implementation MUST NOT modify the Mesh resource + in any way, + and it SHOULD warn the user + (in whatever way is appropriate for the mesh) + that there is a mismatch in the Mesh resource + +```mermaid +flowchart TD + Start{Does a Mesh resource with a matching name exist?} + Start -->|Yes| Match + Start -->|No| NoMatch + Match{Does the controllerName also match?} + Match -->|No| WarnNoModify + Match -->|Yes| UpdateStat + NoMatch[Create a new Mesh resource] --> CheckCreate + CheckCreate{Did creation succeed?} + CheckCreate -->|Yes| UpdateStat + CheckCreate -->|No| Warn + UpdateStat[Update status] + Warn[Warn] + WarnNoModify[Warn and don't modify] +``` -- It MUST act as if a Mesh resource was found - with an empty `spec` - (other than the `controllerName` field). - Optional configuration MUST remain in its default state, - and features that require a Mesh resource - (such as OCG support) - MUST NOT be enabled. +If, at the end of this process, +there is no Mesh resource with both +a matching `metadata.name` and +a matching `spec.controllerName`, +the implementation MUST act as if +a Mesh resource was found with a empty `spec` +(other than the `controllerName` field). +Optional configuration MUST remain in its default state, +and features that require a Mesh resource +(such as OCG support) +MUST NOT be enabled. Obviously, if no matching Mesh resource exists, the mesh will not be able to publish support features, which may lead to assumptions that the mesh does not support any features. -Meshes SHOULD provide an easy way -for [Chihiro] or [Ian] to obtain a default Mesh resource -when the mesh is installed, -so that they do not need to know -the `controllerName` -before installing the mesh. -(For example, -a mesh's Helm chart might include -a default Mesh resource -with only the `controllerName` field set, -with the assumption -that [Chihiro] or [Ian] will later edit the resource.) -Any such mechanism for obtaining a default Mesh resource -MUST NOT unconditionally overwrite an existing Mesh resource, though. +The mesh implementation MUST NOT, +under any circumstances, +modify the `spec` of a Mesh resource +other than by creating a new Mesh resource +when one does not exist. + +Mesh implementations SHOULD +respond to changes in the Mesh resource +without requiring the mesh to be restarted. ### API Type Definitions @@ -449,6 +525,16 @@ there was no clear need for both, and that a Mesh resource better served the use cases. +If a MeshClass resource +is later defined, +the Mesh resource +will need to be updated. +One potential approach to such an update might be: + +- Add a `meshClassName` field to the Mesh resource; +- Deprecate the `controllerName` field; and +- Define that a Mesh resource with both fields set is invalid. + ## References TBA. From 27fd0ef9fe21b741321c5a6482d919e46da3a3d5 Mon Sep 17 00:00:00 2001 From: Flynn Date: Wed, 30 Jul 2025 00:16:16 -0400 Subject: [PATCH 20/20] :man_facepalming: Cluster-scoped resources don't have namespaces. Signed-off-by: Flynn --- geps/gep-3949/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md index 2d89e68876..26f5f2056c 100644 --- a/geps/gep-3949/index.md +++ b/geps/gep-3949/index.md @@ -195,7 +195,6 @@ apiVersion: gateway.networking.x-k8s.io/v1alpha1 kind: XMesh metadata: name: one-mesh-to-mesh-them-all - namespace: mesh-namespace spec: controllerName: one-mesh.example.com/one-mesh status: