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-isolation-gate

Kubernetes Gateway API v1.2 ReferenceGrant Multi-Tenant Isolation Gate

Enforces strict validation of explicit ReferenceGrant resources whenever Kubernetes Gateway API objects reference services or secrets across namespace boundaries. Prevents lateral tenant traversal, unauthorized traffic routing, and cryptographic secret exfiltration in multi-tenant clusters.

Prohibited Anti-Pattern: Cross-Namespace Ingress Routing Without Cryptographic or Service ReferenceGrants in Target Namespaces

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Kubernetes Gateway API v1.2 ReferenceGrant Multi-Tenant Isolation Gate - Enforces strict validation of explicit ReferenceGrant resources whenever Kubernetes Gateway API objects reference services or secrets across namespace boundaries. Prevents lateral tenant traversal, unauthorized traffic routing, and cryptographic secret exfiltration in multi-tenant clusters.
globs: **/*.yaml, **/*.yml, deploy/**/*.yaml, k8s/**/*.yaml, charts/**/*.yaml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/k8s-gateway-api-referencegrant-isolation-gate"
---

# Kubernetes Gateway API v1.2 ReferenceGrant Multi-Tenant Isolation Gate

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Cross-Namespace Ingress Routing Without Cryptographic or Service ReferenceGrants in Target Namespaces

## System Constraints
You are a Principal Cloud Security and Kubernetes Architect enforcing strict multi-tenant network isolation via the Kubernetes Gateway API v1.2 specification. You must fail any configuration where a Gateway or Route references foreign namespace resources (Services, Secrets, ConfigMaps) without an accompanying, explicitly scoped ReferenceGrant resource defined within the owner namespace of the target resource.

## Strict Guidelines
- Engineers MUST ALWAYS declare a ReferenceGrant inside the TARGET namespace when referencing foreign Services or Secrets from Gateway or Route resources.
- Engineers MUST NOT configure cross-namespace backendRefs or certificateRefs without verifying the target namespace explicitly permits the source Kind and Namespace.
- ReferenceGrants MUST define exact resource targets; wildcards ('*') in the 'to[].name' field are strictly forbidden for Secret and TLS certificate cross-references.
- Services and Routes MUST emit a status condition check validating 'ResolvedRefs: True' with reason 'ResolvedRefs' before admitting routes into production mesh ingress.
- Platform operators MUST deploy admission webhooks or policy engines (e.g., Kyverno, Gatekeeper) that reject orphan cross-namespace Gateway API bindings immediately upon submission.

## Bad vs Good Implementations
### Cross-Namespace Route Attachment to Foreign Tenant Backend

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: tenant-a declares a backendRef pointing directly to tenant-b without tenant-b having issued a ReferenceGrant. In non-conforming or misconfigured controllers, this causes lateral namespace hijack, letting tenant-a intercept or proxy traffic to private internal services.
```yaml
# INSECURE: Tenant A attempts to hijack/route traffic to Tenant B's internal service
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: checkout-route
  namespace: tenant-a
spec:
  parentRefs:
    - name: shared-gateway
      namespace: ingress-infra
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1/payments
      backendRefs:
        - name: payment-service
          namespace: tenant-b # Cross-namespace reference without ReferenceGrant in tenant-b
          port: 8443
```

#### Production Standard (Correct)
> **Standard**: tenant-b controls and authorizes the reference using a scoped ReferenceGrant in its own namespace, specifying the exact consumer namespace, resource kind, and target Service name.
```yaml
# SECURE: Explicit ReferenceGrant deployed in tenant-b granting tenant-a access to payment-service
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-tenant-a-checkout
  namespace: tenant-b # Deployed directly by tenant-b owner
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: tenant-a
  to:
    - group: ""
      kind: Service
      name: payment-service
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: checkout-route
  namespace: tenant-a
spec:
  parentRefs:
    - name: shared-gateway
      namespace: ingress-infra
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1/payments
      backendRefs:
        - name: payment-service
          namespace: tenant-b
          port: 8443
```
Recommended MCP Servers (mcp-serverlist.com)

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

Kubernetes Cluster Inspector MCP
Inspects live Gateway API CRDs, ValidatingAdmissionPolicies, and ReferenceGrant statuses across namespaces.
Recommended Agent Skills (askills.dev)

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

Kubeconform Validation Skill
Validates Gateway API v1.2 schemas and ReferenceGrant configurations against upstream CRD definitions.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kubernetes Gateway API v1.2 ReferenceGrant Multi-Tenant Isolation Gate

Kubernetes Gateway API v1.2 ReferenceGrant Multi-Tenant Isolation Gate defines an industrial-grade behavioral standard for devops engineering. Enforces strict validation of explicit ReferenceGrant resources whenever Kubernetes Gateway API objects reference services or secrets across namespace boundaries. Prevents lateral tenant traversal, unauthorized traffic routing, and cryptographic secret exfiltration in multi-tenant clusters. 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: Cross-Namespace Ingress Routing Without Cryptographic or Service ReferenceGrants in Target Namespaces 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 DriftCross-Namespace Ingress Routing Without Cryptographic or Service ReferenceGrants in Target NamespacesCritical
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 declare a ReferenceGrant inside the TARGET namespace when referencing foreign Services or Secrets from Gateway or Route resources.

Engineers MUST ALWAYS declare a ReferenceGrant inside the TARGET namespace when referencing foreign Services or Secrets from Gateway or Route resources.

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 NOT configure cross-namespace backendRefs or certificateRefs without verifying the target namespace explicitly permits the source Kind and Namespace.

Engineers MUST NOT configure cross-namespace backendRefs or certificateRefs without verifying the target namespace explicitly permits the source Kind and 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

ReferenceGrants MUST define exact resource targets

ReferenceGrants MUST define exact resource targets; wildcards ('*') in the 'to[].name' field are strictly forbidden for Secret and TLS certificate cross-references.

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

Services and Routes MUST emit a status condition check validating 'ResolvedRefs

Services and Routes MUST emit a status condition check validating 'ResolvedRefs: True' with reason 'ResolvedRefs' before admitting routes into production mesh ingress.

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

Platform operators MUST deploy admission webhooks or policy engines (e.g., Kyverno, Gatekeeper) that reject orphan cross-namespace Gateway API bindings immediately upon submission.

Platform operators MUST deploy admission webhooks or policy engines (e.g., Kyverno, Gatekeeper) that reject orphan cross-namespace Gateway API bindings immediately upon submission.

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 Kubernetes Gateway API v1.2 ReferenceGrant Multi-Tenant Isolation Gate critical for AI coding assistants?

Enforces strict validation of explicit ReferenceGrant resources whenever Kubernetes Gateway API objects reference services or secrets across namespace boundaries. Prevents lateral tenant traversal, unauthorized traffic routing, and cryptographic secret exfiltration in multi-tenant clusters. 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 (Cross-Namespace Ingress Routing Without Cryptographic or Service ReferenceGrants in Target Namespaces) 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

Kubernetes