Update ParentRef wording

apis/v1alpha2/shared_types.go

@@ -25,6 +25,12 @@ import (
 // with "Core" support is Gateway. This API may be extended in the future to
 // support additional kinds of parent resources, such as HTTPRoute.
 //
+// Note that there are specific rules for ParentRefs which cross namespace
+// boundaries. 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.
+//
 // 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.
 // +k8s:deepcopy-gen=false

apis/v1beta1/shared_types.go

@@ -52,6 +52,12 @@ type ParentReference struct {
 	// Namespace is the namespace of the referent. When unspecified, this refers
 	// to the local namespace of the Route.
 	//
+	// Note that there are specific rules for ParentRefs which cross namespace
+	// boundaries. 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.
+	//
 	// Support: Core
 	//
 	// +optional
@@ -140,6 +146,12 @@ type CommonRouteSpec struct {
 	// case, the list of routes attached to those resources should also be
 	// merged.
 	//
+	// Note that for ParentRefs that cross namespace boundaries, there are specific
+	// 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.
+	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=32
 	ParentRefs []ParentReference `json:"parentRefs,omitempty"`