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-backend-tls-san-verification

Gateway API v1.2 BackendTLSPolicy Strict SAN Verification Standard

Enforces strict transport security and explicit cryptographic identity verification between Kubernetes Gateway controllers and upstream backends. Mandates the binding of BackendTLSPolicy v1alpha3 resources with explicit Subject Alternative Name (SAN) hostnames and pinned CA certificate references to eliminate east-west man-in-the-middle attacks and internal impersonation vectors.

Prohibited Anti-Pattern: Unvalidated Backend TLS Allowing East-West Service Impersonation and Insecure Upstream Transport

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Gateway API v1.2 BackendTLSPolicy Strict SAN Verification Standard - Enforces strict transport security and explicit cryptographic identity verification between Kubernetes Gateway controllers and upstream backends. Mandates the binding of BackendTLSPolicy v1alpha3 resources with explicit Subject Alternative Name (SAN) hostnames and pinned CA certificate references to eliminate east-west man-in-the-middle attacks and internal impersonation vectors.
globs: **/*.yaml, **/*.yml, deploy/**/*.yaml, k8s/**/*.yaml, charts/**/*.yaml, infra/**/*.yaml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/k8s-gateway-backend-tls-san-verification"
---

# Gateway API v1.2 BackendTLSPolicy Strict SAN Verification Standard

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Unvalidated Backend TLS Allowing East-West Service Impersonation and Insecure Upstream Transport

## System Constraints
You are a Principal Infrastructure Security Architect enforcing the Kubernetes Gateway API v1.2 BackendTLSPolicy Strict SAN Verification Standard. You must ensure that all Gateway-to-backend transport paths are cryptographically authenticated using Gateway API BackendTLSPolicy resources with strict, explicit SAN hostname matching and immutable CA trust anchors.

## Strict Guidelines
- Engineers MUST ALWAYS declare a dedicated `BackendTLSPolicy` in `gateway.networking.k8s.io/v1alpha3` targeting backend `Service` references for TLS-enabled upstreams.
- Engineers MUST NOT omit the `validation.hostname` field or configure wildcards that exceed the single-label boundary of the service's cryptographically bound SAN.
- Services MUST define `appProtocol: kubernetes.io/tls` or `appProtocol: https` on backend Service port definitions when BackendTLSPolicy is applied.
- Engineers MUST specify explicit `caCertificateRefs` pointing to immutable ConfigMaps containing trusted root certificates, rather than trusting unpinned system stores, unless explicitly configured via `wellKnownCACertificates: System`.
- Components NEVER bridge Gateway routes (HTTPRoute/GRPCRoute) to TLS endpoints without an accompanying and reconciled BackendTLSPolicy in the same namespace as the target Service.

## Bad vs Good Implementations
### Insecure Route Lacking BackendTLSPolicy and Explicit SAN Verification

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: The HTTPRoute forwards traffic to port 8443 without binding a BackendTLSPolicy. The gateway proxy performs unauthenticated or plaintext upstream forwarding, allowing internal attackers with pod or network access to intercept, spoof, or replay east-west requests.
```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: payment-route
  namespace: payments
spec:
  parentRefs:
    - name: internal-gateway
      namespace: gateway-infra
  rules:
    - backendRefs:
        - name: payment-service
          port: 8443
---
apiVersion: v1
kind: Service
metadata:
  name: payment-service
  namespace: payments
spec:
  ports:
    - name: https
      port: 8443
      targetPort: 8443
      # FAILS: Missing appProtocol annotation and no BackendTLSPolicy defined.
      # East-west traffic traverses gateway-to-backend unverified or blindly ignores SAN.
```

#### Production Standard (Correct)
> **Standard**: The BackendTLSPolicy explicitly binds to the payment Service, validates the upstream certificate against a designated CA ConfigMap, and strictly checks the SAN against 'payment-service.payments.svc.cluster.local', ensuring cryptographic non-repudiation across the gateway-backend hop.
```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: payment-route
  namespace: payments
spec:
  parentRefs:
    - name: internal-gateway
      namespace: gateway-infra
  rules:
    - backendRefs:
        - name: payment-service
          port: 8443
---
apiVersion: v1
kind: Service
metadata:
  name: payment-service
  namespace: payments
spec:
  ports:
    - name: https
      port: 8443
      targetPort: 8443
      appProtocol: kubernetes.io/tls
---
apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: payment-backend-tls
  namespace: payments
spec:
  targetRefs:
    - group: ""
      kind: Service
      name: payment-service
  validation:
    caCertificateRefs:
      - group: ""
        kind: ConfigMap
        name: internal-ca-bundle
    hostname: payment-service.payments.svc.cluster.local
```
Recommended MCP Servers (mcp-serverlist.com)

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

Kubernetes Cluster Model Context Protocol Server
Enables real-time validation, schema verification, and active cluster querying for Gateway API resources and CRD specifications.
Recommended Agent Skills (askills.dev)

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

kubeconform
Validates Kubernetes manifests against Gateway API v1.2 JSON schemas to detect missing required fields in BackendTLSPolicy declarations.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Gateway API v1.2 BackendTLSPolicy Strict SAN Verification Standard

Gateway API v1.2 BackendTLSPolicy Strict SAN Verification Standard defines an industrial-grade behavioral standard for devops engineering. Enforces strict transport security and explicit cryptographic identity verification between Kubernetes Gateway controllers and upstream backends. Mandates the binding of BackendTLSPolicy v1alpha3 resources with explicit Subject Alternative Name (SAN) hostnames and pinned CA certificate references to eliminate east-west man-in-the-middle attacks and internal impersonation vectors. 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: Unvalidated Backend TLS Allowing East-West Service Impersonation and Insecure Upstream Transport 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 DriftUnvalidated Backend TLS Allowing East-West Service Impersonation and Insecure Upstream TransportCritical
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 dedicated `BackendTLSPolicy` in `gateway.networking.k8s.io/v1alpha3` targeting backend `Service` references for TLS-enabled upstreams.

Engineers MUST ALWAYS declare a dedicated `BackendTLSPolicy` in `gateway.networking.k8s.io/v1alpha3` targeting backend `Service` references for TLS-enabled upstreams.

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 omit the `validation.hostname` field or configure wildcards that exceed the single-label boundary of the service's cryptographically bound SAN.

Engineers MUST NOT omit the `validation.hostname` field or configure wildcards that exceed the single-label boundary of the service's cryptographically bound SAN.

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

Services MUST define `appProtocol

Services MUST define `appProtocol: kubernetes.io/tls` or `appProtocol: https` on backend Service port definitions when BackendTLSPolicy is applied.

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 specify explicit `caCertificateRefs` pointing to immutable ConfigMaps containing trusted root certificates, rather than trusting unpinned system stores, unless explicitly configured via `wellKnownCACertificates

Engineers MUST specify explicit `caCertificateRefs` pointing to immutable ConfigMaps containing trusted root certificates, rather than trusting unpinned system stores, unless explicitly configured via `wellKnownCACertificates: System`.

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 Gateway routes (HTTPRoute/GRPCRoute) to TLS endpoints without an accompanying and reconciled BackendTLSPolicy in the same namespace as the target Service.

Components NEVER bridge Gateway routes (HTTPRoute/GRPCRoute) to TLS endpoints without an accompanying and reconciled BackendTLSPolicy in the same namespace as the target Service.

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 Gateway API v1.2 BackendTLSPolicy Strict SAN Verification Standard critical for AI coding assistants?

Enforces strict transport security and explicit cryptographic identity verification between Kubernetes Gateway controllers and upstream backends. Mandates the binding of BackendTLSPolicy v1alpha3 resources with explicit Subject Alternative Name (SAN) hostnames and pinned CA certificate references to eliminate east-west man-in-the-middle attacks and internal impersonation vectors. 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 (Unvalidated Backend TLS Allowing East-West Service Impersonation and Insecure Upstream Transport) 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

Gateway