feat: cross namespace support for aigatewayroute and aiservicebackend (#1361)

**Description**

This PR implements comprehensive cross-namespace access support between
AIServiceBackend and AIGatewayRoute resources, following Gateway API
patterns with ReferenceGrant validation.

**API Enhancements**
- Added namespace field to AIGatewayRouteRuleBackendRef allowing
cross-namespace backend references
- Updated CRDs to include proper validation for the namespace field
Enhanced documentation explaining ReferenceGrant requirements for
cross-namespace access
**ReferenceGrant Integration**
- ReferenceGrant Validator: New component that validates cross-namespace
references against ReferenceGrant resources
- ReferenceGrant Controller: Watches ReferenceGrant resources and
triggers reconciliation of affected AIGatewayRoutes when grants change
- Automatic validation: Cross-namespace references are automatically
validated at reconciliation time

**Controller Updates**
- Cross-namespace backend lookups: AIGatewayRoute controller now
supports referencing AIServiceBackend resources in different namespaces
- ReferenceGrant enforcement: Fails reconciliation with clear error
messages when valid ReferenceGrant is missing
- Event-driven reconciliation: ReferenceGrant changes trigger automatic
reconciliation of affected routes


**Comprehensive Testing**
- Unit tests: Full coverage for ReferenceGrant validation logic,
cross-namespace scenarios, and error cases
- Integration tests: Controller tests validating cross-namespace backend
references with and without ReferenceGrant
- E2E test updates: Modified existing cross-namespace test to validate
AIServiceBackend cross-namespace access with ReferenceGrant

AIGatewayRouteBackendRefChange: 
```
# AIGatewayRouteRuleBackendRef now supports:
backendRefs:
- name: my-backend
  namespace: other-namespace  # NEW: Cross-namespace reference
  weight: 1
```

Reference Grant Example: 
```
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-route-to-backend
  namespace: backend-ns
spec:
  from:
    - group: aigateway.envoyproxy.io
      kind: AIGatewayRoute
      namespace: route-ns
  to:
    - group: aigateway.envoyproxy.io
      kind: AIServiceBackend
```

**Related Issues/PRs (if applicable)**
close #1374

---------

Signed-off-by: siddharth1036 <[email protected]>

Author: siddharth1036

api/v1alpha1/ai_gateway_route.go

@@ -200,7 +200,11 @@ type AIGatewayRouteRule struct {
 	// BackendRefs is the list of backends that this rule will route the traffic to.
 	// Each backend can have a weight that determines the traffic distribution.
 	//
-	// The namespace of each backend is "local", i.e. the same namespace as the AIGatewayRoute.
+	// The namespace of each backend defaults to the same namespace as the AIGatewayRoute when not specified.
+	// Cross-namespace references are supported by specifying the namespace field.
+	// When a namespace different than the AIGatewayRoute's namespace is specified,
+	// a ReferenceGrant object is required in the referent namespace to allow that
+	// namespace's owner to accept the reference.
 	//
 	// BackendRefs can reference either AIServiceBackend resources (default) or InferencePool resources
 	// from the Gateway API Inference Extension. When referencing InferencePool resources:
@@ -278,6 +282,17 @@ type AIGatewayRouteRuleBackendRef struct {
 	// +kubebuilder:validation:MinLength=1
 	Name string `json:"name"`
 
+	// Namespace is the namespace of the backend resource.
+	// When unspecified (or empty string), this refers to the local namespace of the AIGatewayRoute.
+	//
+	// 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.
+	//
+	// +optional
+	Namespace *gwapiv1.Namespace `json:"namespace,omitempty"`
+
 	// Group is the group of the backend resource.
 	// When not specified, defaults to aigateway.envoyproxy.io (AIServiceBackend).
 	// Currently, only "inference.networking.k8s.io" is supported for InferencePool resources.

api/v1alpha1/ai_gateway_route_helper.go

@@ -82,3 +82,21 @@ func (r *AIGatewayRouteRule) HasAIServiceBackends() bool {
 	}
 	return false
 }
+
+// GetNamespace returns the namespace for the backend reference.
+// If the namespace is not specified, it returns the provided defaultNamespace.
+func (ref *AIGatewayRouteRuleBackendRef) GetNamespace(defaultNamespace string) string {
+	if ref.Namespace != nil && *ref.Namespace != "" {
+		return string(*ref.Namespace)
+	}
+	return defaultNamespace
+}
+
+// IsCrossNamespace returns true if the backend reference is a cross-namespace reference.
+// A cross-namespace reference is one where the namespace field is specified and differs from the routeNamespace.
+func (ref *AIGatewayRouteRuleBackendRef) IsCrossNamespace(routeNamespace string) bool {
+	if ref.Namespace == nil || *ref.Namespace == "" {
+		return false
+	}
+	return string(*ref.Namespace) != routeNamespace
+}

api/v1alpha1/ai_gateway_route_helper_test.go

@@ -80,6 +80,11 @@ func TestAIGatewayRouteRuleBackendRef_IsInferencePool(t *testing.T) {
 		ref      *AIGatewayRouteRuleBackendRef
 		expected bool
 	}{
+		{
+			name:     "Nil reference",
+			ref:      nil,
+			expected: false,
+		},
 		{
 			name: "AIServiceBackend reference (no group/kind)",
 			ref: &AIGatewayRouteRuleBackendRef{
@@ -161,6 +166,11 @@ func TestAIGatewayRouteRule_HasInferencePoolBackends(t *testing.T) {
 		rule     *AIGatewayRouteRule
 		expected bool
 	}{
+		{
+			name:     "Nil rule",
+			rule:     nil,
+			expected: false,
+		},
 		{
 			name: "No backends",
 			rule: &AIGatewayRouteRule{
@@ -221,6 +231,11 @@ func TestAIGatewayRouteRule_HasAIServiceBackends(t *testing.T) {
 		rule     *AIGatewayRouteRule
 		expected bool
 	}{
+		{
+			name:     "Nil rule",
+			rule:     nil,
+			expected: false,
+		},
 		{
 			name: "No backends",
 			rule: &AIGatewayRouteRule{
@@ -260,3 +275,107 @@ func TestAIGatewayRouteRule_HasAIServiceBackends(t *testing.T) {
 		})
 	}
 }
+
+func TestAIGatewayRouteRuleBackendRef_GetNamespace(t *testing.T) {
+	tests := []struct {
+		name             string
+		ref              *AIGatewayRouteRuleBackendRef
+		defaultNamespace string
+		expected         string
+	}{
+		{
+			name: "No namespace specified - should use default",
+			ref: &AIGatewayRouteRuleBackendRef{
+				Name: "test-backend",
+			},
+			defaultNamespace: "default",
+			expected:         "default",
+		},
+		{
+			name: "Empty namespace specified - should use default",
+			ref: &AIGatewayRouteRuleBackendRef{
+				Name:      "test-backend",
+				Namespace: ptr.To(gwapiv1.Namespace("")),
+			},
+			defaultNamespace: "default",
+			expected:         "default",
+		},
+		{
+			name: "Specific namespace specified - should use specified namespace",
+			ref: &AIGatewayRouteRuleBackendRef{
+				Name:      "test-backend",
+				Namespace: ptr.To(gwapiv1.Namespace("other-namespace")),
+			},
+			defaultNamespace: "default",
+			expected:         "other-namespace",
+		},
+		{
+			name: "Same namespace as default - should use specified namespace",
+			ref: &AIGatewayRouteRuleBackendRef{
+				Name:      "test-backend",
+				Namespace: ptr.To(gwapiv1.Namespace("default")),
+			},
+			defaultNamespace: "default",
+			expected:         "default",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := tt.ref.GetNamespace(tt.defaultNamespace)
+			require.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestAIGatewayRouteRuleBackendRef_IsCrossNamespace(t *testing.T) {
+	tests := []struct {
+		name           string
+		ref            *AIGatewayRouteRuleBackendRef
+		routeNamespace string
+		expected       bool
+	}{
+		{
+			name: "No namespace specified - not cross-namespace",
+			ref: &AIGatewayRouteRuleBackendRef{
+				Name: "test-backend",
+			},
+			routeNamespace: "default",
+			expected:       false,
+		},
+		{
+			name: "Empty namespace specified - not cross-namespace",
+			ref: &AIGatewayRouteRuleBackendRef{
+				Name:      "test-backend",
+				Namespace: ptr.To(gwapiv1.Namespace("")),
+			},
+			routeNamespace: "default",
+			expected:       false,
+		},
+		{
+			name: "Same namespace as route - not cross-namespace",
+			ref: &AIGatewayRouteRuleBackendRef{
+				Name:      "test-backend",
+				Namespace: ptr.To(gwapiv1.Namespace("default")),
+			},
+			routeNamespace: "default",
+			expected:       false,
+		},
+		{
+			name: "Different namespace from route - is cross-namespace",
+			ref: &AIGatewayRouteRuleBackendRef{
+				Name:      "test-backend",
+				Namespace: ptr.To(gwapiv1.Namespace("other-namespace")),
+			},
+			routeNamespace: "default",
+			expected:       true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := tt.ref.IsCrossNamespace(tt.routeNamespace)
+			require.Equal(t, tt.expected, result)
+		})
+	}
+}

api/v1alpha1/zz_generated.deepcopy.go

@@ -58,6 +58,8 @@ type AIGatewayRouteController struct {
 	gatewayEventChan chan event.GenericEvent
 	// rootPrefix is the prefix for the root path of the AI Gateway.
 	rootPrefix string
+	// referenceGrantValidator validates cross-namespace references using ReferenceGrant.
+	referenceGrantValidator *referenceGrantValidator
 }
 
 // NewAIGatewayRouteController creates a new reconcile.TypedReconciler[reconcile.Request] for the AIGatewayRoute resource.
@@ -67,11 +69,12 @@ func NewAIGatewayRouteController(
 	rootPrefix string,
 ) *AIGatewayRouteController {
 	return &AIGatewayRouteController{
-		client:           client,
-		kube:             kube,
-		logger:           logger,
-		gatewayEventChan: gatewayEventChan,
-		rootPrefix:       rootPrefix,
+		client:                  client,
+		kube:                    kube,
+		logger:                  logger,
+		gatewayEventChan:        gatewayEventChan,
+		rootPrefix:              rootPrefix,
+		referenceGrantValidator: newReferenceGrantValidator(client),
 	}
 }
 
@@ -252,7 +255,8 @@ func (c *AIGatewayRouteController) newHTTPRoute(ctx context.Context, dst *gwapiv
 		var backendRefs []gwapiv1.HTTPBackendRef
 		for j := range rule.BackendRefs {
 			br := &rule.BackendRefs[j]
-			dstName := fmt.Sprintf("%s.%s", br.Name, aiGatewayRoute.Namespace)
+			backendNamespace := br.GetNamespace(aiGatewayRoute.Namespace)
+			dstName := fmt.Sprintf("%s.%s", br.Name, backendNamespace)
 
 			if br.IsInferencePool() {
 				// Handle InferencePool backend reference.
@@ -268,14 +272,28 @@ func (c *AIGatewayRouteController) newHTTPRoute(ctx context.Context, dst *gwapiv
 					}},
 				)
 			} else {
-				// Handle AIServiceBackend reference.
-				backend, err := c.backend(ctx, aiGatewayRoute.Namespace, br.Name)
+				// Handle AIServiceBackend reference with cross-namespace validation.
+				backend, err := c.validateAndGetBackend(ctx, aiGatewayRoute, br)
 				if err != nil {
-					return fmt.Errorf("AIServiceBackend %s not found", dstName)
+					return fmt.Errorf("failed to get AIServiceBackend %s: %w", dstName, err)
 				}
+
+				// Copy the BackendObjectReference from the AIServiceBackend.
+				backendObjRef := backend.Spec.BackendRef
+
+				// Ensure the namespace is explicitly set in the BackendObjectReference
+				// only for cross-namespace references.
+				// If the AIServiceBackend is in a different namespace than the AIGatewayRoute,
+				// the Backend it references is also in that namespace, and we need to set
+				// the namespace explicitly in the HTTPRoute's backendRef.
+				if backendObjRef.Namespace == nil && backend.Namespace != "" && backend.Namespace != aiGatewayRoute.Namespace {
+					ns := gwapiv1.Namespace(backend.Namespace)
+					backendObjRef.Namespace = &ns
+				}
+
 				backendRefs = append(backendRefs,
 					gwapiv1.HTTPBackendRef{BackendRef: gwapiv1.BackendRef{
-						BackendObjectReference: backend.Spec.BackendRef,
+						BackendObjectReference: backendObjRef,
 						Weight:                 br.Weight,
 					}},
 				)
@@ -372,6 +390,36 @@ func (c *AIGatewayRouteController) backend(ctx context.Context, namespace, name
 	return backend, nil
 }
 
+// validateAndGetBackend validates a backend reference (including cross-namespace ReferenceGrant check)
+// and returns the AIServiceBackend if valid.
+func (c *AIGatewayRouteController) validateAndGetBackend(
+	ctx context.Context,
+	aiGatewayRoute *aigv1a1.AIGatewayRoute,
+	backendRef *aigv1a1.AIGatewayRouteRuleBackendRef,
+) (*aigv1a1.AIServiceBackend, error) {
+	backendNamespace := backendRef.GetNamespace(aiGatewayRoute.Namespace)
+
+	// Validate cross-namespace reference if applicable
+	if backendRef.IsCrossNamespace(aiGatewayRoute.Namespace) {
+		if err := c.referenceGrantValidator.validateAIServiceBackendReference(
+			ctx,
+			aiGatewayRoute.Namespace,
+			backendNamespace,
+			backendRef.Name,
+		); err != nil {
+			return nil, err
+		}
+	}
+
+	// Get the backend
+	backend, err := c.backend(ctx, backendNamespace, backendRef.Name)
+	if err != nil {
+		return nil, fmt.Errorf("AIServiceBackend %s.%s not found", backendRef.Name, backendNamespace)
+	}
+
+	return backend, nil
+}
+
 // updateAIGatewayRouteStatus updates the status of the AIGatewayRoute.
 func (c *AIGatewayRouteController) updateAIGatewayRouteStatus(ctx context.Context, route *aigv1a1.AIGatewayRoute, conditionType string, message string) {
 	err := retry.RetryOnConflict(retry.DefaultRetry, func() error {