Kubernetes Gateway Cross Namespace Routing

Kubernetes Gateway Cross Namespace Routing refers to the Gateway API's explicit support for Route resources in one namespace attaching to a Gateway in a different namespace, or referencing backend Services outside their own namespace, along with the ReferenceGrant mechanism that governs when such cross-boundary references are permitted.

Why Cross Namespace Routing Exists

Shared Infrastructure Ownership Model

Gateway API's layered ownership model, with Gateways typically owned by a platform team and Routes owned by individual application teams, inherently requires crossing namespace boundaries, since application teams' Routes live in their own namespaces while a shared Gateway lives in an infrastructure-owned namespace. Cross namespace routing is the mechanism that makes this ownership split practically workable.

Contrast With Ingress's Namespace Confinement

Unlike the original Ingress API, which restricts a resource to referencing backends only within its own namespace, Gateway API was designed from the outset to support crossing namespace boundaries safely, addressing a limitation that previously forced workarounds like duplicating Ingress objects per namespace or relying on controller-specific extensions.

The ReferenceGrant Mechanism

Explicit, Target-Controlled Permission

A ReferenceGrant is created in the target namespace, the one being referenced, and explicitly lists which source namespace and resource kind combinations are permitted to reference resources within it. This design places control firmly in the hands of the namespace being referenced, preventing any namespace from unilaterally attaching to or targeting another namespace's resources without that namespace's explicit consent.

Scope Limited to Named Kinds

A ReferenceGrant only permits the specific resource kinds it names, meaning a grant allowing HTTPRoute references does not implicitly permit TCPRoute references from the same namespace, requiring cross namespace routing management to be explicit about every kind of reference that needs to be authorized.

Cross Namespace Backend References

Beyond Gateway Attachment

Cross namespace routing extends beyond just Route-to-Gateway attachment; a Route's backend references can also point to a Service in a different namespace than the Route itself, which similarly requires a ReferenceGrant in the target namespace containing the Service, a distinct grant from whatever permits the Gateway attachment.

Common Multi-Team Backend Scenarios

This capability is used when a shared backend Service, such as a common authentication or gateway aggregation service, needs to be reachable from Routes defined across several different application namespaces, each requiring its own explicit grant rather than a single blanket permission.

Security Implications

Preventing Unauthorized Namespace Targeting

Because ReferenceGrant requires action from the target namespace rather than the source, cross namespace routing cannot be used by a compromised or misconfigured namespace to unilaterally attach to or route traffic through infrastructure it does not own, a deliberate security property that distinguishes this model from less restrictive cross-namespace reference patterns elsewhere in Kubernetes.

Operational Management

Grant Lifecycle Coordination

Cross namespace routing in practice requires coordinating the lifecycle of ReferenceGrants with the onboarding and offboarding of application namespaces, ensuring grants are created before a new team's Routes are expected to attach and cleaned up when a namespace is decommissioned, to avoid both broken initial deployments and stale, unnecessary permissions lingering after a team's resources are removed.