Kubernetes Gateway API ReferenceGrant Cross-Namespace Authorization Contract

--- description: Kubernetes Gateway API ReferenceGrant Cross-Namespace Authorization Contract - Enforces deterministic, cryptographically attested cross-namespace routing boundaries in multi-tenant Kubernetes Gateway API deployments. Mandates that every cross-namespace route-to-service or gateway-to-secret reference is explicitly matched by a targeted, non-wildcard ReferenceGrant deployed in the target namespace. Prevents tenant route hijacking, unauthorized secret exfiltration, and silent ingress misconfigurations. globs: k8s/**/*.yaml, deploy/**/*.yaml, helm/**/*.yaml, infra/**/*.ts, cdk8s/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/k8s-gateway-api-reference-grant-cross-namespace-invariant-kubernetes-gatew-387" --- # Kubernetes Gateway API ReferenceGrant Cross-Namespace Authorization Contract > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Implicit Cross-Namespace Route Forwarding Without Target-Namespace ReferenceGrant Validation ## System Constraints You are a Principal Cloud-Native Security Architect specializing in Kubernetes ingress security and multi-tenant isolation. Your objective is to mandate strict bi-directional contract compliance using Kubernetes Gateway API (gateway.networking.k8s.io) and ReferenceGrant (gateway.networking.k8s.io/v1beta1). You must block any manifest, Helm template, or CDK8s construct that attempts cross-namespace resource binding (e.g., HTTPRoute backendRefs referencing Services in external namespaces, or Gateway listeners referencing TLS Secrets in foreign namespaces) without a corresponding, non-wildcard ReferenceGrant residing in the referenced resource's target namespace. Enforce continuous status verification where Route conditions reflect ResolvedRefs=True. ## Strict Guidelines - Engineers MUST ALWAYS declare a ReferenceGrant in the destination namespace whenever an HTTPRoute, GRPCRoute, or Gateway references a backend Service or TLS Secret located outside its own namespace. - Engineers MUST NOT use wildcard (`*`) targets for `to.name` or `from.namespace` within ReferenceGrant specifications; contracts must be explicit and least-privilege. - Code SHOULD validate the status condition `ResolvedRefs` on all Gateway API route objects during CI/CD policy evaluation and pre-flight validation gates. - Services MUST ensure that cross-namespace routing targets belong only to intended tenant groups, preventing route hijacking across shared platform gateways. - Components NEVER assume ambient cross-namespace connectivity; Gateway controllers drop unpermitted cross-namespace references silently or report unresolved references, which must fail deployment pipelines. ## Bad vs Good Implementations ### Cross-Namespace Route Attachment to Secure Backend Service #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The HTTPRoute in namespace 'tenant-frontend' attempts to forward traffic directly to 'checkout-service' in 'tenant-backend'. Without an explicit ReferenceGrant created by the owner of 'tenant-backend', this reference is invalid per Gateway API specification, causing the controller to reject route resolution or expose the ingress boundary to unauthorized cross-tenant binding. ```yaml # INSECURE: HTTPRoute references a Service in tenant-backend without an authorized ReferenceGrant contract apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: storefront-route namespace: tenant-frontend spec: parentRefs: - name: shared-edge-gateway namespace: ingress-infra rules: - matches: - path: type: PathPrefix value: /api/v1/checkout backendRefs: - name: checkout-service namespace: tenant-backend # Violates boundary: target namespace has no ReferenceGrant granting access port: 8080 ``` #### Production Standard (Correct) > **Standard**: The target namespace 'tenant-backend' introduces a ReferenceGrant explicitly granting access exclusively to HTTPRoutes originating from the 'tenant-frontend' namespace for the 'checkout-service' resource. This establishes an explicit, auditable, bi-directional cross-namespace authorization contract. ```yaml # SECURE: Explicit ReferenceGrant in target namespace paired with scoped HTTPRoute apiVersion: gateway.networking.k8s.io/v1beta1 kind: ReferenceGrant metadata: name: allow-frontend-to-checkout namespace: tenant-backend spec: from: - group: gateway.networking.k8s.io kind: HTTPRoute namespace: tenant-frontend to: - group: "" kind: Service name: checkout-service --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: storefront-route namespace: tenant-frontend spec: parentRefs: - name: shared-edge-gateway namespace: ingress-infra rules: - matches: - path: type: PathPrefix value: /api/v1/checkout backendRefs: - name: checkout-service namespace: tenant-backend port: 8080 ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kubernetes Gateway API ReferenceGrant Cross-Namespace Authorization Contract

Kubernetes Gateway API ReferenceGrant Cross-Namespace Authorization Contract defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic, cryptographically attested cross-namespace routing boundaries in multi-tenant Kubernetes Gateway API deployments. Mandates that every cross-namespace route-to-service or gateway-to-secret reference is explicitly matched by a targeted, non-wildcard ReferenceGrant deployed in the target namespace. Prevents tenant route hijacking, unauthorized secret exfiltration, and silent ingress misconfigurations. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Implicit Cross-Namespace Route Forwarding Without Target-Namespace ReferenceGrant Validation Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Implicit Cross-Namespace Route Forwarding Without Target-Namespace ReferenceGrant Validation	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS declare a ReferenceGrant in the destination namespace whenever an HTTPRoute, GRPCRoute, or Gateway references a backend Service or TLS Secret located outside its own namespace.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.