eBPF TC Egress Token-Bucket Backpressure & Packet-Drop Signaling

--- description: eBPF TC Egress Token-Bucket Backpressure & Packet-Drop Signaling - Enforces sub-millisecond network egress rate-limiting and congestion backpressure at the kernel Traffic Control (TC) layer via eBPF. Eliminates proxy sidecar memory exhaustion and CPU starvation during egress microbursts by directly engaging kernel TCP congestion control with deterministic drop (TC_ACT_SHOT) or ECN marking. globs: src/**/*.{ts,tsx}, infra/**/*.{ts,js}, daemon/**/*.{ts,js}, k8s/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-tc-egress-backpressure-signaling-standard" --- # eBPF TC Egress Token-Bucket Backpressure & Packet-Drop Signaling > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Delegating High-Throughput Egress Rate Limiting to Userspace Proxy Sidecars Causing OOM Cascades ## System Constraints You are a Principal Software Architect enforcing eBPF TC (Traffic Control) Egress Packet-Drop Backpressure Signaling. Mandate kernel-level egress packet filtering over userspace buffering proxies to prevent resource starvation during microbursts. Ensure token-bucket calculations are atomic, non-routable traffic is bypassed, and backpressure signals directly trigger TCP window scaling. ## Strict Guidelines - Engineers MUST ALWAYS ensure non-routable, ARP, and vital ICMP/ICMPv6 diagnostic frames bypass token bucket drops to prevent cluster network partition. - Engineers MUST NOT buffer high-throughput egress packets in userspace node/container proxies when line-rate egress limits are exceeded. - Code SHOULD prefer IP header ECN (Explicit Congestion Notification) marking before falling back to immediate TC_ACT_SHOT drops to encourage graceful TCP window reduction. - Services MUST manage eBPF rate-limiting maps using BPF_MAP_TYPE_LRU_HASH or atomic token updates with bpf_spin_lock to prevent CPU cache thrashing and race conditions across multi-core systems. - Components NEVER fail closed on eBPF map allocation exhaustion; controllers must gracefully pass non-violating control plane traffic. ## Bad vs Good Implementations ### Configuring Egress Network Backpressure: Userspace Buffering vs eBPF TC Enforcement #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Buffering microbursts in userspace node processes forces massive heap allocations, high V8 GC stalls, and inevitable proxy OOMKills without signaling backpressure to the kernel TCP stack. ```typescript import { Socket } from 'net'; import { Transform } from 'stream'; // ANTI-PATTERN: Buffering packets in userspace proxy streams. // Under microbursts (>10Gbps), userspace heap balloons, causing high GC pauses, // event loop blockage, and catastrophic OOM kills of the proxy container. export class UserspaceRateLimitingProxy { private buffer: Buffer[] = []; private bytesSentInWindow = 0; private readonly maxBytesPerSec = 100_000_000; // 100MB/s public handleEgressStream(clientSocket: Socket, upstreamSocket: Socket): void { const limiter = new Transform({ transform: (chunk: Buffer, _encoding, callback) => { if (this.bytesSentInWindow + chunk.length > this.maxBytesPerSec) { // Unbounded in-memory queueing starves the container runtime this.buffer.push(chunk); callback(null, null); return; } this.bytesSentInWindow += chunk.length; callback(null, chunk); } }); clientSocket.pipe(limiter).pipe(upstreamSocket); } } ``` #### Production Standard (Correct) > **Standard**: Delegates egress packet metering and drops directly to the kernel TC layer via eBPF. Eliminates userspace buffering entirely and triggers immediate hardware/kernel TCP congestion window drops at sub-millisecond precision. ```typescript import { execFile } from 'child_process'; import { promisify } from 'util'; const execFileAsync = promisify(execFile); export interface TcRateLimitConfig { interfaceName: string; bpfObjectPath: string; rateBps: bigint; burstBytes: bigint; } // PRODUCTION INVARIANT: Attach eBPF classifier to the TC egress hook (clsact). // Direct packet drops (TC_ACT_SHOT) or ECN marking happen in kernel sk_buff, // forcing local/peer TCP congestion control (CUBIC/BBR) to collapse window without userland overhead. export class EbpfTcRateLimiterService { public async attachTcEgressFilter(config: TcRateLimitConfig): Promise<void> { const { interfaceName, bpfObjectPath, rateBps, burstBytes } = config; // 1. Ensure clsact qdisc exists on interface try { await execFileAsync('tc', ['qdisc', 'add', 'dev', interfaceName, 'clsact']); } catch (err: unknown) { // File exists error (EEXIST) indicates clsact is already bound; proceed safely const error = err as { stderr?: string }; if (!error.stderr?.includes('File exists')) { throw new Error(`Failed to bind clsact qdisc: ${error.stderr ?? 'unknown'}`); } } // 2. Attach eBPF object to egress hook with map configuration for kernel backpressure await execFileAsync('tc', [ 'filter', 'replace', 'dev', interfaceName, 'egress', 'prio', '1', 'handle', '1', 'bpf', 'da', 'obj', bpfObjectPath, 'sec', 'tc_egress' ]); // 3. Configure token-bucket map directly accessible by eBPF kernel program await execFileAsync('bpftool', [ 'map', 'update', 'pinned', `/sys/fs/bpf/tc/globals/rate_limit_${interfaceName}`, 'key', 'hex', '00', '00', '00', '00', 'value', 'hex', rateBps.toString(16).padStart(16, '0'), burstBytes.toString(16).padStart(16, '0') ]); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF TC Egress Token-Bucket Backpressure & Packet-Drop Signaling

eBPF TC Egress Token-Bucket Backpressure & Packet-Drop Signaling defines an industrial-grade behavioral standard for devops engineering. Enforces sub-millisecond network egress rate-limiting and congestion backpressure at the kernel Traffic Control (TC) layer via eBPF. Eliminates proxy sidecar memory exhaustion and CPU starvation during egress microbursts by directly engaging kernel TCP congestion control with deterministic drop (TC_ACT_SHOT) or ECN marking. 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: Delegating High-Throughput Egress Rate Limiting to Userspace Proxy Sidecars Causing OOM Cascades 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	Delegating High-Throughput Egress Rate Limiting to Userspace Proxy Sidecars Causing OOM Cascades	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 ensure non-routable, ARP, and vital ICMP/ICMPv6 diagnostic frames bypass token bucket drops to prevent cluster network partition.

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.