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-ebpf-wireguard-mtu-mss-clamping

Cilium eBPF Host Routing MTU Clamping and WireGuard Overlay Guardrail

Mandates automated TCP MSS clamping and explicit datapath MTU calculation when enabling Cilium WireGuard node-to-node encryption and eBPF host routing. Prevents catastrophic TCP connection stalls and silent blackholing caused by dropped ICMP Fragmentation Needed (Type 3, Code 4) packets in cloud transit VPCs.

Prohibited Anti-Pattern: Deploying Cilium WireGuard encryption on standard 1500 MTU fabrics without eBPF MSS clamping

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Cilium eBPF Host Routing MTU Clamping and WireGuard Overlay Guardrail - Mandates automated TCP MSS clamping and explicit datapath MTU calculation when enabling Cilium WireGuard node-to-node encryption and eBPF host routing. Prevents catastrophic TCP connection stalls and silent blackholing caused by dropped ICMP Fragmentation Needed (Type 3, Code 4) packets in cloud transit VPCs.
globs: **/values*.yaml, **/cilium*.yaml, **/helmfile*.yaml, **/*cilium*.ts, **/cluster-config/**/*.{yaml,yml,ts}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/cilium-ebpf-wireguard-mtu-mss-clamping"
---

# Cilium eBPF Host Routing MTU Clamping and WireGuard Overlay Guardrail

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Deploying Cilium WireGuard encryption on standard 1500 MTU fabrics without eBPF MSS clamping

## System Constraints
You are a Principal Infrastructure Architect enforcing eBPF datapath invariants for Kubernetes clusters running Cilium. You must eliminate TCP packet blackholing caused by encapsulation and WireGuard crypto headers. When Cilium transparent encryption (WireGuard) or tunneling (Geneve/VXLAN) is active with eBPF host routing, you must enforce dynamic MSS clamping or explicit MTU reduction (at least 60 bytes for IPv4 WireGuard, 80 bytes for IPv6 WireGuard, plus overlay headers if dual-encapsulating). Never permit default 1500-byte pod MTUs on 1500-byte underlays when WireGuard encryption is enabled.

## Strict Guidelines
- Engineers MUST ALWAYS calculate and explicitly specify Cilium MTU by subtracting WireGuard overhead (minimum 60 bytes for IPv4, 80 bytes for IPv6) from the physical host interface MTU if underlay MTU auto-detection is not guaranteed.
- Engineers MUST enable Cilium's TCP MSS clamping in the eBPF datapath (`bpf.masquerade=true` and tunnel/encryption MSS adjustment) when running cross-VPC or hybrid-cloud transit gateways that filter ICMP Type 3 Code 4.
- Services MUST NOT rely on Path MTU Discovery (PMTUD) over intermediate cloud security groups or NAT gateways where ICMP 'Fragmentation Needed' is frequently dropped.
- Infrastructure code SHOULD configure `encryption.wireguard.encryptNode: true` only after verifying that `bpf.hostRouting` does not bypass tunnel interface routing tables unexpectedly.
- Configurations NEVER allow `bpf.hostRouting: true` alongside WireGuard without setting `mtu` explicitly or verifying that `cilium-agent` autodetects the clamped MTU on the `cilium_wg0` interface.

## Bad vs Good Implementations
### Cilium Helm Release Configuration with MTU Clamping & WireGuard (Pulumi / CDK8s)

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Defaults pod network MTU to 1500 bytes. When WireGuard adds 60-80 bytes of encryption encapsulation headers, packets reach 1560-1580 bytes. Because VPC fabrics enforce a strict 1500-byte MTU and drop ICMP Type 3 Code 4 packets, TCP handshakes succeed (SYN fits) but bulk payload transfers hang indefinitely (silent blackholing).
```typescript
import * as k8s from "@pulumi/kubernetes";

// ANTI-PATTERN: WireGuard enabled with default MTU and bpf host routing.
// Standard 1500 MTU packets will exceed underlay limit once encrypted (1500 + 60 = 1560B),
// causing silent drops on AWS/GCP fabrics when ICMP PMTUD is blocked.
export const ciliumRelease = new k8s.helm.v3.Release("cilium", {
  chart: "cilium",
  version: "1.15.5",
  repositoryOpts: { repo: "https://helm.cilium.io/" },
  values: {
    routingMode: "native",
    bpf: {
      hostRouting: true
    },
    encryption: {
      enabled: true,
      type: "wireguard",
      wireguard: {
        encryptNode: true
      }
    }
    // Missing explicit MTU calculation or TCP MSS clamping
  }
});
```

#### Production Standard (Correct)
> **Standard**: Explicitly clamps Pod MTU to 1420 bytes, guaranteeing that encapsulated WireGuard frames never exceed the host underlay MTU (1500). Combined with eBPF-driven host routing and masquerading, TCP SYN packets negotiate an MSS of 1380 bytes (1420 - 40 TCP/IP headers), eliminating dependency on ICMP PMTUD and preventing blackhole failure modes.
```typescript
import * as k8s from "@pulumi/kubernetes";

// PRODUCTION INVARIANT: MTU is derived from host interface minus WireGuard overhead.
// Host underlay = 1500. IPv4 WireGuard header = 60 bytes. Clamped MTU = 1440 (or 1420 for dual-stack safety).
const HOST_UNDERLAY_MTU = 1500;
const WIREGUARD_OVERHEAD = 80; // Safe for IPv6 and IPv4
const CLAMPED_POD_MTU = HOST_UNDERLAY_MTU - WIREGUARD_OVERHEAD; // 1420

export const ciliumRelease = new k8s.helm.v3.Release("cilium", {
  chart: "cilium",
  version: "1.15.5",
  repositoryOpts: { repo: "https://helm.cilium.io/" },
  values: {
    routingMode: "native",
    autoDirectNodeRoutes: true,
    mtu: CLAMPED_POD_MTU,
    bpf: {
      hostRouting: true,
      masquerade: true,
      // Clamps TCP MSS on SYN/SYN-ACK via eBPF to prevent PMTUD blackholing
      tproxy: true
    },
    encryption: {
      enabled: true,
      type: "wireguard",
      wireguard: {
        encryptNode: true
      }
    },
    // Enforce MSS clamping at pod egress for external/inter-cluster traffic
    cni: {
      customConf: false
    }
  }
});
```
Recommended MCP Servers (mcp-serverlist.com)

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

Kubernetes Cluster Inspector
Inspects running Cilium DaemonSet configurations, CiliumNode CRDs, and live MTU attributes across cluster nodes.
Recommended Agent Skills (askills.dev)

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

Cilium Datapath Diagnostics
Executes 'cilium-dbg bpf' and 'cilium-dbg status --all-addresses' to inspect active eBPF map limits, tunnel overhead, and WireGuard MTU allocations.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Host Routing MTU Clamping and WireGuard Overlay Guardrail

Cilium eBPF Host Routing MTU Clamping and WireGuard Overlay Guardrail defines an industrial-grade behavioral standard for devops engineering. Mandates automated TCP MSS clamping and explicit datapath MTU calculation when enabling Cilium WireGuard node-to-node encryption and eBPF host routing. Prevents catastrophic TCP connection stalls and silent blackholing caused by dropped ICMP Fragmentation Needed (Type 3, Code 4) packets in cloud transit VPCs. 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: Deploying Cilium WireGuard encryption on standard 1500 MTU fabrics without eBPF MSS clamping 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 DriftDeploying Cilium WireGuard encryption on standard 1500 MTU fabrics without eBPF MSS clampingCritical
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 calculate and explicitly specify Cilium MTU by subtracting WireGuard overhead (minimum 60 bytes for IPv4, 80 bytes for IPv6) from the physical host interface MTU if underlay MTU auto-detection is not guaranteed.

Engineers MUST ALWAYS calculate and explicitly specify Cilium MTU by subtracting WireGuard overhead (minimum 60 bytes for IPv4, 80 bytes for IPv6) from the physical host interface MTU if underlay MTU auto-detection is not guaranteed.

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 enable Cilium's TCP MSS clamping in the eBPF datapath (`bpf.masquerade=true` and tunnel/encryption MSS adjustment) when running cross-VPC or hybrid-cloud transit gateways that filter ICMP Type 3 Code 4.

Engineers MUST enable Cilium's TCP MSS clamping in the eBPF datapath (`bpf.masquerade=true` and tunnel/encryption MSS adjustment) when running cross-VPC or hybrid-cloud transit gateways that filter ICMP Type 3 Code 4.

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

Services MUST NOT rely on Path MTU Discovery (PMTUD) over intermediate cloud security groups or NAT gateways where ICMP 'Fragmentation Needed' is frequently dropped.

Services MUST NOT rely on Path MTU Discovery (PMTUD) over intermediate cloud security groups or NAT gateways where ICMP 'Fragmentation Needed' is frequently dropped.

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

Infrastructure code SHOULD configure `encryption.wireguard.encryptNode

Infrastructure code SHOULD configure `encryption.wireguard.encryptNode: true` only after verifying that `bpf.hostRouting` does not bypass tunnel interface routing tables unexpectedly.

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

Configurations NEVER allow `bpf.hostRouting

Configurations NEVER allow `bpf.hostRouting: true` alongside WireGuard without setting `mtu` explicitly or verifying that `cilium-agent` autodetects the clamped MTU on the `cilium_wg0` interface.

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 MTU Clamping and WireGuard Overlay Guardrail critical for AI coding assistants?

Mandates automated TCP MSS clamping and explicit datapath MTU calculation when enabling Cilium WireGuard node-to-node encryption and eBPF host routing. Prevents catastrophic TCP connection stalls and silent blackholing caused by dropped ICMP Fragmentation Needed (Type 3, Code 4) packets in cloud transit VPCs. 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 (Deploying Cilium WireGuard encryption on standard 1500 MTU fabrics without eBPF MSS clamping) 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