[GEP-1911] Update BackendRef with GEP details (#2444)

* just mention service protocol field

* add backend protocol GEP details to BackendRef

* mark backend protocol section experimental

* fix regexp generation

* fix nits

* relax requirements to SHOULD and only drop language around Endpoints/EndpointSlices

* Drop 'Gateway' in some clauses so that appProtocol can apply to mesh use cases

* Update godoc so it appears in the CRD generated docs

* clarify multiplexing clause

* drop reference to GEP - adjust requirement level

* drop multiplexing backend clause

Author: dprotaso

apis/v1alpha2/grpcroute_types.go

@@ -549,6 +549,31 @@ type GRPCRouteFilter struct {
 }
 
 // GRPCBackendRef defines how a GRPCRoute forwards a gRPC request.
+//
+// Note that when a namespace different than the local namespace is specified, a
+// ReferenceGrant object is required in the referent namespace to allow that
+// namespace's owner to accept the reference. See the ReferenceGrant
+// documentation for details.
+//
+// <gateway:experimental:description>
+//
+// When the BackendRef points to a Kubernetes Service, implementations SHOULD honor the
+// appProtocol field if it is set for the target Service Port.
+//
+// Implementations supporting appProtocol SHOULD recognize the Kubernetes Standard Application Protocols
+// defined in [KEP-3726].
+//
+// If a Service appProtocol isn't specified an implementation MAY infer the backend
+// protocol through its own means. Implementations MAY infer the protocol from the
+// Route type referring to the backend Service.
+//
+// If a Route is not able to send traffic to the backend using the specified protocol then
+// the backend is considered invalid. Implementations MUST set ResolvedRefs condition to
+// False with the "UnsupportedProtocol".
+//
+// </gateway:experimental:description>
+//
+// [KEP-3726]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-network/3726-standard-application-protocols
 type GRPCBackendRef struct {
 	// BackendRef is a reference to a backend to forward matched requests to.
 	//

apis/v1beta1/httproute_types.go

@@ -1110,7 +1110,32 @@ type HTTPRequestMirrorFilter struct {
 	BackendRef BackendObjectReference `json:"backendRef"`
 }
 
-// HTTPBackendRef defines how a HTTPRoute should forward an HTTP request.
+// HTTPBackendRef defines how a HTTPRoute forwards a HTTP request.
+//
+// Note that when a namespace different than the local namespace is specified, a
+// ReferenceGrant object is required in the referent namespace to allow that
+// namespace's owner to accept the reference. See the ReferenceGrant
+// documentation for details.
+//
+// <gateway:experimental:description>
+//
+// When the BackendRef points to a Kubernetes Service, implementations SHOULD honor the
+// appProtocol field if it is set for the target Service Port.
+//
+// Implementations supporting appProtocol SHOULD recognize the Kubernetes Standard Application Protocols
+// defined in [KEP-3726].
+//
+// If a Service appProtocol isn't specified an implementation MAY infer the backend
+// protocol through its own means. Implementations MAY infer the protocol from the
+// Route type referring to the backend Service.
+//
+// If a Route is not able to send traffic to the backend using the specified protocol then
+// the backend is considered invalid. Implementations MUST set ResolvedRefs condition to
+// False with the "UnsupportedProtocol".
+//
+// </gateway:experimental:description>
+//
+// [KEP-3726]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-network/3726-standard-application-protocols
 type HTTPBackendRef struct {
 	// BackendRef is a reference to a backend to forward matched requests to.
 	//

apis/v1beta1/shared_types.go

@@ -243,6 +243,26 @@ type PortNumber int32
 // ReferenceGrant object is required in the referent namespace to allow that
 // namespace's owner to accept the reference. See the ReferenceGrant
 // documentation for details.
+//
+// <gateway:experimental:description>
+//
+// When the BackendRef points to a Kubernetes Service, implementations SHOULD honor the
+// appProtocol field if it is set for the target Service Port.
+//
+// Implementations supporting appProtocol SHOULD recognize the Kubernetes Standard Application Protocols
+// defined in [KEP-3726].
+//
+// If a Service appProtocol isn't specified an implementation MAY infer the backend
+// protocol through its own means. Implementations MAY infer the protocol from the
+// Route type referring to the backend Service.
+//
+// If a Route is not able to send traffic to the backend using the specified protocol then
+// the backend is considered invalid. Implementations MUST set ResolvedRefs condition to
+// False with the "UnsupportedProtocol".
+//
+// </gateway:experimental:description>
+//
+// [KEP-3726]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-network/3726-standard-application-protocols
 type BackendRef struct {
 	// BackendObjectReference references a Kubernetes object.
 	BackendObjectReference `json:",inline"`
@@ -342,6 +362,7 @@ const (
 	// * "RefNotPermitted"
 	// * "InvalidKind"
 	// * "BackendNotFound"
+	// * "UnsupportedProtocol"
 	//
 	// Controllers may raise this condition with other reasons,
 	// but should prefer to use the reasons listed above to improve
@@ -366,6 +387,11 @@ const (
 	// This reason is used with the "ResolvedRefs" condition when one of the
 	// Route's rules has a reference to a resource that does not exist.
 	RouteReasonBackendNotFound RouteConditionReason = "BackendNotFound"
+
+	// This reason is used with the "ResolvedRefs" condition when one of the
+	// Route's rules has a reference to a resource with an app protocol that
+	// is not supported by this implementation.
+	RouteReasonUnsupportedProtocol RouteConditionReason = "UnsupportedProtocol"
 )
 
 // RouteParentStatus describes the status of a route with respect to an