Cilium eBPF Ring Buffer Non-Blocking Telemetry & Drop Invariant

--- description: Cilium eBPF Ring Buffer Non-Blocking Telemetry & Drop Invariant - Mandates non-blocking, zero-contention ring buffer reservation patterns across Cilium datapath hooks to prevent kernel latency spikes and packet loss during telemetry saturation. Prohibits blocking calls, retry loops, and packet dropping due to telemetry exhaustion by enforcing atomic metrics increment and immediate event drops under backpressure. globs: bpf/**/*.c, bpf/**/*.h, pkg/datapath/**/*.go, pkg/maps/**/*.go, pkg/bpf/**/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-cilium-ringbuffer-nonblocking-invariant" --- # Cilium eBPF Ring Buffer Non-Blocking Telemetry & Drop Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blocking or Unbounded BPF Ring Buffer Submissions Inducing Datapath Packet Drops Under Ingress Storms ## System Constraints You are a Principal Systems Engineer and Kernel Datapath Architect enforcing eBPF Cilium BPF Ring Buffer Non-Blocking Invariants. Mandate strict lockless reservation semantics, immediate telemetry dropping on buffer saturation, atomic drop-counter accounting, and guaranteed non-interference with forwarding verdicts across all eBPF TC and XDP hooks. ## Strict Guidelines - Engineers MUST ALWAYS use `bpf_ringbuf_reserve` with an immediate NULL verification and non-blocking early return to protect the datapath forwarding path. - Engineers MUST NEVER block, spin, retry, or allocate dynamic kernel memory within XDP or TC datapath handlers when ring buffer capacity is exhausted. - Code MUST atomically increment a local per-CPU map drop counter prior to abandoning telemetry submission when `bpf_ringbuf_reserve` returns NULL. - Services MUST prioritize packet forwarding verdicts (`TC_ACT_OK`, `XDP_PASS`) over telemetry persistence, ensuring that missing telemetry never stalls or drops live traffic. - Components NEVER use `BPF_RB_FORCE_WAKEUP` unconditionally; instead, use `BPF_RB_NO_WAKEUP` or conditional wakeups based on watermarks to avoid catastrophic CPU inter-processor interrupt (IPI) storms. ## Bad vs Good Implementations ### eBPF Datapath Telemetry Emission: Blocking/Dropping Traffic vs Non-Blocking Ring Buffer Reservation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Busy-retrying inside an eBPF datapath hook triggers kernel latency spikes and soft lockups. Dropping the actual network packet (TC_ACT_SHOT) when telemetry fails breaks data plane delivery. Forcing wakeups (BPF_RB_FORCE_WAKEUP) per packet causes severe context-switching overhead and IPI storms. ```c #include <linux/bpf.h> #include <bpf/bpf_helpers.h> #include "types.h" struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 1 << 24); } telemetry_events SEC(".maps"); SEC("tc") int handle_ingress_telemetry(struct __sk_buff *skb) { struct event_t *evt; int retries = 0; // ANTI-PATTERN: Busy-wait retry loop in kernel datapath causes soft lockup while (retries < 3) { evt = bpf_ringbuf_reserve(&telemetry_events, sizeof(*evt), 0); if (evt) { break; } retries++; } // ANTI-PATTERN: Dropping the network packet if telemetry reservation fails if (!evt) { return TC_ACT_SHOT; } evt->sip = skb->remote_ip4; evt->dip = skb->local_ip4; evt->len = skb->len; // ANTI-PATTERN: Forcing wakeups per packet triggers IPI storms under load bpf_ringbuf_submit(evt, BPF_RB_FORCE_WAKEUP); return TC_ACT_OK; } ``` #### Production Standard (Correct) > **Standard**: The good pattern attempts a single non-blocking ring buffer reservation. If saturated, it immediately increments a lockless per-CPU drop counter and forwards the network packet without delay, ensuring kernel stability and zero datapath packet loss during extreme traffic spikes. ```c #include <linux/bpf.h> #include <bpf/bpf_helpers.h> #include "types.h" struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 1 << 24); } telemetry_events SEC(".maps"); struct { __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); __type(key, __u32); __type(value, __u64); __uint(max_entries, 1); } telemetry_drops SEC(".maps"); SEC("tc") int handle_ingress_telemetry(struct __sk_buff *skb) { struct event_t *evt; __u32 drop_key = 0; // GOOD: Lockless, single-attempt reservation evt = bpf_ringbuf_reserve(&telemetry_events, sizeof(*evt), 0); if (!evt) { // GOOD: Non-blocking telemetry drop with per-CPU counter metric tracking __u64 *drops = bpf_map_lookup_elem(&telemetry_drops, &drop_key); if (drops) { __sync_fetch_and_add(drops, 1); } // INVARIANT: Never fail the datapath forwarding verdict due to telemetry saturation return TC_ACT_OK; } evt->sip = skb->remote_ip4; evt->dip = skb->local_ip4; evt->len = skb->len; // GOOD: Let ring buffer adaptive wakeups batch notifications without IPI storms bpf_ringbuf_submit(evt, 0); return TC_ACT_OK; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Ring Buffer Non-Blocking Telemetry & Drop Invariant

Cilium eBPF Ring Buffer Non-Blocking Telemetry & Drop Invariant defines an industrial-grade behavioral standard for devops engineering. Mandates non-blocking, zero-contention ring buffer reservation patterns across Cilium datapath hooks to prevent kernel latency spikes and packet loss during telemetry saturation. Prohibits blocking calls, retry loops, and packet dropping due to telemetry exhaustion by enforcing atomic metrics increment and immediate event drops under backpressure. 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: Blocking or Unbounded BPF Ring Buffer Submissions Inducing Datapath Packet Drops Under Ingress Storms 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	Blocking or Unbounded BPF Ring Buffer Submissions Inducing Datapath Packet Drops Under Ingress Storms	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 use `bpf_ringbuf_reserve` with an immediate NULL verification and non-blocking early return to protect the datapath forwarding path.

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.