Clarify cross-namespace policy attachment semantics with `namespaceSelector` and `ReferenceGrant`

[zhaohuabing]

This is a follow-up to #8676.

In #8676, cross-namespace policy attachment was added using:

• targetSelectors.namespaces.selector in the policy spec to select targets in other namespaces
• ReferenceGrant in the target namespace to allow the policy to attach to the target

Example:

  apiVersion: gateway.envoyproxy.io/v1alpha1
  kind: SecurityPolicy
  metadata:
    namespace: policy-ns
    name: cross-ns-selector-policy
  spec:
    targetSelectors:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespaces:
        from: Selector
        selector:
          matchLabels:
            team: blue
      matchLabels:
        team: blue
    cors:
      allowOrigins:
      - https://example.com
---
  apiVersion: v1
  kind: Namespace
  metadata:
    name: route-ns
    labels:
      team: blue
---
  apiVersion: gateway.networking.k8s.io/v1
  kind: HTTPRoute
  metadata:
    namespace: route-ns
    name: test-route
    labels:
      team: blue
  spec:
    parentRefs:
    - name: test-gateway
      namespace: gateway-ns
      sectionName: http
    rules:
    - matches:
      - path:
          value: /
      backendRefs:
      - name: backend
        port: 8080
---
  apiVersion: gateway.networking.k8s.io/v1beta1
  kind: ReferenceGrant
  metadata:
    namespace: route-ns
    name: allow-selector-sp
  spec:
    from:
    - group: gateway.envoyproxy.io
      kind: SecurityPolicy
      namespace: policy-ns
    to:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: test-route

One remaining question is how targetSelectors and ReferenceGrant should interact. The semantics should be clear and easy for users to reason about.

Possible approaches:

Approach 1: Select first, then silently filter by ReferenceGrant

Envoy Gateway first computes candidate targets from targetSelectors, including namespaces.selector. It then applies ReferenceGrant as a permission check for cross-namespace targets and silently removes targets without a matching ReferenceGrant.

Under this model:

• namespaces.selector means selection.
• ReferenceGrant means permission.
• Cross-namespace targets without a matching ReferenceGrant are ignored.
• ReferenceGrant effectively acts as a fine-grained authorization filter on top of targetSelectors.

Pros:

• Keeps the model simple.
• Supports a two-level model where users select potential targets with labels, then allow specific cross-namespace attachments with ReferenceGrant.

Cons:

• It may be difficult to diagnose why some selected targets are attached while others are not when users just want to select all the matching targets.

Approach 2: Report unauthorized targets in policy status

Envoy Gateway still computes candidate targets from targetSelectors, including namespaces.selector, and still requires ReferenceGrant for cross-namespace attachment.

However, instead of only ignoring targets without a matching ReferenceGrant, Envoy Gateway records policy status indicating that selected cross-namespace targets were skipped because permission was missing.

Under this model:

• namespaces.selector still means selection.
• ReferenceGrant still means permission.
• Cross-namespace targets without a matching ReferenceGrant are excluded.
• Policy status explains why selected targets did not take effect.

Pros:
*Helps users diagnose why selected targets were not attached.

Cons:

• This implies that targetSelectors and ReferenceGrant are expected to match; otherwise Envoy Gateway surfaces a warning.
• This may be noisy because ReferenceGrant does not provide a namespace selector equivalent, so users may intentionally select a broad namespace set and authorize only specific targets with ReferenceGrant.