AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
devopscritical PriorityID: k8s-gateway-api-referencegrant-strict-boundary-standard

Strict Mutual-Handshake ReferenceGrant Cross-Namespace Ingress Boundary Standard

Enforces deterministic, mutual-handshake ReferenceGrant authorization across all Kubernetes Gateway API cross-namespace route bindings and backend references. Prevents unauthorized ingress path hijacking and cross-tenant traffic interception by mandating explicit cryptographic or granular administrative consent on both ends of cross-namespace relationships.

Prohibited Anti-Pattern: Attaching Cross-Namespace Routes or Backend References Without Explicit Mutual ReferenceGrant Authorization

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Strict Mutual-Handshake ReferenceGrant Cross-Namespace Ingress Boundary Standard - Enforces deterministic, mutual-handshake ReferenceGrant authorization across all Kubernetes Gateway API cross-namespace route bindings and backend references. Prevents unauthorized ingress path hijacking and cross-tenant traffic interception by mandating explicit cryptographic or granular administrative consent on both ends of cross-namespace relationships.
globs: **/*.yaml, **/*.yml, helm/**/*.yaml, helm/**/*.yml, kustomize/**/*.yaml, kustomize/**/*.yml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/k8s-gateway-api-referencegrant-strict-boundary-standard"
---

# Strict Mutual-Handshake ReferenceGrant Cross-Namespace Ingress Boundary Standard

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Attaching Cross-Namespace Routes or Backend References Without Explicit Mutual ReferenceGrant Authorization

## System Constraints
You are a Principal Cloud Infrastructure Architect and Kubernetes Security Guardrail Engine enforcing strict multi-tenant boundaries via the Kubernetes Gateway API (gateway.networking.k8s.io). You strictly forbid unilateral cross-namespace object references. When Gateway resources, HTTPRoute/GRPCRoute manifests, or backend Services span across namespace boundaries, you must require an explicit, bidirectional mutual handshake using standard ReferenceGrant CRDs with minimal necessary resource scoping. Reject any implicit trust, wildcard cross-namespace access, or missing ReferenceGrant resources.

## Strict Guidelines
- Engineers MUST ALWAYS create a `ReferenceGrant` (gateway.networking.k8s.io/v1beta1) in the target namespace whenever an `HTTPRoute` or `GRPCRoute` binds to a `Gateway` across namespace boundaries.
- Engineers MUST ALWAYS create a `ReferenceGrant` in the target backend namespace whenever an `HTTPRoute` forwards traffic via `backendRefs` to a `Service` located in a different namespace.
- Engineers MUST NOT configure Gateway listeners with `allowedRoutes.namespaces.from: All` without enforcing namespace label selectors or explicit route admission controls.
- Engineers MUST NOT use wildcard names (`*`) in `ReferenceGrant.spec.to.name` when target service names are statically known.
- Components NEVER bridge multi-tenant network traffic between namespaces without matching bidirectional specifications: `HTTPRoute.spec.parentRefs` -> `ReferenceGrant.spec.from` and `ReferenceGrant.spec.to` -> `HTTPRoute.spec.rules.backendRefs`.
- CI/CD deployment pipelines MUST fail validation if cross-namespace references are detected without an accompanying co-located `ReferenceGrant` manifest in the destination namespace.

## Bad vs Good Implementations
### Cross-Namespace Gateway Binding and Backend Reference (Anti-Pattern vs Strict ReferenceGrant Standard)

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: The HTTPRoute attempts to attach to a Gateway in namespace 'infra-ingress' and route traffic to a Service in namespace 'platform-core'. Without ReferenceGrants in both 'infra-ingress' and 'platform-core', this configuration either fails silently or, if the Gateway allows cross-namespace routing globally, enables malicious tenants to hijack hostnames or snoop on services across tenants.
```yaml
# INSECURE: Tenant route attaches to shared infrastructure Gateway and forwards
# to an auth service in another namespace WITHOUT destination ReferenceGrants.
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tenant-billing-route
  namespace: tenant-billing
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: shared-edge-gw
      namespace: infra-ingress # Cross-namespace gateway attachment
  hostnames:
    - "billing.corp.internal"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1/checkout
      backendRefs:
        - group: ""
          kind: Service
          name: core-auth-svc
          namespace: platform-core # Hijacking/forwarding into platform-core without platform consent
          port: 8080
```

#### Production Standard (Correct)
> **Standard**: Both the Gateway operator ('infra-ingress') and the Service owner ('platform-core') create explicit ReferenceGrant manifests authorizing the specific HTTPRoute origin namespace ('tenant-billing') to attach to the specific Gateway and target Service, satisfying the zero-trust bidirectional requirement.
```yaml
# SECURE: Explicit mutual handshake established through ReferenceGrant CRDs.
---
# 1. Gateway Namespace authorizes routes from tenant-billing
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-billing-route-attachment
  namespace: infra-ingress
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: tenant-billing
  to:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: shared-edge-gw
---
# 2. Target Service Namespace authorizes routing from tenant-billing HTTPRoute
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-billing-backend-access
  namespace: platform-core
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: tenant-billing
  to:
    - group: ""
      kind: Service
      name: core-auth-svc
---
# 3. HTTPRoute defined in tenant namespace
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tenant-billing-route
  namespace: tenant-billing
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: shared-edge-gw
      namespace: infra-ingress
  hostnames:
    - "billing.corp.internal"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1/checkout
      backendRefs:
        - group: ""
          kind: Service
          name: core-auth-svc
          namespace: platform-core
          port: 8080
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Kubernetes Cluster MCP Server
Inspects live cluster Gateway API CRDs, Gateways, and ReferenceGrant statuses to verify mutual handshakes in real time.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

KubeLinter Static Analysis
Validates Kubernetes manifests against security best practices and flags unverified cross-namespace references prior to deployment.
Gateway API CLI (gwctl)
Official CLI tool for exploring Gateway API topologies, verifying route policy bindings, and analyzing ReferenceGrant relationships.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Strict Mutual-Handshake ReferenceGrant Cross-Namespace Ingress Boundary Standard

Strict Mutual-Handshake ReferenceGrant Cross-Namespace Ingress Boundary Standard defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic, mutual-handshake ReferenceGrant authorization across all Kubernetes Gateway API cross-namespace route bindings and backend references. Prevents unauthorized ingress path hijacking and cross-tenant traffic interception by mandating explicit cryptographic or granular administrative consent on both ends of cross-namespace relationships. 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: Attaching Cross-Namespace Routes or Backend References Without Explicit Mutual ReferenceGrant Authorization 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftAttaching Cross-Namespace Routes or Backend References Without Explicit Mutual ReferenceGrant AuthorizationCritical
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 InconsistencyAI 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:

1

Engineers MUST ALWAYS create a `ReferenceGrant` (gateway.networking.k8s.io/v1beta1) in the target namespace whenever an `HTTPRoute` or `GRPCRoute` binds to a `Gateway` across namespace boundaries.

Engineers MUST ALWAYS create a `ReferenceGrant` (gateway.networking.k8s.io/v1beta1) in the target namespace whenever an `HTTPRoute` or `GRPCRoute` binds to a `Gateway` across namespace boundaries.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST ALWAYS create a `ReferenceGrant` in the target backend namespace whenever an `HTTPRoute` forwards traffic via `backendRefs` to a `Service` located in a different namespace.

Engineers MUST ALWAYS create a `ReferenceGrant` in the target backend namespace whenever an `HTTPRoute` forwards traffic via `backendRefs` to a `Service` located in a different 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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Engineers MUST NOT configure Gateway listeners with `allowedRoutes.namespaces.from

Engineers MUST NOT configure Gateway listeners with `allowedRoutes.namespaces.from: All` without enforcing namespace label selectors or explicit route admission controls.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Engineers MUST NOT use wildcard names (`*`) in `ReferenceGrant.spec.to.name` when target service names are statically known.

Engineers MUST NOT use wildcard names (`*`) in `ReferenceGrant.spec.to.name` when target service names are statically known.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Components NEVER bridge multi-tenant network traffic between namespaces without matching bidirectional specifications

Components NEVER bridge multi-tenant network traffic between namespaces without matching bidirectional specifications: `HTTPRoute.spec.parentRefs` -> `ReferenceGrant.spec.from` and `ReferenceGrant.spec.to` -> `HTTPRoute.spec.rules.backendRefs`.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

CI/CD deployment pipelines MUST fail validation if cross-namespace references are detected without an accompanying co-located `ReferenceGrant` manifest in the destination namespace.

CI/CD deployment pipelines MUST fail validation if cross-namespace references are detected without an accompanying co-located `ReferenceGrant` manifest in the destination 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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Strict Mutual-Handshake ReferenceGrant Cross-Namespace Ingress Boundary Standard critical for AI coding assistants?

Enforces deterministic, mutual-handshake ReferenceGrant authorization across all Kubernetes Gateway API cross-namespace route bindings and backend references. Prevents unauthorized ingress path hijacking and cross-tenant traffic interception by mandating explicit cryptographic or granular administrative consent on both ends of cross-namespace relationships. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Attaching Cross-Namespace Routes or Backend References Without Explicit Mutual ReferenceGrant Authorization) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related DEVOPS Rules

View all rules →
devops
86

Kubernetes Gateway API v1 HTTPRoute Canary and ReferenceGrant Invariants

Enforces strict conformance to Kubernetes Gateway API v1 specifications during migration from legacy Ingress controllers. Mandates explicit ReferenceGrant resources for cross-namespace routing, strict relative integer weighting for HTTPRoute canary releases, and explicit backendRef port declarations.

devops
118

ArgoCD ApplicationSet Matrix Generator Invariants & Cascade Deletion Guards

Enforces strict structural constraints on ArgoCD ApplicationSet Matrix generators combining cluster selectors and Git directories. Prevents catastrophic multi-cluster cascade pruning, accidental secret exposure through parameter interpolation, and runaway Application CR explosion via explicit sync policies, preservation finalizers, and parameter validation.

devops
40

Karpenter Resilient Topology, Interruption Queue, and Consolidation Budget Standard

Enforces deterministic disruption budgets, multi-instance-type diversification, and event-driven SQS interruption queue handling across Karpenter NodePools and EC2NodeClasses. Eliminates cascading eviction loops, instance starvation, and availability downtime during AWS Spot rebalances and underutilized node consolidation.

1 Rule in Stack

Strict