Cilium eBPF XDP Hardware-Offloaded Layer-4 Filter Invariant

Enforces Cilium eBPF XDP (eXpress Data Path) acceleration at the NIC driver or SmartNIC hardware level to intercept and drop volumetric SYN floods and malformed L4 packets prior to kernel socket buffer (sk_buff) allocation. Bypassing socket buffer allocation is mandatory to eliminate memory exhaustion, softirq contention, and OS kernel lock serialization under extreme packet-per-second (Mpps) DDoS conditions. All network policies targeting border ingress interfaces must validate XDP hardware/driver mode compatibility and fail closed.

--- description: Cilium eBPF XDP Hardware-Offloaded Layer-4 Filter Invariant - Enforces Cilium eBPF XDP (eXpress Data Path) acceleration at the NIC driver or SmartNIC hardware level to intercept and drop volumetric SYN floods and malformed L4 packets prior to kernel socket buffer (sk_buff) allocation. Bypassing socket buffer allocation is mandatory to eliminate memory exhaustion, softirq contention, and OS kernel lock serialization under extreme packet-per-second (Mpps) DDoS conditions. All network policies targeting border ingress interfaces must validate XDP hardware/driver mode compatibility and fail closed. globs: helm/cilium/values.yaml, deploy/cilium/**/*.yaml, k8s/**/*.yaml, infra/terraform/**/*.tf, charts/cilium/values*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-ebpf-xdp-hardware-offload-l4-filter-invariant" --- # Cilium eBPF XDP Hardware-Offloaded Layer-4 Filter Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Processing Ingress L4 Traffic via iptables, IPVS, or Standard TC-eBPF Allowing sk_buff Exhaustion Under Volumetric Attacks ## System Constraints You are a Principal Systems & Network Architect enforcing Cilium eBPF XDP hardware-offloaded Layer-4 ingress filter invariants. You must mandate that high-throughput cluster ingress interfaces offload packet parsing and volumetric filtering (such as TCP SYN cookies and malformed packet drops) directly to XDP driver (native) or hardware (offload) hooks before Linux kernel network stack allocation (sk_buff) takes place. Reject any configuration that relies on Linux tc (traffic control) filters alone or userspace firewalls for line-rate volumetric DDoS protection. ## Strict Guidelines - Engineers MUST ALWAYS configure Cilium Helm values with `loadBalancer.acceleration=native` or `loadBalancer.acceleration=best-effort` to ensure XDP driver-level processing on ingress interfaces. - Engineers MUST ALWAYS verify that physical interface drivers support native or offloaded XDP (e.g., mlx5, i40e, ixgbe, ena) before pinning ingress nodes into hardware-drop pools. - Engineers MUST configure `bpf.preallocateMaps=true` and verify `bpf-map-dynamic-size-ratio` to prevent runtime memory allocation latency spikes during high-rate connection floods. - Engineers MUST NOT fallback to generic XDP (`generic` or `disabled`) in production edge gateways where ingress bandwidth exceeds 10 Gbps, as generic XDP incurs sk_buff allocation penalties. - Kubernetes CiliumNetworkPolicy resources MUST NOT rely on userspace L7 proxies (Envoy) to reject volumetric L4 denial-of-service traffic; packet mitigation must occur within the XDP hook via XDP_DROP or XDP_TX. ## Bad vs Good Implementations ### Cilium Helm Configuration: Native XDP Acceleration vs Standard TC Mode #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting XDP acceleration forces Cilium to attach BPF programs at the TC (traffic control) layer. At this layer, the Linux kernel has already allocated an sk_buff data structure for every incoming packet, consuming softirq CPU cycles and kernel memory before packet evaluation, leaving the host vulnerable to volumetric exhaustion. ```yaml # Anti-Pattern: Relies on generic sk_buff allocation and standard TC-level BPF tunnel: disabled autoDirectNodeRoutes: true loadBalancer: mode: dsr # Missing acceleration: defaults to tc (traffic control) hook # Incurs full sk_buff allocation per packet under SYN flood bpf: masquerade: true preallocateMaps: false # Dynamic map expansion leads to memory thrashing during attacks ``` #### Production Standard (Correct) > **Standard**: Configuring `loadBalancer.acceleration: native` ensures the Cilium BPF L4 logic attaches directly to the NIC driver XDP hook. Malformed packets and invalid TCP SYNs are dropped via XDP_DROP before `alloc_skb()` executes, maintaining wire-rate performance and protecting kernel resources. ```yaml # Production Invariant: Hardware/Driver-Offloaded XDP Layer-4 Filter tunnel: disabled autoDirectNodeRoutes: true device: "eth0+" loadBalancer: mode: dsr acceleration: native # Attaches BPF directly to driver XDP ring buffer algorithm: maglev xds: enabled: false bpf: masquerade: true preallocateMaps: true # Eliminates BPF map allocation latency during line-rate floods lbExternalClusterIP: true mapDynamicSizeRatio: 0.0075 ``` ### CiliumNodeConfig Ingress Interface Assertion via Kubernetes Custom Resource #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to declare XDP mode or target interfaces on edge nodes, resulting in unaccelerated TC hook fallback and catastrophic packet drops in softirq under volumetric L4 floods. ```yaml # Anti-Pattern: Unvalidated interface configuration without native acceleration pinning apiVersion: cilium.io/v2 kind: CiliumNodeConfig metadata: name: edge-worker-config namespace: kube-system spec: nodeSelector: matchLabels: node-role.kubernetes.io/edge: "true" defaults: enable-bpf-masquerade: "true" ``` #### Production Standard (Correct) > **Standard**: Explicitly binds edge ingress worker nodes to native XDP acceleration across primary interfaces (`eth0,eth1`) with preallocated BPF maps, guaranteeing pre-sk_buff L4 packet filtering. ```yaml # Production Invariant: Strictly binds edge nodes to native XDP mode on designated interfaces apiVersion: cilium.io/v2 kind: CiliumNodeConfig metadata: name: edge-worker-config namespace: kube-system spec: nodeSelector: matchLabels: node-role.kubernetes.io/edge: "true" defaults: bpf-lb-acceleration: "native" devices: "eth0,eth1" preallocate-bpf-maps: "true" enable-bpf-masquerade: "true" ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF XDP Hardware-Offloaded Layer-4 Filter Invariant

Cilium eBPF XDP Hardware-Offloaded Layer-4 Filter Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces Cilium eBPF XDP (eXpress Data Path) acceleration at the NIC driver or SmartNIC hardware level to intercept and drop volumetric SYN floods and malformed L4 packets prior to kernel socket buffer (sk_buff) allocation. Bypassing socket buffer allocation is mandatory to eliminate memory exhaustion, softirq contention, and OS kernel lock serialization under extreme packet-per-second (Mpps) DDoS conditions. All network policies targeting border ingress interfaces must validate XDP hardware/driver mode compatibility and fail closed. 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: Processing Ingress L4 Traffic via iptables, IPVS, or Standard TC-eBPF Allowing sk_buff Exhaustion Under Volumetric Attacks 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	Processing Ingress L4 Traffic via iptables, IPVS, or Standard TC-eBPF Allowing sk_buff Exhaustion Under Volumetric Attacks	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 Cilium Helm values with `loadBalancer.acceleration=native` or `loadBalancer.acceleration=best-effort` to ensure XDP driver-level processing on ingress interfaces.

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.