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: cilium-ebpf-host-routing-wireguard-invariant

Cilium eBPF Host-Routing Node-to-Node WireGuard Mesh & Pod Identity Guardrail

Enforces in-kernel cryptographic mesh encapsulation and transparent egress pod identity verification via Cilium eBPF host routing and WireGuard. Eliminates user-space proxy performance degradation by bypassing iptables connection tracking and routing encrypted transit directly through native eBPF tc/sockops programs.

Prohibited Anti-Pattern: Routing Node Mesh Traffic Through User-Space Proxies or Forcing Conntrack Decryption Fallbacks

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Cilium eBPF Host-Routing Node-to-Node WireGuard Mesh & Pod Identity Guardrail - Enforces in-kernel cryptographic mesh encapsulation and transparent egress pod identity verification via Cilium eBPF host routing and WireGuard. Eliminates user-space proxy performance degradation by bypassing iptables connection tracking and routing encrypted transit directly through native eBPF tc/sockops programs.
globs: charts/cilium/**/*.yaml, helm/**/*.yaml, deploy/cilium/**/*.yaml, infra/k8s/**/*.yaml, k8s/**/*.yaml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/cilium-ebpf-host-routing-wireguard-invariant"
---

# Cilium eBPF Host-Routing Node-to-Node WireGuard Mesh & Pod Identity Guardrail

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Routing Node Mesh Traffic Through User-Space Proxies or Forcing Conntrack Decryption Fallbacks

## System Constraints
You are a Principal Infrastructure Architect enforcing strict network datapath performance and cryptographic transit invariants in Kubernetes. Mandate Cilium eBPF Host-Routing with native Node-to-Node WireGuard encryption. Prevent user-space proxy routing bottlenecks (e.g., standard IPsec or user-space WireGuard tunnels), prohibit iptables conntrack overhead, and ensure egress pod identity labels remain preserved and verified across encrypted overlays without payload transformation.

## Strict Guidelines
- Engineers MUST ALWAYS configure `tunnelProtocol: "none"` or native routing mode combined with `bpf.masquerade=true` and `bpf.hostRouting=true` when enabling Cilium WireGuard encryption.
- Engineers MUST ALWAYS enable `encryption.enabled=true` with `encryption.type=wireguard` and `encryption.wireguard.userspaceFallback=false` to guarantee in-kernel cryptographic processing.
- Engineers MUST NOT allow MTU misalignments; MTU calculations MUST explicitly subtract the 60-byte WireGuard overhead (or 80 bytes with IPv6) from the native network interface MTU.
- Services MUST preserve endpoint identity across pod-to-pod and node-to-node hops by retaining `encryption.wireguard.encryptPodTraffic=true` without traversing legacy iptables kube-proxy chains.
- Components NEVER fall back to legacy kube-proxy; clusters MUST enforce `kubeProxyReplacement=true` with strict host-reachable services (`hostServices.enabled=true`) to avoid user-space socket context switches.

## Bad vs Good Implementations
### Cilium Helm Values: Insecure/Degraded Legacy Proxy Configuration vs. In-Kernel eBPF WireGuard Routing

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Relies on kube-proxy and VXLAN encapsulation stacked on top of IPsec encryption without eBPF host routing. This forces network packets through the kernel netfilter/iptables stack and connection tracking subsystems, causing severe CPU spikes and latency degradation while stripping granular egress pod identity verification.
```yaml
# Anti-Pattern: User-space kube-proxy fallback with IPsec overhead and unoptimized MTU
kubeProxyReplacement: "false"
enablingHostRouting: false
enclosingMasquerade: false
routingMode: tunnel
tunnelProtocol: vxlan

encryption:
  enabled: true
  type: ipsec # Induces high user-space IPsec/conntrack CPU overhead
  ipsec:
    keyFile: "cilium-ipsec-keys"

bpf:
  masquerade: false
  hostRouting: false
```

#### Production Standard (Correct)
> **Standard**: Enforces complete kube-proxy replacement via eBPF host routing, direct node routing without unnecessary VXLAN encapsulation, and in-kernel WireGuard cryptographic mesh. This maximizes packet-per-second (PPS) throughput, transparently preserves pod security identities across nodes, and prevents netfilter connection-tracking bottlenecks.
```yaml
# Production Invariant: In-kernel eBPF Direct Host-Routing with Native WireGuard Mesh
kubeProxyReplacement: true
routingMode: native
ipv4NativeRoutingCIDR: "10.244.0.0/16"
autoDirectNodeRoutes: true

bpf:
  masquerade: true
  hostRouting: true
  tproxy: true

enryption:
  enabled: true
  type: wireguard
  wireguard:
    userspaceFallback: false
    encryptPodTraffic: true
    encryptNodeTraffic: true

# Interface MTU: 9000 (Jumbo frame) minus 60 bytes WireGuard overhead
mtu: 8940
```
Recommended MCP Servers (mcp-serverlist.com)

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

Kubernetes Cluster Inspector
Validates live Cilium ConfigMaps, Helm releases, and CiliumNode CRDs across production clusters.
Recommended Agent Skills (askills.dev)

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

Cilium CLI Verification Tool
Executes 'cilium bpf tunnel list' and 'cilium status --verbose' to verify WireGuard datapath invariants directly within nodes.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Host-Routing Node-to-Node WireGuard Mesh & Pod Identity Guardrail

Cilium eBPF Host-Routing Node-to-Node WireGuard Mesh & Pod Identity Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces in-kernel cryptographic mesh encapsulation and transparent egress pod identity verification via Cilium eBPF host routing and WireGuard. Eliminates user-space proxy performance degradation by bypassing iptables connection tracking and routing encrypted transit directly through native eBPF tc/sockops programs. 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: Routing Node Mesh Traffic Through User-Space Proxies or Forcing Conntrack Decryption Fallbacks 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 DriftRouting Node Mesh Traffic Through User-Space Proxies or Forcing Conntrack Decryption FallbacksCritical
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 configure `tunnelProtocol

Engineers MUST ALWAYS configure `tunnelProtocol: "none"` or native routing mode combined with `bpf.masquerade=true` and `bpf.hostRouting=true` when enabling Cilium WireGuard encryption.

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 enable `encryption.enabled=true` with `encryption.type=wireguard` and `encryption.wireguard.userspaceFallback=false` to guarantee in-kernel cryptographic processing.

Engineers MUST ALWAYS enable `encryption.enabled=true` with `encryption.type=wireguard` and `encryption.wireguard.userspaceFallback=false` to guarantee in-kernel cryptographic processing.

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 allow MTU misalignments

Engineers MUST NOT allow MTU misalignments; MTU calculations MUST explicitly subtract the 60-byte WireGuard overhead (or 80 bytes with IPv6) from the native network interface MTU.

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 MUST preserve endpoint identity across pod-to-pod and node-to-node hops by retaining `encryption.wireguard.encryptPodTraffic=true` without traversing legacy iptables kube-proxy chains.

Services MUST preserve endpoint identity across pod-to-pod and node-to-node hops by retaining `encryption.wireguard.encryptPodTraffic=true` without traversing legacy iptables kube-proxy chains.

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 fall back to legacy kube-proxy

Components NEVER fall back to legacy kube-proxy; clusters MUST enforce `kubeProxyReplacement=true` with strict host-reachable services (`hostServices.enabled=true`) to avoid user-space socket context switches.

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 Cilium eBPF Host-Routing Node-to-Node WireGuard Mesh & Pod Identity Guardrail critical for AI coding assistants?

Enforces in-kernel cryptographic mesh encapsulation and transparent egress pod identity verification via Cilium eBPF host routing and WireGuard. Eliminates user-space proxy performance degradation by bypassing iptables connection tracking and routing encrypted transit directly through native eBPF tc/sockops programs. 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 (Routing Node Mesh Traffic Through User-Space Proxies or Forcing Conntrack Decryption Fallbacks) 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

Cilium