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-dsr-dynamic-drain-invariant

Cilium 1.17 eBPF Direct-Server-Return Dynamic Drain Invariant

Guarantees deterministic socket state preservation and active TCP connection draining during rolling Kubernetes node evictions under Cilium Direct Server Return (DSR) mode. Mandates strict kernel connection tracking synchronization and graceful termination life-cycles to eliminate RST spikes without relying on userspace reverse-proxy sidecars.

Prohibited Anti-Pattern: Immediate Pod Termination Severing Active eBPF DSR Conntrack Tuples and Causing Silent Client RST Storms

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Cilium 1.17 eBPF Direct-Server-Return Dynamic Drain Invariant - Guarantees deterministic socket state preservation and active TCP connection draining during rolling Kubernetes node evictions under Cilium Direct Server Return (DSR) mode. Mandates strict kernel connection tracking synchronization and graceful termination life-cycles to eliminate RST spikes without relying on userspace reverse-proxy sidecars.
globs: deploy/helm/**/*.yaml, deploy/kustomize/**/*.yaml, k8s/**/*.yaml, infrastructure/**/*.tf, charts/**/values.yaml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/cilium-ebpf-dsr-dynamic-drain-invariant"
---

# Cilium 1.17 eBPF Direct-Server-Return Dynamic Drain Invariant

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Immediate Pod Termination Severing Active eBPF DSR Conntrack Tuples and Causing Silent Client RST Storms

## System Constraints
You are a Principal Infrastructure & Networking Architect enforcing the Cilium 1.17 eBPF Direct-Server-Return Dynamic Drain Invariant. You must ensure that all Kubernetes workloads running behind Cilium eBPF DSR correctly propagate dynamic endpoint draining, align terminationGracePeriodSeconds with conntrack TCP FIN/CLOSE timeout tables, and execute zero-downtime draining without sidecar intervention.

## Strict Guidelines
- Engineers MUST configure Cilium Helm values with `bpf.lbTerminationGracePeriod` enabled and set to at least the maximum client session drain threshold when DSR is enabled (`loadBalancer.mode=dsr`).
- Deployments exposed via DSR Service backends MUST define `terminationGracePeriodSeconds` strictly greater than the application drain timeout plus the Cilium eBPF map cleanup delay.
- Pods exposed to DSR backends MUST implement a `preStop` hook or application-level graceful shutdown listener that stops accepting new TCP connections while servicing in-flight requests, preventing eBPF map entry churn.
- Engineers MUST NOT rely on userspace proxies (e.g., Envoy or NGINX sidecars) for TCP connection draining when eBPF host routing (`bpf.hostRouting=true`) and DSR are active, as asymmetrical return traffic bypasses userspace conntrack tracking.
- Workload manifests MUST configure `readinessProbe` to fail immediately upon receiving SIGTERM to signal Cilium's endpoint monitor to transition the backend state to `Terminating` and activate dynamic drain tables in the eBPF datapath.

## Bad vs Good Implementations
### Cilium Helm Values and Kubernetes Deployment DSR Drain Specification

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: When the node evicts the Pod, `terminationGracePeriodSeconds: 10` is insufficient. Cilium's eBPF DSR conntrack table removes the reverse-NAT tuple immediately upon backend deletion, causing ongoing TCP connections returning directly to clients to fail silently or emit RST packets.
```yaml
# Flawed: DSR enabled without eBPF dynamic drain termination guardrails
cilium:
  loadBalancer:
    mode: dsr
  bpf:
    hostRouting: true
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-gateway
spec:
  replicas: 3
  template:
    spec:
      terminationGracePeriodSeconds: 10
      containers:
        - name: gateway
          image: payment-gw:v1.17.0
          ports:
            - containerPort: 8443
```

#### Production Standard (Correct)
> **Standard**: Enables `bpf.lbTerminationGracePeriod: 60` in Cilium 1.17, allowing the eBPF datapath to preserve connection-tracking state for terminating endpoints. The pod lifecycle `preStop` hook coordinates with a 75s termination grace period, ensuring active TCP streams cleanly FIN without RST injection.
```yaml
# Correct: Cilium 1.17 dynamic drain enabled with coordinated backend lifecycle
cilium:
  loadBalancer:
    mode: dsr
    dsrDispatch: opt
  bpf:
    hostRouting: true
    lbTerminationGracePeriod: 60
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-gateway
spec:
  replicas: 3
  template:
    spec:
      terminationGracePeriodSeconds: 75
      containers:
        - name: gateway
          image: payment-gw:v1.17.0
          ports:
            - containerPort: 8443
          lifecycle:
            preStop:
              exec:
                command: ["/bin/sh", "-c", "sleep 5 && /app/drain --timeout=45"]
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8443
```
Recommended MCP Servers (mcp-serverlist.com)

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

Kubernetes Cluster Inspector MCP
Inspects live Kubernetes service descriptors, endpointslices, and pod graceful termination phases.
Recommended Agent Skills (askills.dev)

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

Cilium eBPF Datapath Validator
Validates eBPF load-balancing maps, DSR session tracking, and termination grace periods via `cilium bpf lb list`.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium 1.17 eBPF Direct-Server-Return Dynamic Drain Invariant

Cilium 1.17 eBPF Direct-Server-Return Dynamic Drain Invariant defines an industrial-grade behavioral standard for devops engineering. Guarantees deterministic socket state preservation and active TCP connection draining during rolling Kubernetes node evictions under Cilium Direct Server Return (DSR) mode. Mandates strict kernel connection tracking synchronization and graceful termination life-cycles to eliminate RST spikes without relying on userspace reverse-proxy sidecars. 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: Immediate Pod Termination Severing Active eBPF DSR Conntrack Tuples and Causing Silent Client RST Storms 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 DriftImmediate Pod Termination Severing Active eBPF DSR Conntrack Tuples and Causing Silent Client RST StormsCritical
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 Cilium Helm values with `bpf.lbTerminationGracePeriod` enabled and set to at least the maximum client session drain threshold when DSR is enabled (`loadBalancer.mode=dsr`).

Engineers MUST configure Cilium Helm values with `bpf.lbTerminationGracePeriod` enabled and set to at least the maximum client session drain threshold when DSR is enabled (`loadBalancer.mode=dsr`).

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

Deployments exposed via DSR Service backends MUST define `terminationGracePeriodSeconds` strictly greater than the application drain timeout plus the Cilium eBPF map cleanup delay.

Deployments exposed via DSR Service backends MUST define `terminationGracePeriodSeconds` strictly greater than the application drain timeout plus the Cilium eBPF map cleanup delay.

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

Pods exposed to DSR backends MUST implement a `preStop` hook or application-level graceful shutdown listener that stops accepting new TCP connections while servicing in-flight requests, preventing eBPF map entry churn.

Pods exposed to DSR backends MUST implement a `preStop` hook or application-level graceful shutdown listener that stops accepting new TCP connections while servicing in-flight requests, preventing eBPF map entry churn.

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 NOT rely on userspace proxies (e.g., Envoy or NGINX sidecars) for TCP connection draining when eBPF host routing (`bpf.hostRouting=true`) and DSR are active, as asymmetrical return traffic bypasses userspace conntrack tracking.

Engineers MUST NOT rely on userspace proxies (e.g., Envoy or NGINX sidecars) for TCP connection draining when eBPF host routing (`bpf.hostRouting=true`) and DSR are active, as asymmetrical return traffic bypasses userspace conntrack tracking.

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

Workload manifests MUST configure `readinessProbe` to fail immediately upon receiving SIGTERM to signal Cilium's endpoint monitor to transition the backend state to `Terminating` and activate dynamic drain tables in the eBPF datapath.

Workload manifests MUST configure `readinessProbe` to fail immediately upon receiving SIGTERM to signal Cilium's endpoint monitor to transition the backend state to `Terminating` and activate dynamic drain tables in the eBPF datapath.

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 1.17 eBPF Direct-Server-Return Dynamic Drain Invariant critical for AI coding assistants?

Guarantees deterministic socket state preservation and active TCP connection draining during rolling Kubernetes node evictions under Cilium Direct Server Return (DSR) mode. Mandates strict kernel connection tracking synchronization and graceful termination life-cycles to eliminate RST spikes without relying on userspace reverse-proxy sidecars. 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 (Immediate Pod Termination Severing Active eBPF DSR Conntrack Tuples and Causing Silent Client RST Storms) 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