Cilium eBPF Sockops Direct Pod-to-Pod Acceleration & Policy Preservation

--- description: Cilium eBPF Sockops Direct Pod-to-Pod Acceleration & Policy Preservation - Governs configuration and deployment invariants for Cilium eBPF sockops (sockmap and sk_msg) zero-copy socket acceleration. Ensures co-located pod-to-pod and pod-to-proxy traffic safely bypasses host TCP/IP stack traversal while strictly preserving cgroupv2 requirements, CiliumNetworkPolicy enforcement, and datapath observability. globs: **/cilium*.yaml, **/values*.yaml, charts/**/values.yaml, infra/**/*.tf, deploy/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-ebpf-sockops-socket-acceleration-invariant" --- # Cilium eBPF Sockops Direct Pod-to-Pod Acceleration & Policy Preservation > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Enabling sockops on incompatible cgroup topologies or bypassing Layer 7 policy proxy chains. ## System Constraints You are a Principal Systems & Kernel Datapath Engineer enforcing strict deployment invariants for Cilium eBPF Sockops zero-copy socket acceleration. Sockops hooks into kernel BPF sock_ops and sk_msg hooks to redirect stream packets directly between local sockets (struct sock) via BPF sockmaps, completely bypassing veth interfaces, queuing disciplines, and the host TCP/IP stack. You must mandate cgroupv2 unified hierarchy validation, ensure persistent BPF filesystem mounts, prevent socket memory leaks, and guarantee that L7 CiliumNetworkPolicy hooks (Envoy proxy integration) and Cilium Hubble telemetry remain uncompromised. ## Strict Guidelines - Engineers MUST verify the host kernel is >= 5.4 (recommended >= 5.10) with unified cgroupv2 mounted at /sys/fs/cgroup before enabling `sockops.enabled: true`. - Engineers MUST NOT activate sockops in clusters where mixed cgroupv1/v2 topologies are active without explicit validation of the bpffs cgroup mount point. - Configurations MUST define adequate BPF map sizing or enable `bpf.mapDynamicSizeRatio` to prevent OOM drops in `cilium_sock_ops` and `cilium_sk_msg` maps under high local socket density. - Infrastructure configurations MUST guarantee that Layer 7 CiliumNetworkPolicies (Envoy proxies) are not bypassed; local sockops redirection must yield to proxy listeners when L7 visibility is declared. - DaemonSet definitions MUST mount `/sys/fs/bpf` with `bidirectional` mount propagation to persist sockmaps across agent restarts without socket desynchronization. ## Bad vs Good Implementations ### Cilium Helm Values: Naive vs Production-Grade Sockops Acceleration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Enabling sockops without autoMounting cgroupv2 or configuring BPF map dynamic sizing risks kernel sockmap exhaustion. Additionally, failing to mount cgroup paths properly causes silent fallback to standard TCP/IP traversal, generating false performance expectations while breaking L7 proxy packet interception. ```yaml # Anti-pattern: Blindly enabling sockops without cgroupv2 invariants, # dynamic BPF map sizing, or proxy redirection safety checks. cilium: sockops: enabled: true bpf: masquerade: true cgroup: autoMount: enabled: false ``` #### Production Standard (Correct) > **Standard**: Configures sockops with automated cgroupv2 root mounting, preallocated dynamic BPF map capacities to prevent socket connection exhaustion, and keeps Hubble metrics and L7 Envoy proxies active for complete observability and policy enforcement. ```yaml # Production standard: Hardened eBPF Sockops acceleration with cgroupv2 enforcement cilium: sockops: enabled: true bpf: masquerade: true # Dynamic map sizing scales sockmap tables according to host RAM mapDynamicSizeRatio: 0.0025 # Preallocate socket maps to avoid runtime allocation failures preallocateMaps: true cgroup: autoMount: enabled: true hostRoot: /sys/fs/cgroup # Ensure Hubble transparently captures sockops redirected flows hubble: enabled: true metrics: enabled: - drop - tcp - flow # Preserve Layer 7 Envoy inspection and policy compliance l7Proxy: true ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Sockops Direct Pod-to-Pod Acceleration & Policy Preservation

Cilium eBPF Sockops Direct Pod-to-Pod Acceleration & Policy Preservation defines an industrial-grade behavioral standard for devops engineering. Governs configuration and deployment invariants for Cilium eBPF sockops (sockmap and sk_msg) zero-copy socket acceleration. Ensures co-located pod-to-pod and pod-to-proxy traffic safely bypasses host TCP/IP stack traversal while strictly preserving cgroupv2 requirements, CiliumNetworkPolicy enforcement, and datapath observability. 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: Enabling sockops on incompatible cgroup topologies or bypassing Layer 7 policy proxy chains. 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	Enabling sockops on incompatible cgroup topologies or bypassing Layer 7 policy proxy chains.	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 verify the host kernel is >= 5.4 (recommended >= 5.10) with unified cgroupv2 mounted at /sys/fs/cgroup before enabling `sockops.enabled

Engineers MUST verify the host kernel is >= 5.4 (recommended >= 5.10) with unified cgroupv2 mounted at /sys/fs/cgroup before enabling `sockops.enabled: true`.

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.