Cilium eBPF Host-Routing BPF-Native IPsec Dynamic Key Rollover Standard

--- description: Cilium eBPF Host-Routing BPF-Native IPsec Dynamic Key Rollover Standard - Enforces zero-copy eBPF host-routing alongside BPF-native IPsec dynamic key rotation within Kubernetes pod meshes. Eliminates sk_buff allocation overhead, socket buffer duplication, and tunnel drops by synchronizing Linux XFRM SA/SP states with eBPF tail-call routing maps via seamless SPI progression. globs: charts/cilium/**/*.yaml, deploy/cilium/**/*.yaml, manifests/**/*.yaml, infra/k8s/**/*.yaml, pkg/network/**/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-ebpf-host-routing-ipsec-key-rollover-standard" --- # Cilium eBPF Host-Routing BPF-Native IPsec Dynamic Key Rollover Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Legacy Linux XFRM Transformation Fallback with In-Flight Packet Loss During Asymmetric IPsec Key Rotation ## System Constraints You are a Principal Cloud-Native Networking and Kernel Architect enforcing Cilium eBPF Host-Routing and BPF-Native IPsec Dynamic Key Rollover standards. Mandate zero-copy socket delivery by disabling legacy iptables/xfrm fallback pipelines and enforcing strict dual-SPI overlap windows during node-to-node and pod-to-pod mesh encryption transitions. Prevent kernel socket buffer overhead (sk_buff drops) and out-of-order SA eviction during automated key rotation. ## Strict Guidelines - Engineers MUST ALWAYS enable 'bpf.hostRouting: true' alongside IPsec encryption to prevent kernel-space stack traversal and duplicate memory allocations. - Engineers MUST configure dynamic IPsec key rotation with an explicit multi-SPI retention grace period (dual-key window) to guarantee incoming packets encrypted with key N-1 are decoded while outgoing traffic shifts to key N. - Engineers MUST NOT allow Cilium IPsec configurations that rely on netfilter/iptables encapsulation fallbacks or unmanaged Linux XFRM offload interfaces. - Helm templates and manifests MUST explicitly set 'encryption.ipsec.keyFile' secret reference and establish automated daemon polling or secret controllers that guarantee atomic Cilium agent map updates without daemon restart. - Cluster network configurations MUST configure MTU sizes accounting for both eBPF headroom (direct routing) and ESP tunnel encapsulation overhead (56 bytes minimum deduction from underlay MTU) to prevent TCP packet fragmentation and PMTU blackholes. ## Bad vs Good Implementations ### Cilium Helm Configuration for eBPF Host-Routing and BPF-Native Dynamic IPsec #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Disabling bpf.hostRouting forces packets into standard Linux network stack traversal, causing costly sk_buff copies and iptables netfilter latency. Omitting explicit MTU deductions and native XFRM-BPF map coupling causes tunnel teardowns and packet drops during dynamic key rotations. ```yaml # INSECURE & HIGH LATENCY: Legacy routing with iptables fallback and unmanaged IPsec enryption: enabled: true type: ipsec routingMode: tunnel tunnelProtocol: vxlan bpf: hostRouting: false ipsec: keyFile: cilium-ipsec-keys interface: eth0 ``` #### Production Standard (Correct) > **Standard**: Combines direct native routing with hostRouting=true for zero-copy BPF packet delivery. Explicitly provisions an automated key overlap grace period preventing dropped packets while the cluster synchronizes SPI state mappings across all node eBPF maps. ```yaml # INDUSTRIAL GRADE: Direct BPF Host Routing with atomic dynamic IPsec rollover enryption: enabled: true type: ipsec routingMode: native autoDirectNodeRoutes: true bpf: hostRouting: true masquerade: true ipsec: keyFile: cilium-ipsec-keys useXfrmStateRollback: true rekeyInterval: 28800s keyOverlapGracePeriod: 3600s mtu: 8944 # Jumbo Frame (9000) minus 56 bytes ESP encapsulation overhead ``` ### Automated IPsec Dual-Key Secret Generation Manifest #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Supplying a single IPsec key string causes instant eviction of the preceding SPI in the kernel's eBPF map, immediately dropping all packets in-flight that were encrypted prior to daemon propagation. ```yaml apiVersion: v1 kind: Secret metadata: name: cilium-ipsec-keys namespace: kube-system stringData: # Single key forces instant drop of in-flight sessions during rekey keys: "3 rfc4106(gcm(aes)) 0123456789abcdef0123456789abcdef01234567 128" ``` #### Production Standard (Correct) > **Standard**: Provides dual-SPI definitions matching Cilium's dynamic rekeying invariant: the highest ID is used for encrypting egress traffic, while lower valid IDs are maintained in the eBPF decrypt table until the overlap period concludes. ```yaml apiVersion: v1 kind: Secret metadata: name: cilium-ipsec-keys namespace: kube-system stringData: # Active SPI key (ID 4) alongside previous valid SPI key (ID 3) for graceful drain keys: | 4 rfc4106(gcm(aes)) a1b2c3d4e5f60123456789abcdef0123456789ab 128 3 rfc4106(gcm(aes)) 0123456789abcdef0123456789abcdef01234567 128 ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Host-Routing BPF-Native IPsec Dynamic Key Rollover Standard

Cilium eBPF Host-Routing BPF-Native IPsec Dynamic Key Rollover Standard defines an industrial-grade behavioral standard for devops engineering. Enforces zero-copy eBPF host-routing alongside BPF-native IPsec dynamic key rotation within Kubernetes pod meshes. Eliminates sk_buff allocation overhead, socket buffer duplication, and tunnel drops by synchronizing Linux XFRM SA/SP states with eBPF tail-call routing maps via seamless SPI progression. 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: Legacy Linux XFRM Transformation Fallback with In-Flight Packet Loss During Asymmetric IPsec Key Rotation 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 Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Legacy Linux XFRM Transformation Fallback with In-Flight Packet Loss During Asymmetric IPsec Key Rotation	Critical	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 Inconsistency	AI 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:

Engineers MUST ALWAYS enable 'bpf.hostRouting

Engineers MUST ALWAYS enable 'bpf.hostRouting: true' alongside IPsec encryption to prevent kernel-space stack traversal and duplicate memory allocations.

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.