apis: document ParentRef functionality for GAMMA

apis/v1alpha2/referencegrant_types.go

@@ -36,8 +36,12 @@ import (
 // Additional Reference Grants can be used to add to the set of trusted
 // sources of inbound references for the namespace they are defined within.
 //
-// All cross-namespace references in Gateway API (with the exception of cross-namespace
-// Gateway-route attachment) require a ReferenceGrant.
+// A ReferenceGrant is required for all cross-namespace references in Gateway API
+// (with the exception of cross-namespace Route-Gateway attachment, which is
+// governed by the AllowedRoutes configuration on the Gateway, and cross-namespace
+// Service ParentRefs on a "consumer" mesh Route, which defines routing rules
+// applicable only to workloads in the Route namespace). ReferenceGrants allowing
+// a reference from a Route to a Service are only applicable to BackendRefs.
 //
 // ReferenceGrant is a form of runtime verification allowing users to assert
 // which cross-namespace object references are permitted. Implementations that

apis/v1beta1/shared_types.go

@@ -21,9 +21,14 @@ import (
 )
 
 // ParentReference identifies an API object (usually a Gateway) that can be considered
-// a parent of this resource (usually a route). The only kind of parent resource
-// with "Core" support is Gateway. This API may be extended in the future to
-// support additional kinds of parent resources, such as HTTPRoute.
+// a parent of this resource (usually a route). There are two kinds of parent resources
+// with "Core" support:
+//
+// * Gateway (Gateway conformance profile)
+// * Service (Mesh conformance profile)
+//
+// This API may be extended in the future to support additional kinds of parent
+// resources.
 //
 // The API object must be valid in the cluster; the Group and Kind must
 // be registered in the cluster for this reference to be valid.
@@ -41,9 +46,12 @@ type ParentReference struct {
 
 	// Kind is kind of the referent.
 	//
-	// Support: Core (Gateway)
+	// There are two kinds of parent resources with "Core" support:
+	//
+	// * Gateway (Gateway conformance profile)
+	// * Service (Mesh conformance profile)
 	//
-	// Support: Implementation-specific (Other Resources)
+	// Support for other resources is Implementation-Specific.
 	//
 	// +kubebuilder:default=Gateway
 	// +optional
@@ -58,6 +66,16 @@ type ParentReference struct {
 	// Gateway has the AllowedRoutes field, and ReferenceGrant provides a
 	// generic way to enable any other kind of cross-namespace reference.
 	//
+	// ParentRefs from a Route to a Service in the same namespace are "producer"
+	// routes, which apply default routing rules to inbound connections from
+	// any namespace to the Service.
+	//
+	// ParentRefs from a Route to a Service in a different namespace are
+	// "consumer" routes, and these routing rules are only applied to outbound
+	// connections originating from the same namespace as the Route, for which
+	// the intended destination of the connections are a Service targeted as a
+	// ParentRef of the Route.
+	//
 	// Support: Core
 	//
 	// +optional
@@ -104,6 +122,10 @@ type ParentReference struct {
 	// and SectionName are specified, the name and port of the selected listener
 	// must match both specified values.
 	//
+	// When the parent resource is a Service, this targets a specific port in the
+	// Service spec. When both Port (experimental) and SectionName are specified,
+	// the name and port of the selected port 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.
@@ -130,15 +152,25 @@ type CommonRouteSpec struct {
 	// 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.
+	// namespace. For Services, that means the Service must either be in the same
+	// namespace for a "producer" route, or the mesh implementation must support
+	// and allow "consumer" routes for the referenced Service. ReferenceGrant is
+	// not applicable for governing ParentRefs to Services - it is not possible to
+	// create a "producer" route for a Service in a different namespace from the
+	// Route.
 	//
-	// The only kind of parent resource with "Core" support is Gateway. This API
-	// may be extended in the future to support additional kinds of parent
-	// resources such as one of the route kinds.
+	// There are two kinds of parent resources with "Core" support:
+	//
+	// * Gateway (Gateway conformance profile)
+	// * Service (Mesh conformance profile)
+	//
+	// This API may be extended in the future to support additional kinds of parent
+	// resources.
 	//
 	// 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.
+	// resource, such as two separate Listeners on the same Gateway or two separate
+	// ports on the same Service.
 	//
 	// It is possible to separately reference multiple distinct objects that may
 	// be collapsed by an implementation. For example, some implementations may
@@ -150,7 +182,17 @@ type CommonRouteSpec struct {
 	// rules. Cross-namespace references are only valid if they are explicitly
 	// allowed by something in the namespace they are referring to. For example,
 	// Gateway has the AllowedRoutes field, and ReferenceGrant provides a
-	// generic way to enable any other kind of cross-namespace reference.
+	// generic way to enable other kinds of cross-namespace reference.
+	//
+	// ParentRefs from a Route to a Service in the same namespace are "producer"
+	// routes, which apply default routing rules to inbound connections from
+	// any namespace to the Service.
+	//
+	// ParentRefs from a Route to a Service in a different namespace are
+	// "consumer" routes, and these routing rules are only applied to outbound
+	// connections originating from the same namespace as the Route, for which
+	// the intended destination of the connections are a Service targeted as a
+	// ParentRef of the Route.
 	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=32