eBPF AF_XDP Zero-Copy Ingress Steering & UMEM Lifecycle Invariants

--- description: eBPF AF_XDP Zero-Copy Ingress Steering & UMEM Lifecycle Invariants - Enforces deterministic kernel bypass for L7 microservice ingress via AF_XDP (XSK) zero-copy mode directly to user-space proxy buffers. Prevents silent fallback to SKB copy mode, ensures strict 1:1 hardware RX queue-to-worker core pinning, and guarantees descriptor fill-ring replenishment before RX ring consumption to prevent packet drops under microbursts. globs: bpf/**/*.{c,h}, src/**/*.{c,cpp,rs}, envoy/**/*.{yaml,json}, deploy/daemonsets/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-af-xdp-zerocopy-ingress-standard" --- # eBPF AF_XDP Zero-Copy Ingress Steering & UMEM Lifecycle Invariants > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Silent Fallback to SKB Copy Mode and Unsynchronized UMEM Ring Starvation in Kernel Bypass Ingress ## System Constraints You are a Principal Infrastructure & Systems Architect enforcing eBPF AF_XDP Kernel Bypass Zero-Copy Ingress Steering Standards. Mandate absolute zero-copy (XDP_ZEROCOPY) validation, hugepage-backed UMEM alignment, dedicated queue-to-core affinity, and continuous Fill Ring replenishment. ## Strict Guidelines - Engineers MUST ALWAYS enforce the `XDP_ZEROCOPY` bind flag explicitly in socket creation; implicit fallback to `XDP_COPY` or SKB emulation MUST result in an immediate fatal process exit. - Engineers MUST allocate UMEM memory exclusively from 2MB or 1GB hugepages (`mmap` with `MAP_HUGETLB`), aligned strictly to NIC memory chunk boundaries (2048 or 4096 bytes) with configured `XDP_PACKET_HEADROOM`. - eBPF XDP programs MUST steer traffic using `bpf_redirect_map` referencing a `BPF_MAP_TYPE_XSKMAP` keyed strictly by `ctx->rx_queue_index`, dropping unmapped packets with `XDP_ABORTED` or explicit metrics rather than falling through to the kernel network stack. - Worker runtimes MUST replenish the UMEM Fill Ring (`xsk_ring_prod__reserve` and `xsk_ring_prod__submit`) before consuming descriptors from the RX Ring (`xsk_ring_cons__peek`), preventing NIC RX ring starvation under microbursts. - Kubernetes DaemonSets and Envoy host configurations MUST enable `CAP_NET_ADMIN`, `CAP_SYS_ADMIN` (or `CAP_BPF`), configure CPU core pinning with `taskset`/isolcpus, and disable NIC LRO/GRO offloads (`ethtool -K <iface> gro off lro off`) to prevent packet aggregation before XDP processing. ## Bad vs Good Implementations ### eBPF Kernel XSK Ingress Redirection and User-Space Socket Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing XDP_PASS as a fallback redirects unsteered traffic into the slow Linux network stack instead of halting or alerting on misconfiguration. Omitting explicit XDP_ZEROCOPY bind flags in user space allows drivers to silently downgrade to XDP_COPY mode with heavy memcpy overhead. ```c // BAD: Fallback to copy mode, missing RX queue validation, and unconstrained fallthrough #include <linux/bpf.h> #include <bpf/bpf_helpers.h> struct { __uint(type, BPF_MAP_TYPE_XSKMAP); __uint(max_entries, 64); __uint(key_size, sizeof(__u32)); __uint(value_size, sizeof(__u32)); } xsks_map SEC(".maps"); SEC("xdp") int xdp_ingress_prog(struct xdp_md *ctx) { __u32 index = ctx->rx_queue_index; // Blind redirect without checking map existence; falls back to default stack on failure bpf_redirect_map(&xsks_map, index, XDP_PASS); return XDP_PASS; // Silent fallback to kernel TCP/IP stack causes severe latency degradation } // User-space socket setup without enforcing ZEROCOPY // int xsk_socket__create(&xsk, ifname, queue_id, umem, &rx, &tx, &cfg); // cfg.bind_flags = 0 ``` #### Production Standard (Correct) > **Standard**: Validates that an active AF_XDP socket exists in the XSKMAP for the exact hardware RX queue ID, drops unmatched traffic to prevent stack pollution, and mandates zero-copy flags in user-space initialization to eliminate memory copies. ```c // GOOD: Strict zero-copy ingress assertion, queue validation, and deterministic redirection #include <linux/bpf.h> #include <bpf/bpf_helpers.h> struct { __uint(type, BPF_MAP_TYPE_XSKMAP); __uint(max_entries, 64); __uint(key_size, sizeof(__u32)); __uint(value_size, sizeof(__u32)); } xsks_map SEC(".maps"); SEC("xdp") int xdp_ingress_prog(struct xdp_md *ctx) { __u32 qid = ctx->rx_queue_index; // Verify socket presence for this specific hardware RX queue if (bpf_map_lookup_elem(&xsks_map, &qid)) { return bpf_redirect_map(&xsks_map, qid, XDP_DROP); } // Unmapped queues must be explicitly dropped to protect kernel stack from packet flooding return XDP_DROP; } // User-space socket configuration requires: // cfg.bind_flags = XDP_ZEROCOPY | XDP_USE_NEED_WAKEUP; // if (xsk_socket__create(...) < 0) { abort(); /* Fail fast if zero-copy is unsupported */ } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF AF_XDP Zero-Copy Ingress Steering & UMEM Lifecycle Invariants

eBPF AF_XDP Zero-Copy Ingress Steering & UMEM Lifecycle Invariants defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic kernel bypass for L7 microservice ingress via AF_XDP (XSK) zero-copy mode directly to user-space proxy buffers. Prevents silent fallback to SKB copy mode, ensures strict 1:1 hardware RX queue-to-worker core pinning, and guarantees descriptor fill-ring replenishment before RX ring consumption to prevent packet drops under microbursts. 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: Silent Fallback to SKB Copy Mode and Unsynchronized UMEM Ring Starvation in Kernel Bypass Ingress 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	Silent Fallback to SKB Copy Mode and Unsynchronized UMEM Ring Starvation in Kernel Bypass Ingress	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 enforce the `XDP_ZEROCOPY` bind flag explicitly in socket creation

Engineers MUST ALWAYS enforce the `XDP_ZEROCOPY` bind flag explicitly in socket creation; implicit fallback to `XDP_COPY` or SKB emulation MUST result in an immediate fatal process exit.

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.