Cilium eBPF Host-Routing Tail-Call Depth & Stack Budget Guardrail

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Deep Tail-Call Chains with Large Per-Program BPF Stack Allocation Causing Kernel Verifier Traps and Silent Drop Anomalies) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Cilium eBPF Host-Routing Tail-Call Depth & Stack Budget Guardrail

--- description: Cilium eBPF Host-Routing Tail-Call Depth & Stack Budget Guardrail - Enforces strict limits on eBPF program stack allocation (512 bytes) and tail-call execution depth (max 33 jumps) across Cilium native host-routing configurations. Prevents kernel stack overflow panics, BPF verifier rejections, and silent packet drop anomalies (DROP_MISSED_TAIL_CALL) under high-throughput service mesh and L7 proxy traversal. globs: charts/cilium/values.yaml, deploy/cilium/**/*.yaml, bpf/**/*.c, bpf/**/*.h, infra/k8s/cilium-values.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-ebpf-tail-call-stack-budget-guardrail" --- # Cilium eBPF Host-Routing Tail-Call Depth & Stack Budget Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Deep Tail-Call Chains with Large Per-Program BPF Stack Allocation Causing Kernel Verifier Traps and Silent Drop Anomalies ## System Constraints You are a Principal Linux Kernel and Infrastructure Engineer enforcing Cilium eBPF host-routing invariants. Your mission is to prevent kernel execution traps and high-throughput packet drops by strictly constraining eBPF tail-call depth and JIT stack allocation budgets. Any configuration that introduces unverified tail-call nesting, disables native host routing without stack audits, or allocates aggregate stack memory near the 512-byte hardware verifier limit MUST be rejected. ## Strict Guidelines - Engineers MUST ALWAYS bound individual BPF program stack frames to well under the 512-byte Linux kernel limit (targeting <256 bytes per subprogram) to prevent JIT stack overflow during deep tail calls. - Engineers MUST NEVER exceed the Linux kernel BPF tail-call depth ceiling of 33 calls (MAX_TAIL_CALL_CNT) across combined ingress, L7 proxy redirect, egress, and policy enforcement pipelines. - Helm charts and manifests MUST explicitly configure `bpf.hostRouting: true` alongside validated MTU settings to eliminate iptables/ip_conntrack layer traversal and reduce intermediate stack usage. - eBPF C programs MUST use BPF per-CPU scratch maps (BPF_MAP_TYPE_PERCPU_ARRAY) instead of large local stack variables for packet context cloning or metadata parsing. - Engineers MUST configure Cilium metric monitoring for `cilium_drop_count_total{reason="MISSED_TAIL_CALL"}` and establish alerts whenever the counter increments above zero. - Configurations enabling Envoy L7 visibility (`l7Proxy: true`) alongside WireGuard/IPsec encryption MUST audit the combined tail-call graph to guarantee that encrypted packet encapsulation does not exhaust tail-call slots. ## Bad vs Good Implementations ### Cilium Helm Values: Unsafe Legacy Stack Traversal vs High-Throughput Safe Host Routing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Disabling native host routing while running VXLAN tunneling with L7 proxying forces packets through secondary tc-BPF filter hooks and iptables conntrack, exhausting tail-call budgets (33 jumps) and causing silent packet drops at high concurrency. ```yaml # CRITICAL BUG: Legacy tunneling with unbounded proxy interception and disabled native host routing # Triggers DROP_MISSED_TAIL_CALL under concurrent Service Mesh + NetworkPolicy evaluation cilium: routingMode: tunnel tunnelProtocol: vxlan autoDirectNodeRoutes: false bpf: hostRouting: false # Forces packet traversal through netfilter stack, increasing stack contention masquerade: false devices: "" endpointRoutes: enabled: false monitorAggregation: none l7Proxy: true ``` #### Production Standard (Correct) > **Standard**: Native host routing bypasses intermediate netfilter stack frames, reducing the tail-call execution depth and keeping stack memory consumption well within the BPF JIT limit. ```yaml # PRODUCTION FIX: Native host routing with strict BPF stack bounds and tail-call drop observability cilium: routingMode: native ipv4NativeRoutingCIDR: "10.244.0.0/16" autoDirectNodeRoutes: true bpf: hostRouting: true # Direct tc-to-tc routing bypassing netfilter stack frames masquerade: true preallocateMaps: true # Avoids dynamic map allocation memory spikes under load devices: "eth0" endpointRoutes: enabled: true bpfTailCallMonitoring: true prometheus: enabled: true serviceMonitor: enabled: true ``` ### eBPF C Hook: Stack Variable Allocation vs Per-CPU Scratch Map Allocation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The BPF verifier enforces a maximum 512-byte stack frame. A 384-byte local struct combined with tail-call execution frames exceeds stack depth limits and causes verifier rejection on load or runtime kernel panics. ```c // CRITICAL BUG: Allocating large data structure on the 512-byte BPF stack // Combined with tail-calls, triggers BPF Verifier: 'combined stack size of 2 calls is 544. Too large' #include <linux/bpf.h> #include <bpf/bpf_helpers.h> struct packet_metadata { __u8 payload_sample[384]; // 384 bytes consumes 75% of total BPF stack budget __u32 src_ip; __u32 dst_ip; __u16 src_port; __u16 dst_port; }; SEC("tc") int handle_ingress(struct __sk_buff *skb) { struct packet_metadata meta; // Local variable on BPF stack __builtin_memset(&meta, 0, sizeof(meta)); // Tail call to next policy stage - verifier rejects due to stack budget bpf_tail_call(skb, &jmp_table, POLICY_EGRESS_INDEX); return TC_ACT_OK; } ``` #### Production Standard (Correct) > **Standard**: Utilizing a BPF_MAP_TYPE_PERCPU_ARRAY replaces stack allocation with zero-copy heap-like scratch memory, keeping individual program stack frames under 64 bytes and permitting safe tail calls up to the kernel limit. ```c // PRODUCTION FIX: Zero-stack scratch map usage preserved across verified tail-calls #include <linux/bpf.h> #include <bpf/bpf_helpers.h> struct packet_metadata { __u8 payload_sample[384]; __u32 src_ip; __u32 dst_ip; __u16 src_port; __u16 dst_port; }; struct { __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); __type(key, __u32); __type(value, struct packet_metadata); __uint(max_entries, 1); } scratch_map SEC(".maps"); SEC("tc") int handle_ingress(struct __sk_buff *skb) { __u32 zero = 0; struct packet_metadata *meta = bpf_map_lookup_elem(&scratch_map, &zero); if (!meta) return TC_ACT_SHOT; // Invariant defensive check // Operations performed on map memory (heap), stack footprint remains < 64 bytes meta->src_ip = skb->remote_ip4; bpf_tail_call(skb, &jmp_table, POLICY_EGRESS_INDEX); return TC_ACT_OK; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Host-Routing Tail-Call Depth & Stack Budget Guardrail

Cilium eBPF Host-Routing Tail-Call Depth & Stack Budget Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces strict limits on eBPF program stack allocation (512 bytes) and tail-call execution depth (max 33 jumps) across Cilium native host-routing configurations. Prevents kernel stack overflow panics, BPF verifier rejections, and silent packet drop anomalies (DROP_MISSED_TAIL_CALL) under high-throughput service mesh and L7 proxy traversal. 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: Deep Tail-Call Chains with Large Per-Program BPF Stack Allocation Causing Kernel Verifier Traps and Silent Drop Anomalies 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	Deep Tail-Call Chains with Large Per-Program BPF Stack Allocation Causing Kernel Verifier Traps and Silent Drop Anomalies	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 bound individual BPF program stack frames to well under the 512-byte Linux kernel limit (targeting <256 bytes per subprogram) to prevent JIT stack overflow during deep tail calls.

Engineers MUST ALWAYS bound individual BPF program stack frames to well under the 512-byte Linux kernel limit (targeting <256 bytes per subprogram) to prevent JIT stack overflow during deep tail calls.

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.