WIP: talk about protocol selection

Signed-off-by: Flynn <[email protected]>

Author: kflynn

geps/gep-3792/index.md

@@ -264,12 +264,72 @@ There are three important aspects to the OCG API:
 The API must also solve all four of the problems listed above, so we'll start
 with an overview of the solutions before diving into the API details.
 
+### The Mesh Resource
+
+Since quite a few things about OCG support require mesh-wide configuration and
+status, we will define a new Mesh resource, analogous to the existing Gateway
+resource. We will NOT define a MeshClass resource at this point, though we
+will not rule it out for future work.
+
+A future GEP will cover the Mesh resource in more detail, but for now the Mesh
+resource is fairly straightforward:
+
+```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   # required, must be domain-prefixed
+  parametersRef:
+    # optional ParametersReference
+    ...
+  ocg:
+    # All OCG-related configuration goes here, see below
+    ...
+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
+    ...
+```
+
+Note that the `spec.controllerName` field is required, and must be a
+domain-prefixed name that identifies the mesh implementation. If a MeshClass
+resource is later defined, the intention is that 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 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.
+
 ### Solving the Trust Problem
 
 The trust problem is that the OCG and the mesh need to be able to trust each
-other. The simplest solution to this problem is to add a _trust bundle_ to the
-Gateway resource, and to create a Mesh resource which will also have a trust
-bundle:
+other. The simplest solution to this problem is to include a _trust bundle_ in
+both the Gateway resource and the Mesh resource:
 
 - The trust bundle in the Gateway resource will define the CA certificate(s)
   that the OCG should trust when communicating with meshed workloads in the
@@ -308,6 +368,15 @@ workloads, and that the identities of both peers MUST be verified:
 - The mesh MUST verify the OCG's certificate against the trust bundle
   provided to the mesh.
 
+Beyond that, the OCG needs a way to indicate to the mesh that it intends to
+participate in the mesh. Since multiple meshes may have fundamentally
+different approaches, we will add a `protocol` field to the Gateway's mesh
+configuration and to the Mesh's OCG configuration, to allow configuring the
+OCG and the mesh with a common mechanism.
+
+The only defined value for this field is currently `ocg-basic-alpn/v1`. When
+using this protocol:
+
 - The OCG MUST send the `ocg.gateway.networking.k8s.io/v1` ALPN protocol
   during mTLS negotiation. The mesh MUST interpret this ALPN selection as a
   signal that the OCG intends to participate in the mesh.