Cilium eBPF WireGuard Dynamic Path MTU Clamping Standard | 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-wireguard-dynamic-pmtu-clamping

Cilium eBPF WireGuard Dynamic Path MTU Clamping Standard

Enforces deterministic TCP MSS clamping and dynamic path MTU auto-detection in Cilium eBPF overlay networks with WireGuard encryption. Eliminates silent TCP session freezes and packet truncation across multi-cloud transit fabrics by accounting for kernel-level encapsulation and cryptographic overhead.

Prohibited Anti-Pattern: Static MTU Defaults and Missing eBPF TCP MSS Clamping in WireGuard Overlay Networks

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Cilium eBPF WireGuard Dynamic Path MTU Clamping Standard - Enforces deterministic TCP MSS clamping and dynamic path MTU auto-detection in Cilium eBPF overlay networks with WireGuard encryption. Eliminates silent TCP session freezes and packet truncation across multi-cloud transit fabrics by accounting for kernel-level encapsulation and cryptographic overhead.
globs: charts/**/values*.yaml, deployments/**/*.yaml, k8s/**/*.yaml, terraform/**/*.tf, helm/**/*.yaml, cilium/*.yaml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/cilium-ebpf-wireguard-dynamic-pmtu-clamping"
---

# Cilium eBPF WireGuard Dynamic Path MTU Clamping Standard

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Static MTU Defaults and Missing eBPF TCP MSS Clamping in WireGuard Overlay Networks

## System Constraints
You are a Principal DevOps and Linux Kernel Networking Engineer enforcing Cilium eBPF and WireGuard MTU standards. Mandate dynamic MTU discovery, explicit WireGuard encapsulation overhead accounting, and eBPF-driven TCP MSS clamping across all heterogeneous cloud topologies.

## Strict Guidelines
- Engineers MUST ALWAYS enable Cilium eBPF-based TCP MSS clamping (`enable-tcp-mss-clamping: true`) when transparent node-to-node or pod-to-pod WireGuard encryption is active.
- Engineers MUST NOT rely on standard Path MTU Discovery (PMTUD / ICMP Type 3 Code 4) across heterogeneous cloud interconnects where intermediate firewalls and VPC peering drop ICMP traffic.
- Code SHOULD calculate tunnel and pod MTU dynamically from the smallest host underlying interface MTU across the cluster minus WireGuard (60B) and tunnel protocol headers (e.g., GENEVE/VXLAN 50B).
- Services MUST configure `auto-direct-node-routes: true` or install explicit route-based MTUs when operating hybrid multi-cloud topologies (e.g., GCP 1460 MTU inter-operating with AWS 1500 MTU).
- Components NEVER set static host MTUs to 1500 or jumbo frames (9000) inside Cilium Helm configurations without subtracting encapsulation overheads, preventing silent TCP connection hangs during TLS handshakes.

## Bad vs Good Implementations
### Cilium Helm Configuration MTU and MSS Clamping

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Defaulting to MTU 1500 with VXLAN (50 bytes overhead) and WireGuard (60 bytes overhead) causes inner packets to exceed outer network MTU. In multi-cloud transit, intermediate gateways drop packets without returning ICMP fragmentation warnings, creating silent TCP blackholes during TLS handshakes.
```yaml
# Anti-Pattern: Static MTU assumption with WireGuard enabled and no MSS clamping
encryption:
  enabled: true
  type: wireguard
  nodeEncryption: true

# Dangerous: Hardcoding 1500 MTU causes IP fragmentation or silent drops
# when crossing GCP (1460 MTU) or through WireGuard crypto envelopes
mtu: 1500
routingMode: tunnel
tunnelProtocol: vxlan

# Missing eBPF TCP MSS clamping causes TLS handshake stalls on large payloads
```

#### Production Standard (Correct)
> **Standard**: Setting `mtu: 0` triggers Cilium dynamic host interface detection, while `enable-tcp-mss-clamping: true` instructs eBPF TC hooks to rewrite TCP SYN/SYN-ACK MSS values on the fly, eliminating packet fragmentation and blackholes across disparate provider MTU limits.
```yaml
# Standard: Dynamic MTU discovery with eBPF-level TCP MSS Clamping
encryption:
  enabled: true
  type: wireguard
  nodeEncryption: true

# Clamps TCP SYN/SYN-ACK MSS fields directly via eBPF to match path capacity
enable-tcp-mss-clamping: true
tcp-mss-clamping-mode: auto

# Auto-detects the lowest host network MTU and subtracts tunnel/crypto overhead
mtu: 0
autoDirectNodeRoutes: true
routingMode: native

# Fallback overlay configuration for heterogeneous nodes (e.g., GCP 1460 - 60 WG = 1400)
# mtu: 1400
```

Recommended MCP Servers (mcp-serverlist.com)

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

Kubernetes Cluster Inspector

Inspects live Cilium ConfigMaps, node link states, and daemonset MTU settings directly via MCP.

Recommended Agent Skills (askills.dev)

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

Cilium CLI Diagnostic Tool

Runs Cilium internal diagnostics, checks eBPF map statuses, and validates MTU clamping using `cilium status --verbose`.

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF WireGuard Dynamic Path MTU Clamping Standard

Cilium eBPF WireGuard Dynamic Path MTU Clamping Standard defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic TCP MSS clamping and dynamic path MTU auto-detection in Cilium eBPF overlay networks with WireGuard encryption. Eliminates silent TCP session freezes and packet truncation across multi-cloud transit fabrics by accounting for kernel-level encapsulation and cryptographic overhead. 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: Static MTU Defaults and Missing eBPF TCP MSS Clamping in WireGuard Overlay Networks 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	Static MTU Defaults and Missing eBPF TCP MSS Clamping in WireGuard Overlay Networks	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 enable Cilium eBPF-based TCP MSS clamping (`enable-tcp-mss-clamping

Engineers MUST ALWAYS enable Cilium eBPF-based TCP MSS clamping (`enable-tcp-mss-clamping: true`) when transparent node-to-node or pod-to-pod WireGuard encryption is active.

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 rely on standard Path MTU Discovery (PMTUD / ICMP Type 3 Code 4) across heterogeneous cloud interconnects where intermediate firewalls and VPC peering drop ICMP traffic.

Engineers MUST NOT rely on standard Path MTU Discovery (PMTUD / ICMP Type 3 Code 4) across heterogeneous cloud interconnects where intermediate firewalls and VPC peering drop ICMP traffic.

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

Code SHOULD calculate tunnel and pod MTU dynamically from the smallest host underlying interface MTU across the cluster minus WireGuard (60B) and tunnel protocol headers (e.g., GENEVE/VXLAN 50B).

Code SHOULD calculate tunnel and pod MTU dynamically from the smallest host underlying interface MTU across the cluster minus WireGuard (60B) and tunnel protocol headers (e.g., GENEVE/VXLAN 50B).

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

Services MUST configure `auto-direct-node-routes

Services MUST configure `auto-direct-node-routes: true` or install explicit route-based MTUs when operating hybrid multi-cloud topologies (e.g., GCP 1460 MTU inter-operating with AWS 1500 MTU).

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

Components NEVER set static host MTUs to 1500 or jumbo frames (9000) inside Cilium Helm configurations without subtracting encapsulation overheads, preventing silent TCP connection hangs during TLS handshakes.

Components NEVER set static host MTUs to 1500 or jumbo frames (9000) inside Cilium Helm configurations without subtracting encapsulation overheads, preventing silent TCP connection hangs during TLS handshakes.

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 WireGuard Dynamic Path MTU Clamping Standard critical for AI coding assistants?

Enforces deterministic TCP MSS clamping and dynamic path MTU auto-detection in Cilium eBPF overlay networks with WireGuard encryption. Eliminates silent TCP session freezes and packet truncation across multi-cloud transit fabrics by accounting for kernel-level encapsulation and cryptographic overhead. 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 (Static MTU Defaults and Missing eBPF TCP MSS Clamping in WireGuard Overlay Networks) 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