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-pmtu-mss-clamping-standard

Cilium eBPF Dynamic PMTU Discovery and MSS Clamping Standard

Enforces deterministic Maximum Transmission Unit (MTU) calculations and TCP Maximum Segment Size (MSS) clamping inside Cilium eBPF datapath configurations. Prevents silent ICMP 'Packet Too Big' black-holing across heterogeneous multi-cloud transit networks with nested Geneve encapsulation and WireGuard node-to-node encryption overlays.

Prohibited Anti-Pattern: Hardcoding default 1500 or 9000 byte MTU across nested WireGuard/Geneve overlays without dynamic MSS clamping and PMTU ICMP reflection.

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Cilium eBPF Dynamic PMTU Discovery and MSS Clamping Standard - Enforces deterministic Maximum Transmission Unit (MTU) calculations and TCP Maximum Segment Size (MSS) clamping inside Cilium eBPF datapath configurations. Prevents silent ICMP 'Packet Too Big' black-holing across heterogeneous multi-cloud transit networks with nested Geneve encapsulation and WireGuard node-to-node encryption overlays.
globs: helm/cilium/values.yaml, deploy/cilium/**/*.yaml, infra/k8s/cilium-values.yaml, terraform/modules/cilium/values.yaml, src/infrastructure/ciliumConfig.ts
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/cilium-ebpf-pmtu-mss-clamping-standard"
---

# Cilium eBPF Dynamic PMTU Discovery and MSS Clamping Standard

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Hardcoding default 1500 or 9000 byte MTU across nested WireGuard/Geneve overlays without dynamic MSS clamping and PMTU ICMP reflection.

## System Constraints
You are a Principal Network Architect enforcing Cilium eBPF Dynamic Path MTU Discovery and TCP MSS Clamping invariants across multi-cloud Kubernetes clusters. Your task is to eliminate network black-holes caused by encapsulation overhead mismatches (Geneve + WireGuard) in transit VPCs and inter-cloud peering. You must mandate dynamic PMTU discovery, explicit BPF-level TCP MSS clamping, and ICMP Type 3 Code 4 reflection, prohibiting hardcoded interface MTUs and static unvalidated tunnel overlays.

## Strict Guidelines
- Engineers MUST configure Helm values to reserve exact overhead for encapsulation combinations: 50 bytes for Geneve (VXLAN is 50), 60 bytes for WireGuard (IPv4) or 80 bytes (IPv6), and 110 bytes when chaining WireGuard inside Geneve overlays.
- Engineers MUST set 'bpf.masquerade=true' and ensure 'bpf.tproxy=true' alongside explicit TCP MSS clamping ('bpf.hostRouting=true' with 'devices' properly bound to all multi-cloud transit interfaces).
- Engineers MUST enable PMTU Discovery ('pmtuDiscovery: true') to trigger eBPF TC-level ICMP Type 3 Code 4 ('Fragmentation Needed') reflection when pod egress frames exceed the negotiated path MTU.
- Engineers MUST NEVER configure 'autoDirectNodeRoutes=true' across multi-cloud VPC boundaries without BGP peering or overlay encapsulation, as transit gateways drop unencapsulated pod-CIDR packets.
- Infrastructure automation scripts MUST probe and validate the lowest end-to-end interface MTU (e.g., Azure 1500, AWS TGW 8500, GCP 1460) before applying the CiliumConfig custom resource.

## Bad vs Good Implementations
### Cilium Helm Configuration for Multi-Cloud WireGuard + Geneve Transit Overlay

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Omitting explicit tunnel MTU and PMTU configuration leaves Cilium to assume the host's base 1500 MTU. When 50 bytes of Geneve encapsulation and 60 bytes of WireGuard headers are prepended, the resultant 1610-byte packets are dropped by multi-cloud intermediate routers without ICMP PTB notifications, causing catastrophic TCP connection hangs on large payload transfers.
```typescript
// Flawed Helm values generation: Default MTU with WireGuard overlay enabled
// Results in 1500-byte frame generation dropped silently by cloud transit fabrics
export interface CiliumHelmValues {
  tunnel: string;
  encryption: { enabled: boolean; type: string };
  mtu?: number;
  bpf: { masquerade: boolean };
}

export const productionValues: CiliumHelmValues = {
  tunnel: "geneve",
  encryption: {
    enabled: true,
    type: "wireguard",
  },
  // Anti-pattern: MTU is left unset (defaults to 1500 or host-dev MTU without tunnel deduction)
  // Missing pmtuDiscovery and explicit TCP MSS clamping
  bpf: {
    masquerade: true,
  },
};
```

#### Production Standard (Correct)
> **Standard**: The production configuration accurately calculates the combined encapsulation overhead (110 bytes for Geneve + WireGuard) against the lowest possible multi-cloud transit underlay MTU (1460 bytes for GCP peering). It activates eBPF-level Path MTU Discovery ('pmtuDiscovery: true') to reflect ICMP Packet-Too-Big responses back to pods, ensuring TCP MSS clamping functions deterministically and prevents silent packet drops.
```typescript
// Resilient Helm values generation: Computes dynamic MSS and applies strict PMTU eBPF invariants
export interface CiliumHelmValues {
  tunnelProtocol: "geneve" | "vxlan";
  encryption: {
    enabled: boolean;
    type: "wireguard" | "ipsec";
    nodeEncryption: boolean;
  };
  mtu: number;
  pmtuDiscovery: boolean;
  bpf: {
    masquerade: boolean;
    hostRouting: boolean;
  };
  routingMode: "tunnel";
  devices: string[];
}

export function generateCiliumOverlayConfig(
  baseUnderlayMtu: number = 1500,
  transitType: "gcp-aws-crosscloud" | "standard-vpc" = "gcp-aws-crosscloud"
): CiliumHelmValues {
  // GCP default interface is 1460; AWS TGW default is 8500 or standard 1500
  const lowestTransitMtu = transitType === "gcp-aws-crosscloud" ? 1460 : baseUnderlayMtu;
  
  // Geneve (50B) + WireGuard IPv4 (60B) = 110B overlay overhead
  const totalTunnelOverhead = 110;
  const clampedMtu = lowestTransitMtu - totalTunnelOverhead;

  return {
    tunnelProtocol: "geneve",
    routingMode: "tunnel",
    encryption: {
      enabled: true,
      type: "wireguard",
      nodeEncryption: true,
    },
    mtu: clampedMtu, // Strictly configured to 1350 for 1460 underlay
    pmtuDiscovery: true, // Enables eBPF generation of ICMP 'Fragmentation Needed'
    bpf: {
      masquerade: true,
      hostRouting: true,
    },
    devices: ["eth+", "ens+"],
  };
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

Kubernetes Context Protocol Server
Inspects live Cilium daemonset pods, CiliumNode CRDs, and eBPF datapath interface MTU allocations across clusters.
Recommended Agent Skills (askills.dev)

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

Cilium CLI Diagnostics
Executes 'cilium bpf tunnel list' and 'cilium connectivity test' to validate cross-cluster eBPF PMTU and MSS drop rate telemetry.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Dynamic PMTU Discovery and MSS Clamping Standard

Cilium eBPF Dynamic PMTU Discovery and MSS Clamping Standard defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic Maximum Transmission Unit (MTU) calculations and TCP Maximum Segment Size (MSS) clamping inside Cilium eBPF datapath configurations. Prevents silent ICMP 'Packet Too Big' black-holing across heterogeneous multi-cloud transit networks with nested Geneve encapsulation and WireGuard node-to-node encryption overlays. 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: Hardcoding default 1500 or 9000 byte MTU across nested WireGuard/Geneve overlays without dynamic MSS clamping and PMTU ICMP reflection. 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 DriftHardcoding default 1500 or 9000 byte MTU across nested WireGuard/Geneve overlays without dynamic MSS clamping and PMTU ICMP reflection.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 configure Helm values to reserve exact overhead for encapsulation combinations

Engineers MUST configure Helm values to reserve exact overhead for encapsulation combinations: 50 bytes for Geneve (VXLAN is 50), 60 bytes for WireGuard (IPv4) or 80 bytes (IPv6), and 110 bytes when chaining WireGuard inside Geneve overlays.

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 set 'bpf.masquerade=true' and ensure 'bpf.tproxy=true' alongside explicit TCP MSS clamping ('bpf.hostRouting=true' with 'devices' properly bound to all multi-cloud transit interfaces).

Engineers MUST set 'bpf.masquerade=true' and ensure 'bpf.tproxy=true' alongside explicit TCP MSS clamping ('bpf.hostRouting=true' with 'devices' properly bound to all multi-cloud transit interfaces).

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

Engineers MUST enable PMTU Discovery ('pmtuDiscovery

Engineers MUST enable PMTU Discovery ('pmtuDiscovery: true') to trigger eBPF TC-level ICMP Type 3 Code 4 ('Fragmentation Needed') reflection when pod egress frames exceed the negotiated path 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.
4

Engineers MUST NEVER configure 'autoDirectNodeRoutes=true' across multi-cloud VPC boundaries without BGP peering or overlay encapsulation, as transit gateways drop unencapsulated pod-CIDR packets.

Engineers MUST NEVER configure 'autoDirectNodeRoutes=true' across multi-cloud VPC boundaries without BGP peering or overlay encapsulation, as transit gateways drop unencapsulated pod-CIDR packets.

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

Infrastructure automation scripts MUST probe and validate the lowest end-to-end interface MTU (e.g., Azure 1500, AWS TGW 8500, GCP 1460) before applying the CiliumConfig custom resource.

Infrastructure automation scripts MUST probe and validate the lowest end-to-end interface MTU (e.g., Azure 1500, AWS TGW 8500, GCP 1460) before applying the CiliumConfig custom resource.

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 PMTU Discovery and MSS Clamping Standard critical for AI coding assistants?

Enforces deterministic Maximum Transmission Unit (MTU) calculations and TCP Maximum Segment Size (MSS) clamping inside Cilium eBPF datapath configurations. Prevents silent ICMP 'Packet Too Big' black-holing across heterogeneous multi-cloud transit networks with nested Geneve encapsulation and WireGuard node-to-node encryption overlays. 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 (Hardcoding default 1500 or 9000 byte MTU across nested WireGuard/Geneve overlays without dynamic MSS clamping and PMTU ICMP reflection.) 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