Clarify wording and add to namespace field

Signed-off-by: Nick Young <nick@isovalent.com>

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 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.
+//
 // 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 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.
+	//
 	// Support: Core
 	//
 	// +optional
@@ -140,12 +146,11 @@ type CommonRouteSpec struct {
 	// case, the list of routes attached to those resources should also be
 	// merged.
 	//
-	// Note that for ParentRefs that cross namespace boundaries, the parent
-	// being referred to must have some mechanism to allow Routes to attach.
-	// Gateway has the AllowedRoutes field, for example. Any other resource
-	// being used as a parent across namespaces MUST either include an AllowedRoutes
-	// field or equivalent functionality, OR use a ReferenceGrant (if the spec
-	// can't have a field added).
+	// 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