mesh: update various protobuf comments for mesh types (#18993)

proto-public/pbmesh/v2beta1/common.proto

@@ -13,52 +13,21 @@ message ParentReference {
   // For north/south it should point to a gateway (TBD)
   hashicorp.consul.resource.Reference ref = 1;
 
-  // Port is the network port this Route targets. It can be interpreted
-  // differently based on the type of parent resource.
+  // For east/west this is the name of the Consul Service port to direct traffic to
+  // or empty to imply all.
   //
-  // When the parent resource is a Gateway, this targets all listeners
-  // listening on the specified port that also support this kind of Route(and
-  // select this Route). It’s not recommended to set Port unless the networking
-  // behaviors specified in a Route must apply to a specific port as opposed to
-  // a listener(s) whose port(s) may be changed. When both Port and SectionName
-  // are specified, the name and port of the selected listener must match both
-  // specified values.
-  //
-  // Implementations MAY choose to support other parent resources.
-  // Implementations supporting other types of parent resources MUST clearly
-  // document how/if Port is interpreted.
-  //
-  // For the purpose of status, an attachment is considered successful as long
-  // as the parent resource accepts it partially. For example, Gateway
-  // listeners can restrict which Routes can attach to them by Route kind,
-  // namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from
-  // the referencing Route, the Route MUST be considered successfully attached.
-  // If no Gateway listeners accept attachment from this Route, the Route MUST
-  // be considered detached from the Gateway.
-  //
-  // For east/west this is the name of the consul port.
-  // For north/south this is the stringified integer port expected by GAMMA.
-  //
-  // https://gateway-api.sigs.k8s.io/geps/gep-957/
+  // For north/south this is TBD.
   string port = 2;
 }
 
 message BackendReference {
-  // For east/west configuration, this should point to either a
-  // pbcatalog.Service or ServiceSubset.
-  //
-  // For Partition/PeerName fields likely we could map them to ServiceImports
-  // (MCS+GAMMA) when translating
+  // For east/west configuration, this should point to a pbcatalog.Service.
   hashicorp.consul.resource.Reference ref = 1;
 
-  // For east/west this is the name of the consul port.
-  string port = 2;
-
-  // NOT IN GAMMA; multi-cluster + GWapi is still unknown
+  // For east/west this is the name of the Consul Service port to direct traffic to
+  // or empty to imply using the same value as the parent ref.
   //
-  // Likely we could map this to ServiceImports (MCS+GAMMA) when translating
-  // to/from k8s.
-  //
-  // https://gateway-api.sigs.k8s.io/geps/gep-1748/
+  // For north/south this is TBD.
+  string port = 2;
   string datacenter = 3;
 }

proto-public/pbmesh/v2beta1/grpc_route.proto

@@ -20,16 +20,16 @@ import "pbresource/annotations.proto";
 message GRPCRoute {
   option (hashicorp.consul.resource.spec) = {scope: SCOPE_NAMESPACE};
 
-  // ParentRefs references the resources (usually Gateways) that a Route wants
-  // to be attached to. Note that the referenced parent resource needs to allow
-  // this for the attachment to be complete. For Gateways, that means the
-  // Gateway needs to allow attachment from Routes of this kind and namespace.
+  // ParentRefs references the resources (usually Services) that a Route wants
+  // to be attached to.
   //
   // It is invalid to reference an identical parent more than once. It is valid
-  // to reference multiple distinct sections within the same parent resource,
-  // such as 2 Listeners within a Gateway.
+  // to reference multiple distinct sections within the same parent resource.
   repeated ParentReference parent_refs = 1;
 
+  // Hostnames are the hostnames for which this GRPCRoute should respond to requests.
+  //
+  // This is only valid for north/south.
   repeated string hostnames = 2;
 
   // Rules are a list of GRPC matchers, filters and actions.
@@ -39,11 +39,31 @@ message GRPCRoute {
 message GRPCRouteRule {
   repeated GRPCRouteMatch matches = 1;
   repeated GRPCRouteFilter filters = 2;
+
+  // BackendRefs defines the backend(s) where matching requests should be sent.
+  //
+  // Failure behavior here depends on how many BackendRefs are specified and
+  // how many are invalid.
+  //
+  // If all entries in BackendRefs are invalid, and there are also no filters
+  // specified in this route rule, all traffic which matches this rule MUST
+  // receive a 500 status code.
+  //
+  // See the GRPCBackendRef definition for the rules about what makes a single
+  // GRPCBackendRef invalid.
+  //
+  // When a GRPCBackendRef is invalid, 500 status codes MUST be returned for
+  // requests that would have otherwise been routed to an invalid backend. If
+  // multiple backends are specified, and some are invalid, the proportion of
+  // requests that would otherwise have been routed to an invalid backend MUST
+  // receive a 500 status code.
+  //
+  // For example, if two backends are specified with equal weights, and one is
+  // invalid, 50 percent of traffic must receive a 500. Implementations may
+  // choose how that 50 percent is determined.
   repeated GRPCBackendRef backend_refs = 3;
 
-  // ALTERNATIVE: Timeouts defines the timeouts that can be configured for an HTTP request.
   HTTPRouteTimeouts timeouts = 4;
-  // ALTERNATIVE:
   HTTPRouteRetries retries = 5;
 }
 

proto-public/pbmesh/v2beta1/http_route.proto

@@ -19,17 +19,16 @@ import "pbresource/annotations.proto";
 message HTTPRoute {
   option (hashicorp.consul.resource.spec) = {scope: SCOPE_NAMESPACE};
 
-  // ParentRefs references the resources (usually Gateways) that a Route wants
-  // to be attached to. Note that the referenced parent resource needs to allow
-  // this for the attachment to be complete. For Gateways, that means the
-  // Gateway needs to allow attachment from Routes of this kind and namespace.
+  // ParentRefs references the resources (usually Services) that a Route wants
+  // to be attached to.
   //
   // It is invalid to reference an identical parent more than once. It is valid
-  // to reference multiple distinct sections within the same parent resource,
-  // such as 2 Listeners within a Gateway.
+  // to reference multiple distinct sections within the same parent resource.
   repeated ParentReference parent_refs = 1;
 
   // Hostnames are the hostnames for which this HTTPRoute should respond to requests.
+  //
+  // This is only valid for north/south.
   repeated string hostnames = 2;
 
   // Rules are a list of HTTP-based routing rules that this route should
@@ -40,11 +39,7 @@ message HTTPRoute {
 // HTTPRouteRule specifies the routing rules used to determine what upstream
 // service an HTTP request is routed to.
 message HTTPRouteRule {
-  // Matches specified the matching criteria used in the routing table. If a
-  // request matches the given HTTPMatch configuration, then traffic is routed
-  // to services specified in the Services field.
   repeated HTTPRouteMatch matches = 1;
-
   repeated HTTPRouteFilter filters = 2;
 
   // BackendRefs defines the backend(s) where matching requests should be sent.
@@ -70,9 +65,7 @@ message HTTPRouteRule {
   // choose how that 50 percent is determined.
   repeated HTTPBackendRef backend_refs = 3;
 
-  // ALTERNATIVE: Timeouts defines the timeouts that can be configured for an HTTP request.
   HTTPRouteTimeouts timeouts = 4;
-  // ALTERNATIVE:
   HTTPRouteRetries retries = 5;
 }
 

proto-public/pbmesh/v2beta1/tcp_route.proto

@@ -17,14 +17,11 @@ import "pbresource/annotations.proto";
 message TCPRoute {
   option (hashicorp.consul.resource.spec) = {scope: SCOPE_NAMESPACE};
 
-  // ParentRefs references the resources (usually Gateways) that a Route wants
-  // to be attached to. Note that the referenced parent resource needs to allow
-  // this for the attachment to be complete. For Gateways, that means the
-  // Gateway needs to allow attachment from Routes of this kind and namespace.
+  // ParentRefs references the resources (usually Services) that a Route wants
+  // to be attached to.
   //
   // It is invalid to reference an identical parent more than once. It is valid
-  // to reference multiple distinct sections within the same parent resource,
-  // such as 2 Listeners within a Gateway.
+  // to reference multiple distinct sections within the same parent resource.
   repeated ParentReference parent_refs = 1;
 
   // Rules are a list of TCP matchers and actions.