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: ebpf-tc-dsr-conntrack-bypass

eBPF TC Direct Server Return (DSR) Service Mesh Invariant

Enforces eBPF Traffic Control (TC) Direct Server Return (DSR) networking invariants across Kubernetes and edge service meshes. Bypasses intermediate node SNAT and kernel conntrack table saturation by dispatching ingress traffic via tunnel encapsulation and rewriting egress headers directly to client endpoints at the pod veth interface.

Prohibited Anti-Pattern: SNAT/IPVS Double-Hop Routing Causing nf_conntrack Table Exhaustion and Asymmetric Packet Drops

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: eBPF TC Direct Server Return (DSR) Service Mesh Invariant - Enforces eBPF Traffic Control (TC) Direct Server Return (DSR) networking invariants across Kubernetes and edge service meshes. Bypasses intermediate node SNAT and kernel conntrack table saturation by dispatching ingress traffic via tunnel encapsulation and rewriting egress headers directly to client endpoints at the pod veth interface.
globs: k8s/**/*.yaml, helm/**/*.yaml, infra/**/*.ts, src/infra/**/*.ts
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/ebpf-tc-dsr-conntrack-bypass"
---

# eBPF TC Direct Server Return (DSR) Service Mesh Invariant

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: SNAT/IPVS Double-Hop Routing Causing nf_conntrack Table Exhaustion and Asymmetric Packet Drops

## System Constraints
You are a Principal Infrastructure & Systems Architect enforcing eBPF Traffic Control (TC) Direct Server Return (DSR) invariants in cloud-native service meshes. You must prevent node-level SNAT performance degradation, conntrack table saturation (nf_conntrack: table full, dropping packet), and asymmetric routing failures by enforcing strict eBPF TC egress header translation and tunnel encapsulation standards.

## Strict Guidelines
- Engineers MUST ALWAYS configure eBPF DSR mode with Geneve or IP-in-IP tunnel encapsulation when pod endpoints span multi-node or L3 routing domains to preserve original VIP and port metadata.
- Engineers MUST NOT rely on intermediate node SNAT (IPVS or iptables MASQUERADE) for cluster ingress load balancing under high connection churn environments.
- Code SHOULD enforce Path MTU Discovery (PMTUD) and account for encapsulation overhead (e.g., 50-byte Geneve header delta) to avoid packet truncation and blackholing at eBPF TC hooks.
- Services MUST configure backend eBPF TC egress hooks (SCHED_ACT/SCHED_CLS on veth pairs) to rewrite pod source IP/port with the public Service VIP before transmitting directly to client gateways.
- Components NEVER allow asymmetric return packets to transit the Linux host netfilter/conntrack stack without NOTRACK or complete eBPF host-routing bypass.

## Bad vs Good Implementations
### Cilium eBPF DSR and Conntrack Bypass Configuration via Pulumi TypeScript

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Configuring loadBalancer.mode as 'snat' with hostRouting disabled forces every external request through Linux conntrack and SNAT on the ingress node. High-throughput edge traffic quickly exhausts the host conntrack table, introduces node hops, and discards original client IPs.
```typescript
import * as k8s from "@pulumi/kubernetes";

// ANTI-PATTERN: Default SNAT/IPVS routing causes nf_conntrack table explosion,
// asymmetric routing drops on backend return, and extra intermediate hops.
export const brokenCiliumConfig = new k8s.helm.v3.Release("cilium-cni", {
  chart: "cilium",
  version: "1.15.0",
  repositoryOpts: { repo: "https://helm.cilium.io/" },
  values: {
    kubeProxyReplacement: "partial",
    loadBalancer: {
      mode: "snat", // Forces SNAT on node ingress; destroys client IP and floods conntrack
    },
    bpf: {
      masquerade: true,
      hostRouting: false, // Forces packets through host netfilter
    },
    tunnel: "vxlan",
  },
});
```

#### Production Standard (Correct)
> **Standard**: Configuring DSR with Geneve dispatch and eBPF native host routing enables service pods to reply directly to the upstream client with the Service VIP. This bypasses the ingress node on return, circumvents nf_conntrack limits, eliminates SNAT CPU overhead, and maintains full MTU awareness.
```typescript
import * as k8s from "@pulumi/kubernetes";

// PRODUCTION INVARIANT: Direct Server Return (DSR) using eBPF TC programs.
// Client VIP is preserved, return traffic bypasses ingress LB nodes directly to client gateway,
// and conntrack allocation is completely avoided via eBPF host routing.
export const resilientCiliumConfig = new k8s.helm.v3.Release("cilium-cni", {
  chart: "cilium",
  version: "1.15.0",
  repositoryOpts: { repo: "https://helm.cilium.io/" },
  values: {
    kubeProxyReplacement: "true",
    loadBalancer: {
      mode: "dsr", // Enables Direct Server Return
      dsrDispatch: "geneve", // Preserves VIP and client L4 context across L3 boundaries
      acceleration: "native", // Attaches eBPF directly to native TC/XDP drivers
    },
    bpf: {
      masquerade: false,
      hostRouting: true, // Direct routing bypasses host netfilter / iptables
      conntrackAccounting: false,
    },
    routingMode: "tunnel",
    tunnelProtocol: "geneve",
    devices: ["eth0", "bond0"],
    autoDirectNodeRoutes: true,
    pmtuDiscovery: {
      enabled: true, // Prevents ICMP blackholing due to Geneve header expansion
    },
  },
});
```
Recommended MCP Servers (mcp-serverlist.com)

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

Cilium Mesh Inspector MCP
Inspects eBPF map states, TC BPF attachment points, and conntrack metrics across Kubernetes cluster nodes.
Recommended Agent Skills (askills.dev)

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

bpftool TC Inspector
CLI utility to dump TC filter attachments, inspect BPF map entries, and verify DSR packet translation.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF TC Direct Server Return (DSR) Service Mesh Invariant

eBPF TC Direct Server Return (DSR) Service Mesh Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces eBPF Traffic Control (TC) Direct Server Return (DSR) networking invariants across Kubernetes and edge service meshes. Bypasses intermediate node SNAT and kernel conntrack table saturation by dispatching ingress traffic via tunnel encapsulation and rewriting egress headers directly to client endpoints at the pod veth interface. 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: SNAT/IPVS Double-Hop Routing Causing nf_conntrack Table Exhaustion and Asymmetric 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 DriftSNAT/IPVS Double-Hop Routing Causing nf_conntrack Table Exhaustion and Asymmetric 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 configure eBPF DSR mode with Geneve or IP-in-IP tunnel encapsulation when pod endpoints span multi-node or L3 routing domains to preserve original VIP and port metadata.

Engineers MUST ALWAYS configure eBPF DSR mode with Geneve or IP-in-IP tunnel encapsulation when pod endpoints span multi-node or L3 routing domains to preserve original VIP and port metadata.

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 intermediate node SNAT (IPVS or iptables MASQUERADE) for cluster ingress load balancing under high connection churn environments.

Engineers MUST NOT rely on intermediate node SNAT (IPVS or iptables MASQUERADE) for cluster ingress load balancing under high connection churn environments.

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 enforce Path MTU Discovery (PMTUD) and account for encapsulation overhead (e.g., 50-byte Geneve header delta) to avoid packet truncation and blackholing at eBPF TC hooks.

Code SHOULD enforce Path MTU Discovery (PMTUD) and account for encapsulation overhead (e.g., 50-byte Geneve header delta) to avoid packet truncation and blackholing at eBPF TC 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.
4

Services MUST configure backend eBPF TC egress hooks (SCHED_ACT/SCHED_CLS on veth pairs) to rewrite pod source IP/port with the public Service VIP before transmitting directly to client gateways.

Services MUST configure backend eBPF TC egress hooks (SCHED_ACT/SCHED_CLS on veth pairs) to rewrite pod source IP/port with the public Service VIP before transmitting directly to client gateways.

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 allow asymmetric return packets to transit the Linux host netfilter/conntrack stack without NOTRACK or complete eBPF host-routing bypass.

Components NEVER allow asymmetric return packets to transit the Linux host netfilter/conntrack stack without NOTRACK or complete eBPF host-routing bypass.

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 eBPF TC Direct Server Return (DSR) Service Mesh Invariant critical for AI coding assistants?

Enforces eBPF Traffic Control (TC) Direct Server Return (DSR) networking invariants across Kubernetes and edge service meshes. Bypasses intermediate node SNAT and kernel conntrack table saturation by dispatching ingress traffic via tunnel encapsulation and rewriting egress headers directly to client endpoints at the pod veth interface. 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 (SNAT/IPVS Double-Hop Routing Causing nf_conntrack Table Exhaustion and Asymmetric 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

eBPF