Cilium eBPF Host Routing and Socket-Level Zero-Trust Policy Enforcement

--- description: Cilium eBPF Host Routing and Socket-Level Zero-Trust Policy Enforcement - Enforces strict configuration invariants for Cilium eBPF host routing and socket-layer load balancing (sockops/sock_msg). Prevents catastrophic silent policy bypasses, routing deadlocks, and kernel-space connection drops when bypassing the host TCP/IP stack. globs: **/cilium-values*.yaml, **/cilium/**/*.yaml, helm/**/cilium*.yaml, manifests/network/**, deploy/cilium/** alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-bpf-host-routing-socket-invariants" --- # Cilium eBPF Host Routing and Socket-Level Zero-Trust Policy Enforcement > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Partial eBPF Socket-LB Adoption with Incomplete Host-Routing and Conflicting Node iptables Rules ## System Constraints You are a Principal Infrastructure Architect enforcing eBPF Cilium BPF Host Routing and Socket-Level Enforcement Invariants. You must ensure all Cilium deployments bypassing the node TCP/IP stack strictly configure kube-proxy replacement, cgroup2 attachments, MTU alignment, and socket-layer policy enforcement without silent security bypasses or routing loops. ## Strict Guidelines - Engineers MUST ALWAYS configure 'kubeProxyReplacement: true' when enabling 'bpf.hostRouting: true' to avoid dual-stack translation discrepancies between iptables and BPF maps. - Engineers MUST ALWAYS explicitly enable 'socketLB.enabled: true' with 'socketLB.hostNamespaceOnly: false' to guarantee pod-level zero-trust egress evaluation at the socket layer before packet generation. - Engineers MUST NOT rely on default auto-detection for 'cgroup.autoMount.enabled' across mixed Linux kernel versions; explicitly declare cgroup2 mount parameters to ensure attach points for 'cgroup/connect4' and 'cgroup/sock_ops'. - Services using socket-level acceleration MUST declare compatible encapsulation and native routing CIDRs ('routingMode: native' with explicitly configured 'ipv4NativeRoutingCIDR') to prevent BPF tc redirect drops. - Components NEVER attach generic iptables masquerade rules across Cilium-managed veth or host devices; BPF masquerading ('bpf.masquerade: true') MUST be exclusively authoritative. ## Bad vs Good Implementations ### Cilium Helm Configuration for Socket-Level Enforcement and BPF Host Routing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Enabling hostRouting with tunnel mode and partial kube-proxy replacement leads to packet drops on tc egress due to missing tunnel encapsulation within BPF host routing. Restricting socketLB to hostNamespaceOnly leaves pod namespaces unattached from BPF sock_ops, causing node TCP stack overhead and bypassing zero-trust socket-level policies. ```yaml # Insecure and broken: Enables BPF host routing with partial kube-proxy replacement # and unconstrained socketLB, causing silent bypass of egress policies and packet drops. routingMode: tunnel tunnelProtocol: vxlan bpf: hostRouting: true masquerade: false # Incomplete eBPF routing: falls back to node iptables MASQUERADE kubeProxyReplacement: partial socketLB: enabled: true hostNamespaceOnly: true # Fails to enforce egress zero-trust for pod sockets! ``` #### Production Standard (Correct) > **Standard**: This configuration pins native routing with fully managed eBPF host routing, authoritative BPF masquerade, and universal cgroup2 socket load balancing. Egress zero-trust policies are evaluated during socket creation ('connect4/connect6'), bypassing TCP/IP stack overhead without security regressions. ```yaml # Hardened Production Invariant: Direct socket-level zero-trust enforcement # with deterministic native BPF host routing and full kube-proxy replacement. routingMode: native ipv4NativeRoutingCIDR: "10.244.0.0/16" autoDirectNodeRoutes: true kubeProxyReplacement: true bpf: hostRouting: true masquerade: true tproxy: true socketLB: enabled: true hostNamespaceOnly: false # Socket translation attaches to both host and container cgroups cgroup: autoMount: enabled: true hostRoot: /sys/fs/cgroup pmtuDiscovery: enabled: true ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Host Routing and Socket-Level Zero-Trust Policy Enforcement

Cilium eBPF Host Routing and Socket-Level Zero-Trust Policy Enforcement defines an industrial-grade behavioral standard for devops engineering. Enforces strict configuration invariants for Cilium eBPF host routing and socket-layer load balancing (sockops/sock_msg). Prevents catastrophic silent policy bypasses, routing deadlocks, and kernel-space connection drops when bypassing the host TCP/IP stack. 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: Partial eBPF Socket-LB Adoption with Incomplete Host-Routing and Conflicting Node iptables Rules 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	Partial eBPF Socket-LB Adoption with Incomplete Host-Routing and Conflicting Node iptables Rules	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 configure 'kubeProxyReplacement

Engineers MUST ALWAYS configure 'kubeProxyReplacement: true' when enabling 'bpf.hostRouting: true' to avoid dual-stack translation discrepancies between iptables and BPF maps.

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.