Cilium eBPF Dynamic Map Preallocation and Cgroup v2 Slab Accounting Invariant | AgentRules.org

Rules Stacks Clients Auditor Pruner Self-Heal RFCs Benchmark CLI CI/CD Authors Submit

This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →

devopscritical PriorityID: cilium-ebpf-map-preallocation-cgroupv2-invariant

Cilium eBPF Dynamic Map Preallocation and Cgroup v2 Slab Accounting Invariant

Enforces strict eBPF map sizing, preallocation invariants, and cgroup v2 memory controller accounting for Cilium deployments. Prevents unconstrained kernel slab allocations from dynamic BPF sockhash and connection tracking tables from evading container limits and causing silent node panics.

Prohibited Anti-Pattern: Unbounded dynamic eBPF map allocation without cgroup v2 kernel memory tracking causing host slab exhaustion

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Cilium eBPF Dynamic Map Preallocation and Cgroup v2 Slab Accounting Invariant - Enforces strict eBPF map sizing, preallocation invariants, and cgroup v2 memory controller accounting for Cilium deployments. Prevents unconstrained kernel slab allocations from dynamic BPF sockhash and connection tracking tables from evading container limits and causing silent node panics.
globs: **/cilium/**/*.{yaml,yml}, **/helm/**/values*.{yaml,yml}, **/charts/**/cilium*.{yaml,yml}, **/k8s/**/cilium*.{yaml,yml}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/cilium-ebpf-map-preallocation-cgroupv2-invariant"
---

# Cilium eBPF Dynamic Map Preallocation and Cgroup v2 Slab Accounting Invariant

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Unbounded dynamic eBPF map allocation without cgroup v2 kernel memory tracking causing host slab exhaustion

## System Constraints
You are a Principal Software Architect enforcing kernel stability and eBPF resource bounds in Kubernetes environments. Mandate that Cilium eBPF map preallocation and cgroup v2 memory invariants are strictly configured to prevent silent host slab exhaustion.

## Strict Guidelines
- Engineers MUST ALWAYS enforce explicit eBPF map preallocation (`bpf.preallocateMaps=true`) or strictly bound dynamic size ratios (`bpf.mapDynamicSizeRatio`) when deploying Cilium.
- Engineers MUST NOT disable map preallocation on clusters operating under legacy cgroup v1, as dynamic `BPF_F_NO_PREALLOC` slab memory bypasses pod memory tracking.
- Cilium DaemonSet configurations MUST enforce host cgroup v2 hierarchy mounts (`cgroup.autoMount.enabled=true` and `cgroup.hostRoot=/sys/fs/cgroup`) with memory controller delegation enabled.
- Helm values MUST explicitly configure bounded maximum entries for connection tracking (`bpf.ctMapEntriesGlobalTcp`, `bpf.ctMapEntriesGlobalAny`) and socket maps (`sockops.enabled`) rather than relying on unbounded kernel autoscaling.
- CI/CD validation pipelines MUST fail any manifest update that enables Cilium socket acceleration (`sockops`) without setting upper bounds on socket memory and verifying host kernel version >= 5.10 with `CONFIG_MEMCG_KMEM=y`.

## Bad vs Good Implementations
### Cilium Helm Configuration: BPF Map Allocation and Cgroup Guardrail

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Disabling preallocation without strictly bounded map ratios or cgroup v2 mounts causes BPF sockhash and CT allocations to consume unconstrained host kmalloc slab memory. In the event of a connection burst, this evades pod-level memory cgroup limits and triggers kernel OOM panics on the host node.
```yaml
# ANTI-PATTERN: Dynamic allocation enabled without cgroup v2 accounting or size bounds
bpf:
  preallocateMaps: false
  # Omitting ctMapEntries allows dynamic kernel allocation
  # Omitting mapDynamicSizeRatio allows unmetered slab growth
sockops:
  enabled: true # Dynamic sockmap without preallocation leaks kmalloc slab
cgroup:
  autoMount:
    enabled: false

```

#### Production Standard (Correct)
> **Standard**: Preallocating maps reserves fixed memory at initialization time, preventing runtime slab fragmentation. Enabling cgroup v2 autoMount ensures any dynamic socket memory or kernel allocations are accounted against the cgroup memory controllers, protecting the Kubernetes host node from silent exhaustion.
```yaml
# PRODUCTION INVARIANT: Bounded eBPF maps with strict cgroup v2 accounting
bpf:
  preallocateMaps: true
  ctMapEntriesGlobalTcp: 524288
  ctMapEntriesGlobalAny: 262144
  mapDynamicSizeRatio: 0.0025
sockops:
  enabled: true
cgroup:
  autoMount:
    enabled: true
  hostRoot: /sys/fs/cgroup
k8s:
  requireIPv4PodCIDR: true

```

Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Kubernetes Cluster Inspector MCP

Inspects running node cgroup hierarchy, BPF map allocations, and kernel slab memory usage.

Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Cilium CLI and BPF Map Inspector

Validates eBPF map sizing, preallocation flags, and cgroup attachment integrity via `cilium bpf` commands.

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Dynamic Map Preallocation and Cgroup v2 Slab Accounting Invariant

Cilium eBPF Dynamic Map Preallocation and Cgroup v2 Slab Accounting Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces strict eBPF map sizing, preallocation invariants, and cgroup v2 memory controller accounting for Cilium deployments. Prevents unconstrained kernel slab allocations from dynamic BPF sockhash and connection tracking tables from evading container limits and causing silent node panics. 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: Unbounded dynamic eBPF map allocation without cgroup v2 kernel memory tracking causing host slab exhaustion 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	Unbounded dynamic eBPF map allocation without cgroup v2 kernel memory tracking causing host slab exhaustion	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:

1

Engineers MUST ALWAYS enforce explicit eBPF map preallocation (`bpf.preallocateMaps=true`) or strictly bound dynamic size ratios (`bpf.mapDynamicSizeRatio`) when deploying Cilium.

Engineers MUST ALWAYS enforce explicit eBPF map preallocation (`bpf.preallocateMaps=true`) or strictly bound dynamic size ratios (`bpf.mapDynamicSizeRatio`) when deploying Cilium.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

2

Engineers MUST NOT disable map preallocation on clusters operating under legacy cgroup v1, as dynamic `BPF_F_NO_PREALLOC` slab memory bypasses pod memory tracking.

Engineers MUST NOT disable map preallocation on clusters operating under legacy cgroup v1, as dynamic `BPF_F_NO_PREALLOC` slab memory bypasses pod memory tracking.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

3

Cilium DaemonSet configurations MUST enforce host cgroup v2 hierarchy mounts (`cgroup.autoMount.enabled=true` and `cgroup.hostRoot=/sys/fs/cgroup`) with memory controller delegation enabled.

Cilium DaemonSet configurations MUST enforce host cgroup v2 hierarchy mounts (`cgroup.autoMount.enabled=true` and `cgroup.hostRoot=/sys/fs/cgroup`) with memory controller delegation enabled.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

4

Helm values MUST explicitly configure bounded maximum entries for connection tracking (`bpf.ctMapEntriesGlobalTcp`, `bpf.ctMapEntriesGlobalAny`) and socket maps (`sockops.enabled`) rather than relying on unbounded kernel autoscaling.

Helm values MUST explicitly configure bounded maximum entries for connection tracking (`bpf.ctMapEntriesGlobalTcp`, `bpf.ctMapEntriesGlobalAny`) and socket maps (`sockops.enabled`) rather than relying on unbounded kernel autoscaling.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

5

CI/CD validation pipelines MUST fail any manifest update that enables Cilium socket acceleration (`sockops`) without setting upper bounds on socket memory and verifying host kernel version >= 5.10 with `CONFIG_MEMCG_KMEM=y`.

CI/CD validation pipelines MUST fail any manifest update that enables Cilium socket acceleration (`sockops`) without setting upper bounds on socket memory and verifying host kernel version >= 5.10 with `CONFIG_MEMCG_KMEM=y`.

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Cilium eBPF Dynamic Map Preallocation and Cgroup v2 Slab Accounting Invariant critical for AI coding assistants?

Enforces strict eBPF map sizing, preallocation invariants, and cgroup v2 memory controller accounting for Cilium deployments. Prevents unconstrained kernel slab allocations from dynamic BPF sockhash and connection tracking tables from evading container limits and causing silent node panics. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded dynamic eBPF map allocation without cgroup v2 kernel memory tracking causing host slab exhaustion) 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.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related DEVOPS Rules

View all rules →

Kubernetes Gateway API v1 HTTPRoute Canary and ReferenceGrant Invariants

Enforces strict conformance to Kubernetes Gateway API v1 specifications during migration from legacy Ingress controllers. Mandates explicit ReferenceGrant resources for cross-namespace routing, strict relative integer weighting for HTTPRoute canary releases, and explicit backendRef port declarations.

ArgoCD ApplicationSet Matrix Generator Invariants & Cascade Deletion Guards

Enforces strict structural constraints on ArgoCD ApplicationSet Matrix generators combining cluster selectors and Git directories. Prevents catastrophic multi-cluster cascade pruning, accidental secret exposure through parameter interpolation, and runaway Application CR explosion via explicit sync policies, preservation finalizers, and parameter validation.

Karpenter Resilient Topology, Interruption Queue, and Consolidation Budget Standard

Enforces deterministic disruption budgets, multi-instance-type diversification, and event-driven SQS interruption queue handling across Karpenter NodePools and EC2NodeClasses. Eliminates cascading eviction loops, instance starvation, and availability downtime during AWS Spot rebalances and underutilized node consolidation.

1 Rule in Stack

Cilium