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

Cilium eBPF Dynamic WireGuard Path-MTU Clamping Invariant

Enforces deterministic MTU sizing and dynamic TCP MSS clamping at the eBPF layer for WireGuard encrypted multi-cloud meshes. Prevents silent packet drops, ICMP 'Fragmentation Needed' blackholes, and throughput degradation caused by uncalculated encapsulation overhead across cloud VPC fabrics.

Prohibited Anti-Pattern: Blind 1500 MTU Overlay Defaults and Static MSS Configurations Causing Encrypted Packet Drops

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Cilium eBPF Dynamic WireGuard Path-MTU Clamping Invariant - Enforces deterministic MTU sizing and dynamic TCP MSS clamping at the eBPF layer for WireGuard encrypted multi-cloud meshes. Prevents silent packet drops, ICMP 'Fragmentation Needed' blackholes, and throughput degradation caused by uncalculated encapsulation overhead across cloud VPC fabrics.
globs: deployments/**/*.{yaml,yml}, helm/**/*.{yaml,yml}, infrastructure/**/*.{yaml,yml,tf}, bpf/**/*.c
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/cilium-ebpf-wireguard-pmtu-clamping-standard"
---

# Cilium eBPF Dynamic WireGuard Path-MTU Clamping Invariant

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Blind 1500 MTU Overlay Defaults and Static MSS Configurations Causing Encrypted Packet Drops

## System Constraints
You are a Principal Cloud Networking and Linux Kernel Engineer enforcing Cilium eBPF Dynamic WireGuard Path-MTU Clamping Invariants. You must ensure that all Cilium Helm values, ConfigMaps, and kernel socket programs explicitly accommodate WireGuard's 60-byte IPv4 / 80-byte IPv6 encapsulation overhead, mandate TCP MSS clamping on TC/eBPF ingress and egress hooks, and prohibit hardcoded 1500 MTU configs across multi-cloud overlay networks.

## Strict Guidelines
- Engineers MUST ALWAYS calculate WireGuard MTU derived from the lowest common denominator underlay MTU across cloud providers (e.g., AWS 9001/1500, GCP 1460, Azure 1500) minus WireGuard (60B IPv4 / 80B IPv6) and Geneve/VXLAN overlay headers.
- Engineers MUST NOT rely on ICMP Type 3 Code 4 (Fragmentation Needed) packets surviving public internet transit across multi-cloud transit gateways, as cloud firewalls routinely drop them.
- Helm and GitOps values MUST explicitly set `encryption.wireguard.enabled: true` in conjunction with `bpf.autoMount.enabled: true`, `enableICMPRules: true`, and `bpf.clampMss: true` (or custom MSS clamp DaemonSet annotations).
- Kernel eBPF programs or Cilium network policies MUST clamp TCP MSS inside `TC_ACT_OK` egress filters to `MTU - 40` (IPv4) or `MTU - 60` (IPv6) before WireGuard encapsulation occurs.
- Infrastructure configurations MUST NEVER leave `cilium.mtu` or `devices` unspecified when crossing cloud boundaries where GCP (1460 MTU) or Azure interconnects participate in the mesh.

## Bad vs Good Implementations
### Cilium Helm Values: Broken 1500 MTU Mesh vs Encapsulation-Aware MTU & MSS Clamping

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Omitting explicit MTU calculation in multi-cloud WireGuard setups causes Cilium to assume the host MTU (often 1500 or 9001 on AWS). When traffic traverses GCP (MTU 1460) or standard tunnels, packets encapsulated in WireGuard (60B overhead) exceed the maximum underlay packet size, leading to silent drops because path MTU discovery ICMP messages are routinely blocked.
```yaml
# Flawed: Relies on default 1500 MTU with WireGuard in multi-cloud (GCP underlay is 1460)
# Results in silent PMTU blackholes when TCP packets with DF bit set exceed 1460 - 60 = 1400 bytes.
encryption:
  enabled: true
  type: wireguard
tunnelProtocol: vxlan
# mtu parameter is omitted, defaulting to 1500 host probe
```

#### Production Standard (Correct)
> **Standard**: Explicitly clamps Cilium overlay MTU to 1400 to accommodate the lowest cloud underlay MTU (GCP 1460 minus 60 bytes of WireGuard overhead) and mandates `bpf.clampMss: true` to rewrite the TCP MSS option at the socket layer via eBPF, preventing fragmentation and blackholes completely.
```yaml
# Fixed: Clamped MTU accounting for GCP underlay (1460) - WireGuard IPv4 overhead (60) = 1400
# Enforces dynamic eBPF MSS clamping on all ingress/egress Pod veth interfaces.
encryption:
  enabled: true
  type: wireguard
  wireguard:
    dynamicMTU: true
mtu: 1400
tunnelProtocol: vxlan
bpf:
  autoMount:
    enabled: true
  # Clamps TCP SYN/SYN-ACK MSS via TC eBPF hooks
  clampMss: true
enableICMPRules: true
```

### eBPF Kernel Program: Manual Dynamic MSS Clamping on Ingress/Egress TC Hook

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Failing to inspect the TCP options in SYN packets allows clients to negotiate an MSS equal to MTU - 40 (e.g., 1460 on a 1500 link). Subsequent full-size data frames will blow past the physical device MTU when encapsulated into the WireGuard interface.
```c
// Flawed: Forwards packet through TC without checking or rewriting TCP MSS for WireGuard tunnels
SEC("tc/egress")
int clamp_mss_bad(struct __sk_buff *skb) {
    // No MSS clamping logic; oversized frames attempt WireGuard encapsulation and get dropped
    return TC_ACT_OK;
}
```

#### Production Standard (Correct)
> **Standard**: Inspects egress TCP packets, identifies SYN handshakes, checks the MSS option header, and rewrites it to clamp to the target MTU minus headers while recalculating L4 checksums via `bpf_l4_csum_replace`.
```c
// Fixed: Validates TCP SYN/SYN-ACK and dynamically clamps MSS to MTU - 40 in BPF layer
#include <linux/bpf.h>
#include <linux/pkt_cls.h>
#include <linux/tcp.h>
#include <linux/ip.h>
#include <bpf/bpf_helpers.h>

#define TARGET_MSS 1360 // 1400 MTU - 40 byte IP/TCP headers

SEC("tc/egress")
int clamp_mss_good(struct __sk_buff *skb) {
    void *data = (void *)(long)skb->data;
    void *data_end = (void *)(long)skb->data_end;
    struct iphdr *iph = data + sizeof(struct ethhdr);

    if ((void *)(iph + 1) > data_end || iph->protocol != IPPROTO_TCP)
        return TC_ACT_OK;

    struct tcphdr *tcph = (void *)iph + (iph->ihl * 4);
    if ((void *)(tcph + 1) > data_end || !tcph->syn)
        return TC_ACT_OK;

    // Parse TCP options and rewrite MSS if larger than TARGET_MSS
    __u8 *opts = (void *)(tcph + 1);
    #pragma unroll
    for (int i = 0; i < 40; i += 4) {
        if ((void *)(opts + i + 4) > data_end)
            break;
        if (opts[i] == 2 && opts[i+1] == 4) { // TCP_OPT_MSS
            __u16 *mss = (__u16 *)&opts[i+2];
            if (__builtin_bswap16(*mss) > TARGET_MSS) {
                __u16 old_mss = *mss;
                *mss = __builtin_bswap16(TARGET_MSS);
                bpf_l4_csum_replace(skb, ((void *)tcph - data) + offsetof(struct tcphdr, check),
                                    old_mss, *mss, sizeof(__u16));
            }
            break;
        }
    }
    return TC_ACT_OK;
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

Kubernetes Cluster Inspector MCP
Inspects active Cilium Node objects, ConfigMaps, and Pod annotations to detect MTU mismatches and eBPF MSS clamping configurations.
Recommended Agent Skills (askills.dev)

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

Cilium CLI Diagnostic Suite
Executes `cilium connectivity test`, `cilium status --verbose`, and `cilium bpf tunnel list` to diagnose WireGuard tunnel MTU drops.
Architectural Specification & Invariant Rationale

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

Cilium eBPF Dynamic WireGuard Path-MTU Clamping Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic MTU sizing and dynamic TCP MSS clamping at the eBPF layer for WireGuard encrypted multi-cloud meshes. Prevents silent packet drops, ICMP 'Fragmentation Needed' blackholes, and throughput degradation caused by uncalculated encapsulation overhead across cloud VPC fabrics. 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: Blind 1500 MTU Overlay Defaults and Static MSS Configurations Causing Encrypted Packet Drops 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 DriftBlind 1500 MTU Overlay Defaults and Static MSS Configurations Causing Encrypted Packet DropsCritical
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 WireGuard MTU derived from the lowest common denominator underlay MTU across cloud providers (e.g., AWS 9001/1500, GCP 1460, Azure 1500) minus WireGuard (60B IPv4 / 80B IPv6) and Geneve/VXLAN overlay headers.

Engineers MUST ALWAYS calculate WireGuard MTU derived from the lowest common denominator underlay MTU across cloud providers (e.g., AWS 9001/1500, GCP 1460, Azure 1500) minus WireGuard (60B IPv4 / 80B IPv6) and Geneve/VXLAN overlay headers.

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 ICMP Type 3 Code 4 (Fragmentation Needed) packets surviving public internet transit across multi-cloud transit gateways, as cloud firewalls routinely drop them.

Engineers MUST NOT rely on ICMP Type 3 Code 4 (Fragmentation Needed) packets surviving public internet transit across multi-cloud transit gateways, as cloud firewalls routinely drop them.

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

Helm and GitOps values MUST explicitly set `encryption.wireguard.enabled

Helm and GitOps values MUST explicitly set `encryption.wireguard.enabled: true` in conjunction with `bpf.autoMount.enabled: true`, `enableICMPRules: true`, and `bpf.clampMss: true` (or custom MSS clamp DaemonSet annotations).

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

Kernel eBPF programs or Cilium network policies MUST clamp TCP MSS inside `TC_ACT_OK` egress filters to `MTU - 40` (IPv4) or `MTU - 60` (IPv6) before WireGuard encapsulation occurs.

Kernel eBPF programs or Cilium network policies MUST clamp TCP MSS inside `TC_ACT_OK` egress filters to `MTU - 40` (IPv4) or `MTU - 60` (IPv6) before WireGuard encapsulation occurs.

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 configurations MUST NEVER leave `cilium.mtu` or `devices` unspecified when crossing cloud boundaries where GCP (1460 MTU) or Azure interconnects participate in the mesh.

Infrastructure configurations MUST NEVER leave `cilium.mtu` or `devices` unspecified when crossing cloud boundaries where GCP (1460 MTU) or Azure interconnects participate in the mesh.

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

Enforces deterministic MTU sizing and dynamic TCP MSS clamping at the eBPF layer for WireGuard encrypted multi-cloud meshes. Prevents silent packet drops, ICMP 'Fragmentation Needed' blackholes, and throughput degradation caused by uncalculated encapsulation overhead across cloud VPC fabrics. 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 (Blind 1500 MTU Overlay Defaults and Static MSS Configurations Causing Encrypted Packet Drops) 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