AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
devopscritical PriorityID: cilium-bpf-host-routing-pmtu-clamping

Cilium eBPF Host-Routing Path MTU Discovery & MSS Clamping Boundary

Enforces strict TCP MSS clamping, PMTU discovery enablement, and interface-level MTU alignment when Cilium bpf.hostRouting is active in hybrid cloud or multi-cloud topologies. When eBPF bypasses the host iptables/netfilter stack, jumbo frames and tunnel encapsulation overhead (Geneve, VXLAN, WireGuard) cause silent packet blackholes due to dropped ICMP Type 3 Code 4 fragmentation needed signals. Infrastructure-as-code manifests and Helm configurations must explicitly enforce automated MSS clamping and precise tunnel overhead accounting across all routing boundaries.

Prohibited Anti-Pattern: Bypassing iptables TCP MSS clamping via bpf.hostRouting=true without BPF-native MSS clamping or proper MTU headroom calculation.

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Cilium eBPF Host-Routing Path MTU Discovery & MSS Clamping Boundary - Enforces strict TCP MSS clamping, PMTU discovery enablement, and interface-level MTU alignment when Cilium bpf.hostRouting is active in hybrid cloud or multi-cloud topologies. When eBPF bypasses the host iptables/netfilter stack, jumbo frames and tunnel encapsulation overhead (Geneve, VXLAN, WireGuard) cause silent packet blackholes due to dropped ICMP Type 3 Code 4 fragmentation needed signals. Infrastructure-as-code manifests and Helm configurations must explicitly enforce automated MSS clamping and precise tunnel overhead accounting across all routing boundaries.
globs: helm/**/*.{yaml,yml}, kubernetes/**/*.{yaml,yml}, terraform/**/*.{tf,tfvars}, ansible/**/*.{yaml,yml}, manifests/**/*.{yaml,yml}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/cilium-bpf-host-routing-pmtu-clamping"
---

# Cilium eBPF Host-Routing Path MTU Discovery & MSS Clamping Boundary

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Bypassing iptables TCP MSS clamping via bpf.hostRouting=true without BPF-native MSS clamping or proper MTU headroom calculation.

## System Constraints
You are a Principal Cloud Networking and Security Architect enforcing deterministic Path MTU Discovery (PMTU) and TCP MSS clamping in Kubernetes clusters powered by Cilium eBPF host-routing. You must prevent silent packet drops and blackhole connections caused by encapsulation overhead mismatches, intermediate VPC/transit-gateway MTU limits, and eBPF bypassing the kernel netfilter stack. Ensure every Cilium configuration explicitly reconciles device MTUs, Geneve/VXLAN/WireGuard offsets, and BPF-native MSS clamping parameters.

## Strict Guidelines
- Engineers MUST ALWAYS enable Cilium native MSS clamping via `bpf.autoMSS` or `bpf.clampMss` configuration options when `bpf.hostRouting=true` is activated.
- Engineers MUST NEVER assume host iptables `TCPMSS --clamp-mss-to-pmtu` rules apply when `bpf.hostRouting: true` is set, because eBPF directly redirects packets at tc/xdp layers before netfilter hooks.
- Infrastructure configurations MUST explicitly calculate MTU headroom subtracting encapsulation overhead: 50 bytes for VXLAN/Geneve over IPv4, 70 bytes for VXLAN/Geneve over IPv6, plus an additional 32 bytes when WireGuard encryption is enabled.
- Manifests MUST NEVER leave MTU set to automatic detection (0) in hybrid cloud environments spanning AWS Direct Connect, Azure ExpressRoute, or multi-cloud WireGuard tunnels where MTU boundaries differ from standard 1500 or 9000 bytes.
- Monitoring rules MUST track and alert on `cilium_drop_count_total{reason="Fragmentation needed and DF set"}` and Cilium endpoint monitor drop notifications for MTU exceeded events.

## Bad vs Good Implementations
### Cilium Helm Values: Unclamped BPF Host-Routing vs Production Clamped MTU Configuration

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Enabling bpf.hostRouting bypasses host netfilter, rendering traditional iptables MSS clamping useless. With mtu: 0 and tunnelProtocol: geneve without autoMSS, pods negotiate a 1460 TCP MSS for an assumed 1500 underlay MTU; encapsulation adds 50 bytes (total 1550 bytes), exceeding intermediate MTU and resulting in silent packet drops because ICMP Frag Needed cannot return to the pod.
```yaml
# Anti-Pattern: Host routing bypasses iptables without eBPF MTU clamping
# Silently drops packets > 1450 bytes on Geneve/VXLAN overlay networks crossing 1500-byte underlays
routingMode: native
tunnelProtocol: geneve
bpf:
  hostRouting: true
pmtu:
  enabled: false
mtu: 0
```

#### Production Standard (Correct)
> **Standard**: Explicitly declares mtu: 1450 to accommodate the 50-byte Geneve encapsulation header, enables pmtu to handle dynamic path limits, and configures BPF native MSS clamping so TCP SYN packets are rewritten at the eBPF layer before transmission, eliminating silent blackholes on overlay networks.
```yaml
# Production Standard: Enforced BPF-native MSS clamping with deterministic MTU calculations
routingMode: native
tunnelProtocol: geneve
bpf:
  hostRouting: true
  autoMSS:
    enabled: true
    # Explicit clamp boundary: Underlay (1500) - IPv4/Geneve (50) - TCP/IP Header (40) = 1410
pmtu:
  enabled: true
# Explicit MTU calculated: Host MTU (1500) minus Geneve overhead (50) = 1450
mtu: 1450
enableIPv4Masquerade: true
enableIPv6Masquerade: false
```

### Terraform / Helm Release: WireGuard Overlay MTU Boundary Enforcement

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: WireGuard adds 60 bytes of encapsulation overhead. Defaulting MTU to 1500 without adjusting for WireGuard and host routing causes fragmentation drops on any pod generating TCP packets near the MSS threshold.
```terraform
// Anti-Pattern: Enabling WireGuard mesh encryption without adjusting for WireGuard + Geneve overhead
resource "helm_release" "cilium" {
  name       = "cilium"
  repository = "https://helm.cilium.io/"
  chart      = "cilium"
  version    = "1.15.5"

  set {
    name  = "encryption.enabled"
    value = "true"
  }
  set {
    name  = "encryption.type"
    value = "wireguard"
  }
  set {
    name  = "bpf.hostRouting"
    value = "true"
  }
}
```

#### Production Standard (Correct)
> **Standard**: Calculates the strict MTU boundary considering both VXLAN and WireGuard headers (1500 - 50 - 60 = 1390), instructs Cilium to enforce this MTU across all node interfaces, and ensures bpf.autoMSS clamps TCP handshakes to prevent path MTU dropouts.
```terraform
// Production Standard: Mathematical calculation of MTU and MSS clamping with WireGuard encryption
resource "helm_release" "cilium" {
  name       = "cilium"
  repository = "https://helm.cilium.io/"
  chart      = "cilium"
  version    = "1.15.5"

  values = [
    yamlencode({
      routingMode = "tunnel"
      tunnelProtocol = "vxlan"
      encryption = {
        enabled = true
        type    = "wireguard"
      }
      bpf = {
        hostRouting = true
        autoMSS = {
          enabled = true
        }
      }
      pmtu = {
        enabled = true
      }
      # 1500 underlay - 50 (VXLAN) - 60 (WireGuard) = 1390 pod network MTU
      mtu = 1390
    })
  ]
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

Kubernetes Cluster Inspector MCP
Direct read and audit of live Cilium ConfigMaps, DaemonSets, and Node MTU interfaces.
Recommended Agent Skills (askills.dev)

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

Cilium BPF Monitoring and Connectivity Diagnostics
Runs cilium bpf tunnel list, cilium monitor --type drop, and cilium status --verbose to detect PMTU dropouts.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Host-Routing Path MTU Discovery & MSS Clamping Boundary

Cilium eBPF Host-Routing Path MTU Discovery & MSS Clamping Boundary defines an industrial-grade behavioral standard for devops engineering. Enforces strict TCP MSS clamping, PMTU discovery enablement, and interface-level MTU alignment when Cilium bpf.hostRouting is active in hybrid cloud or multi-cloud topologies. When eBPF bypasses the host iptables/netfilter stack, jumbo frames and tunnel encapsulation overhead (Geneve, VXLAN, WireGuard) cause silent packet blackholes due to dropped ICMP Type 3 Code 4 fragmentation needed signals. Infrastructure-as-code manifests and Helm configurations must explicitly enforce automated MSS clamping and precise tunnel overhead accounting across all routing boundaries. 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: Bypassing iptables TCP MSS clamping via bpf.hostRouting=true without BPF-native MSS clamping or proper MTU headroom calculation. 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftBypassing iptables TCP MSS clamping via bpf.hostRouting=true without BPF-native MSS clamping or proper MTU headroom calculation.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 InconsistencyAI 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 enable Cilium native MSS clamping via `bpf.autoMSS` or `bpf.clampMss` configuration options when `bpf.hostRouting=true` is activated.

Engineers MUST ALWAYS enable Cilium native MSS clamping via `bpf.autoMSS` or `bpf.clampMss` configuration options when `bpf.hostRouting=true` is activated.

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 NEVER assume host iptables `TCPMSS --clamp-mss-to-pmtu` rules apply when `bpf.hostRouting

Engineers MUST NEVER assume host iptables `TCPMSS --clamp-mss-to-pmtu` rules apply when `bpf.hostRouting: true` is set, because eBPF directly redirects packets at tc/xdp layers before netfilter hooks.

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

Infrastructure configurations MUST explicitly calculate MTU headroom subtracting encapsulation overhead

Infrastructure configurations MUST explicitly calculate MTU headroom subtracting encapsulation overhead: 50 bytes for VXLAN/Geneve over IPv4, 70 bytes for VXLAN/Geneve over IPv6, plus an additional 32 bytes when WireGuard encryption is 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

Manifests MUST NEVER leave MTU set to automatic detection (0) in hybrid cloud environments spanning AWS Direct Connect, Azure ExpressRoute, or multi-cloud WireGuard tunnels where MTU boundaries differ from standard 1500 or 9000 bytes.

Manifests MUST NEVER leave MTU set to automatic detection (0) in hybrid cloud environments spanning AWS Direct Connect, Azure ExpressRoute, or multi-cloud WireGuard tunnels where MTU boundaries differ from standard 1500 or 9000 bytes.

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

Monitoring rules MUST track and alert on `cilium_drop_count_total{reason="Fragmentation needed and DF set"}` and Cilium endpoint monitor drop notifications for MTU exceeded events.

Monitoring rules MUST track and alert on `cilium_drop_count_total{reason="Fragmentation needed and DF set"}` and Cilium endpoint monitor drop notifications for MTU exceeded events.

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 Host-Routing Path MTU Discovery & MSS Clamping Boundary critical for AI coding assistants?

Enforces strict TCP MSS clamping, PMTU discovery enablement, and interface-level MTU alignment when Cilium bpf.hostRouting is active in hybrid cloud or multi-cloud topologies. When eBPF bypasses the host iptables/netfilter stack, jumbo frames and tunnel encapsulation overhead (Geneve, VXLAN, WireGuard) cause silent packet blackholes due to dropped ICMP Type 3 Code 4 fragmentation needed signals. Infrastructure-as-code manifests and Helm configurations must explicitly enforce automated MSS clamping and precise tunnel overhead accounting across all routing boundaries. 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 (Bypassing iptables TCP MSS clamping via bpf.hostRouting=true without BPF-native MSS clamping or proper MTU headroom calculation.) 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 →
devops
86

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.

devops
118

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.

devops
40

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