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: ebpf-cilium-xdp-wireguard-egress-guardrail

Hardware-Accelerated eBPF Cilium XDP WireGuard Transit Encryption Standard

Enforces deterministic, hardware-accelerated pod-to-pod WireGuard transit encryption executed directly within the native NIC XDP (eXpress Data Path) hook before SKB (socket buffer) allocation in the Linux network stack. Prevents unencrypted packet leakage, kernel context-switch latency penalties, and fallbacks to user-space network queuing for sensitive inter-node workloads.

Prohibited Anti-Pattern: Bypassing Native Driver XDP Hooks Resulting in SKB Allocation, Kernel Stack Context Switching, or Plaintext Egress Leakage

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Hardware-Accelerated eBPF Cilium XDP WireGuard Transit Encryption Standard - Enforces deterministic, hardware-accelerated pod-to-pod WireGuard transit encryption executed directly within the native NIC XDP (eXpress Data Path) hook before SKB (socket buffer) allocation in the Linux network stack. Prevents unencrypted packet leakage, kernel context-switch latency penalties, and fallbacks to user-space network queuing for sensitive inter-node workloads.
globs: helm/cilium/values.yaml, k8s/network-policies/**/*.yaml, deploy/cilium/**/*.yaml, infra/terraform/modules/cilium/*.tf
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/ebpf-cilium-xdp-wireguard-egress-guardrail"
---

# Hardware-Accelerated eBPF Cilium XDP WireGuard Transit Encryption Standard

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Bypassing Native Driver XDP Hooks Resulting in SKB Allocation, Kernel Stack Context Switching, or Plaintext Egress Leakage

## System Constraints
You are a Principal Infrastructure Architect enforcing strict eBPF Cilium XDP kernel-offloaded WireGuard transit encryption invariants. All inter-node pod communications MUST bypass traditional Linux SKB memory allocation and execute encryption directly at the native driver or hardware-offloaded XDP ingress/egress layers. You MUST prohibit generic generic-XDP fallback, reject configurations missing explicit node-to-node encryption mandates, and verify strict eBPF map integrity to prevent packet leaks under link saturation or route invalidation.

## Strict Guidelines
- Engineers MUST ALWAYS configure Cilium with 'encryption.enabled=true', 'encryption.type=wireguard', and 'encryption.wireguard.userspaceFallback=false' to strictly enforce kernel-space cryptographic routines.
- Engineers MUST configure Cilium XDP mode to 'native' or 'offload' (e.g., 'loadBalancer.acceleration=native') and verify underlying NIC driver support (e.g., mlx5, i40e) to prevent degradation to generic socket buffer-based XDP.
- Configurations MUST enforce egress policy drops ('bpf.masquerade=true' combined with strict egress CiliumNetworkPolicies) ensuring no non-WireGuard UDP port 51871 or unencrypted pod CIDR traffic can exit via host devices.
- Engineers MUST NOT disable 'bpf.hostLegacyRouting' without verifying eBPF Host-Routing compatibility, and MUST NEVER allow unencrypted fallback tunnels (e.g., Geneve/VXLAN without IPsec/WireGuard wrapping).
- Services MUST declare explicit CiliumNetworkPolicy resources with cryptographic transport assertion mandates, rejecting any insecure inter-node egress path prior to L3/L4 routing evaluation.

## Bad vs Good Implementations
### Cilium Helm Configuration: Native XDP Acceleration with Strict WireGuard Enforcement

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Configuring 'loadBalancer.acceleration: generic' defeats hardware-accelerated eBPF by forcing socket buffer allocation (SKB) inside the Linux kernel stack. Lacking explicit enforcement against userspace fallback and using generic tunnel fallbacks risks unencrypted packet leakage upon transient cryptographic handshake failure.
```yaml
# INSECURE: Generic XDP fallback enabled, no driver offload, permits userspace fallback and legacy routing
enableIPv4Masquerade: false
enableIdentityMark: false
encryption:
  enabled: true
  type: wireguard
  # Missing strict userspace fallback prevention
loadBalancer:
  acceleration: generic # Forces slow socket-buffer (SKB) path allocation in kernel
routingMode: tunnel
tunnelProtocol: vxlan # Sends unencrypted vxlan encapsulation if wireguard key drops
```

#### Production Standard (Correct)
> **Standard**: Setting 'loadBalancer.acceleration: native', disabling host legacy routing, and enabling native WireGuard node encryption guarantees that pod egress packets are encrypted via eBPF directly at the driver level without hitting host socket allocations or risking unencrypted egress bypass.
```yaml
# SECURE: Native Driver XDP Offloaded WireGuard with Zero Socket Allocation
enableIPv4Masquerade: true
bpf:
  masquerade: true
  hostLegacyRouting: false # Bypasses Linux IP stack via direct eBPF routing
encryption:
  enabled: true
  type: wireguard
  wireguard:
    userspaceFallback: false
    nodeEncryption: true
loadBalancer:
  mode: dsr
  acceleration: native # Executes at NIC driver XDP hook prior to SKB allocation
routingMode: native
ipv4NativeRoutingCIDR: "10.244.0.0/16"
```

### CiliumNetworkPolicy Egress Guardrail: Enforcing Encrypted Transits

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Entity-based 'cluster' egress without cryptographic transport constraint allows endpoints to communicate across nodes even if WireGuard kernel state fails or unencrypted fallback occurs.
```yaml
apiVersion: "cilium.io/v2"
kind: CiliumNetworkPolicy
metadata:
  name: allow-inter-node-traffic
spec:
  endpointSelector:
    matchLabels:
      security-zone: pci-dss
  egress:
  - toEntities:
    - cluster # Overly permissive; permits egress regardless of link encryption verification
```

#### Production Standard (Correct)
> **Standard**: Mandates strict transit identity match on encrypted pods ('io.cilium.k8s.policy.encrypted: true') over defined endpoints, ensuring that any unencrypted packet or failed XDP interface drops immediately at the egress map lookup.
```yaml
apiVersion: "cilium.io/v2"
kind: CiliumNetworkPolicy
metadata:
  name: strict-wireguard-inter-node-traffic
spec:
  endpointSelector:
    matchLabels:
      security-zone: pci-dss
  egress:
  - toEndpoints:
    - matchLabels:
      io.cilium.k8s.policy.encrypted: "true"
      security-zone: pci-dss
    toPorts:
    - ports:
      - port: "443"
        protocol: TCP
```
Recommended MCP Servers (mcp-serverlist.com)

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

Cilium eBPF Runtime Inspector
Validates active eBPF maps, XDP hook attachment modes, and WireGuard kernel peering keys across physical NIC interfaces.
Recommended Agent Skills (askills.dev)

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

bpftool XDP Driver Verifier
CLI automation skill to query netdev XDP status, verify driver-level program attachments, and assert zero generic-mode eBPF fallbacks.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Accelerated eBPF Cilium XDP WireGuard Transit Encryption Standard

Hardware-Accelerated eBPF Cilium XDP WireGuard Transit Encryption Standard defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic, hardware-accelerated pod-to-pod WireGuard transit encryption executed directly within the native NIC XDP (eXpress Data Path) hook before SKB (socket buffer) allocation in the Linux network stack. Prevents unencrypted packet leakage, kernel context-switch latency penalties, and fallbacks to user-space network queuing for sensitive inter-node workloads. 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: Bypassing Native Driver XDP Hooks Resulting in SKB Allocation, Kernel Stack Context Switching, or Plaintext Egress Leakage 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 DriftBypassing Native Driver XDP Hooks Resulting in SKB Allocation, Kernel Stack Context Switching, or Plaintext Egress LeakageCritical
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 Cilium with 'encryption.enabled=true', 'encryption.type=wireguard', and 'encryption.wireguard.userspaceFallback=false' to strictly enforce kernel-space cryptographic routines.

Engineers MUST ALWAYS configure Cilium with 'encryption.enabled=true', 'encryption.type=wireguard', and 'encryption.wireguard.userspaceFallback=false' to strictly enforce kernel-space cryptographic routines.

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 configure Cilium XDP mode to 'native' or 'offload' (e.g., 'loadBalancer.acceleration=native') and verify underlying NIC driver support (e.g., mlx5, i40e) to prevent degradation to generic socket buffer-based XDP.

Engineers MUST configure Cilium XDP mode to 'native' or 'offload' (e.g., 'loadBalancer.acceleration=native') and verify underlying NIC driver support (e.g., mlx5, i40e) to prevent degradation to generic socket buffer-based XDP.

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

Configurations MUST enforce egress policy drops ('bpf.masquerade=true' combined with strict egress CiliumNetworkPolicies) ensuring no non-WireGuard UDP port 51871 or unencrypted pod CIDR traffic can exit via host devices.

Configurations MUST enforce egress policy drops ('bpf.masquerade=true' combined with strict egress CiliumNetworkPolicies) ensuring no non-WireGuard UDP port 51871 or unencrypted pod CIDR traffic can exit via host devices.

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 disable 'bpf.hostLegacyRouting' without verifying eBPF Host-Routing compatibility, and MUST NEVER allow unencrypted fallback tunnels (e.g., Geneve/VXLAN without IPsec/WireGuard wrapping).

Engineers MUST NOT disable 'bpf.hostLegacyRouting' without verifying eBPF Host-Routing compatibility, and MUST NEVER allow unencrypted fallback tunnels (e.g., Geneve/VXLAN without IPsec/WireGuard wrapping).

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

Services MUST declare explicit CiliumNetworkPolicy resources with cryptographic transport assertion mandates, rejecting any insecure inter-node egress path prior to L3/L4 routing evaluation.

Services MUST declare explicit CiliumNetworkPolicy resources with cryptographic transport assertion mandates, rejecting any insecure inter-node egress path prior to L3/L4 routing evaluation.

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 Hardware-Accelerated eBPF Cilium XDP WireGuard Transit Encryption Standard critical for AI coding assistants?

Enforces deterministic, hardware-accelerated pod-to-pod WireGuard transit encryption executed directly within the native NIC XDP (eXpress Data Path) hook before SKB (socket buffer) allocation in the Linux network stack. Prevents unencrypted packet leakage, kernel context-switch latency penalties, and fallbacks to user-space network queuing for sensitive inter-node workloads. 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 (Bypassing Native Driver XDP Hooks Resulting in SKB Allocation, Kernel Stack Context Switching, or Plaintext Egress Leakage) 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

Hardware-Accelerated