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-ambient-wireguard-mesh

Cilium eBPF Ambient Mesh and Transparent WireGuard Architectural Standard

Mandates strict kernel-level traffic redirection and transparent node-to-node WireGuard encryption via Cilium eBPF, eliminating user-space sidecar proxies and legacy iptables kube-proxy implementations. This invariant enforces socket-level short-circuiting (sockops) and native kernel cryptographic encapsulation to minimize p99 latency overhead and infrastructure compute saturation.

Prohibited Anti-Pattern: Injecting User-Space Envoy Sidecars and Unencrypted Legacy iptables Kube-Proxy Implementations

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Cilium eBPF Ambient Mesh and Transparent WireGuard Architectural Standard - Mandates strict kernel-level traffic redirection and transparent node-to-node WireGuard encryption via Cilium eBPF, eliminating user-space sidecar proxies and legacy iptables kube-proxy implementations. This invariant enforces socket-level short-circuiting (sockops) and native kernel cryptographic encapsulation to minimize p99 latency overhead and infrastructure compute saturation.
globs: **/values*.yaml, **/cilium*.yaml, helm/**/*.yaml, k8s/**/*.yaml, terraform/**/*.tf
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/cilium-ebpf-ambient-wireguard-mesh"
---

# Cilium eBPF Ambient Mesh and Transparent WireGuard Architectural Standard

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Injecting User-Space Envoy Sidecars and Unencrypted Legacy iptables Kube-Proxy Implementations

## System Constraints
You are a Principal Software Architect enforcing Cilium eBPF Ambient Service Mesh with Kernel-Level Transparent WireGuard Encryption. Mandate the complete deprecation of user-space sidecar containers and legacy iptables-based kube-proxy implementations. Ensure all cluster manifests enforce Cilium socket-level load balancing (sockops), transparent node-to-node/pod-to-pod WireGuard cryptographic encapsulation, and sidecarless L7 ingress or ambient proxy daemon routing.

## Strict Guidelines
- Engineers MUST ALWAYS enable strict kube-proxy replacement ('kubeProxyReplacement: true') and eliminate kube-proxy daemonsets to bypass kernel iptables/O(n) sequential packet filtering.
- Engineers MUST ALWAYS configure transparent kernel encryption using WireGuard ('encryption.enabled: true', 'encryption.type: wireguard', 'encryption.nodeEncryption: true') across both pod-to-pod and host-to-host traffic.
- Engineers MUST ALWAYS enable socket-level load balancing ('sockops.enabled: true') to shortcut the TCP/IP stack for intra-node communication directly between socket buffers.
- Services MUST NOT inject sidecar proxy containers (e.g., Istio, Linkerd classic sidecars); Ambient L7 routing must be mediated via Cilium's per-node or standalone Envoy daemonset triggered by CiliumNetworkPolicy.
- Engineers MUST adjust the cluster MTU correctly (lowering MTU by at least 60 bytes for IPv4 or 80 bytes for IPv6) to prevent kernel packet fragmentation under WireGuard tunnel encapsulation.

## Bad vs Good Implementations
### Cilium Helm Configuration: Legacy User-Space Sidecar Proxy vs. eBPF Ambient Mesh with WireGuard

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Operating with kube-proxy enabled retains sequential iptables rule processing that degrades O(N) with service count. Disabling encryption exposes unencrypted intra-cluster node traffic, while injecting user-space sidecars forces packets across multiple user-space/kernel boundaries, elevating p99 tail latency and CPU footprints.
```yaml
# Anti-Pattern: Relying on kube-proxy iptables, sidecars, and unencrypted pod networking
kubeProxyReplacement: "false"
enablement:
  sidecars: true
encryption:
  enabled: false
sockops:
  enabled: false
ipam:
  mode: "cluster-pool"
# Pod specs inject redundant Envoy sidecar proxies
# causing 2 additional user-space context switches per hop
```

#### Production Standard (Correct)
> **Standard**: Replaces kube-proxy with eBPF hash-table lookups (O(1)), activates sockops for direct kernel socket memory zero-copy transfer between local pods, and transparently encrypts all cross-node pod and host traffic inside the Linux kernel via WireGuard without user-space context switches.
```yaml
# Standard: Cilium eBPF Ambient Mesh with Kernel WireGuard & Sockops
kubeProxyReplacement: "true"
k8sServiceHost: "127.0.0.1"
k8sServicePort: "6443"
routingMode: "native"
autoDirectNodeRoutes: true
ipv4NativeRoutingCIDR: "10.244.0.0/16"
sockops:
  enabled: true
bpf:
  masquerade: true
  tproxy: true
enryption:
  enabled: true
  type: "wireguard"
  nodeEncryption: true
mtu: 1420 # Account for 60-byte WireGuard header overhead on 1480/1500 parent interface
envoy:
  enabled: true # In-kernel eBPF redirect to node-level shared Envoy only when L7 inspection is required
```

### Workload Ingress & Security: Sidecar Injection vs. Ambient L7 CiliumNetworkPolicy

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Forcing sidecar injection binds container lifecycle to an external user-space proxy, consumes 0.5-1.0 vCPU overhead per pod, and introduces double TCP handshakes for ingress and egress paths.
```yaml
# Anti-Pattern: Injecting user-space sidecars into deployment annotations
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-service
spec:
  template:
    metadata:
      annotations:
        sidecar.istio.io/inject: "true"
        proxy.istio.io/config: '{"holdApplicationUntilProxyStarts": true}'
    spec:
      containers:
        - name: payment
          image: payment:v1.2.0
```

#### Production Standard (Correct)
> **Standard**: Leaves the pod untouched with zero sidecar overhead. L4 routing and WireGuard encryption happen in kernel eBPF; L7 policy is enforced via Cilium's node-level Ambient Envoy redirect only for matching HTTP rules.
```yaml
# Standard: Pure Ambient Mesh Workload with Cilium L7 Network Policy
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-service
spec:
  template:
    metadata:
      labels:
        app.kubernetes.io/name: payment-service
        io.cilium.service/ambient: "true"
    spec:
      containers:
        - name: payment
          image: payment:v1.2.0
---
apiVersion: "cilium.io/v2"
kind: CiliumNetworkPolicy
metadata:
  name: secure-payment-l7
spec:
  endpointSelector:
    matchLabels:
      app.kubernetes.io/name: payment-service
  ingress:
    - fromEndpoints:
        - matchLabels:
            app.kubernetes.io/name: checkout-service
      toPorts:
        - ports:
            - port: "8080"
              protocol: TCP
          rules:
            http:
              - method: "POST"
                path: "/v1/charge"
```
Recommended MCP Servers (mcp-serverlist.com)

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

Kubernetes Cluster Inspector MCP
Inspects live Kubernetes cluster resources, daemonsets, and CNI configurations to detect sidecars and verify Cilium eBPF status.
Recommended Agent Skills (askills.dev)

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

Cilium CLI Diagnostics Skill
Executes 'cilium status', 'cilium bpf sockops list', and 'cilium encrypt status' to validate kernel WireGuard tunnels and eBPF maps.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Ambient Mesh and Transparent WireGuard Architectural Standard

Cilium eBPF Ambient Mesh and Transparent WireGuard Architectural Standard defines an industrial-grade behavioral standard for devops engineering. Mandates strict kernel-level traffic redirection and transparent node-to-node WireGuard encryption via Cilium eBPF, eliminating user-space sidecar proxies and legacy iptables kube-proxy implementations. This invariant enforces socket-level short-circuiting (sockops) and native kernel cryptographic encapsulation to minimize p99 latency overhead and infrastructure compute saturation. 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: Injecting User-Space Envoy Sidecars and Unencrypted Legacy iptables Kube-Proxy Implementations 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 DriftInjecting User-Space Envoy Sidecars and Unencrypted Legacy iptables Kube-Proxy ImplementationsCritical
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 enable strict kube-proxy replacement ('kubeProxyReplacement

Engineers MUST ALWAYS enable strict kube-proxy replacement ('kubeProxyReplacement: true') and eliminate kube-proxy daemonsets to bypass kernel iptables/O(n) sequential packet filtering.

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 ALWAYS configure transparent kernel encryption using WireGuard ('encryption.enabled

Engineers MUST ALWAYS configure transparent kernel encryption using WireGuard ('encryption.enabled: true', 'encryption.type: wireguard', 'encryption.nodeEncryption: true') across both pod-to-pod and host-to-host 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

Engineers MUST ALWAYS enable socket-level load balancing ('sockops.enabled

Engineers MUST ALWAYS enable socket-level load balancing ('sockops.enabled: true') to shortcut the TCP/IP stack for intra-node communication directly between socket buffers.

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 NOT inject sidecar proxy containers (e.g., Istio, Linkerd classic sidecars)

Services MUST NOT inject sidecar proxy containers (e.g., Istio, Linkerd classic sidecars); Ambient L7 routing must be mediated via Cilium's per-node or standalone Envoy daemonset triggered by CiliumNetworkPolicy.

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

Engineers MUST adjust the cluster MTU correctly (lowering MTU by at least 60 bytes for IPv4 or 80 bytes for IPv6) to prevent kernel packet fragmentation under WireGuard tunnel encapsulation.

Engineers MUST adjust the cluster MTU correctly (lowering MTU by at least 60 bytes for IPv4 or 80 bytes for IPv6) to prevent kernel packet fragmentation under WireGuard tunnel encapsulation.

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 Ambient Mesh and Transparent WireGuard Architectural Standard critical for AI coding assistants?

Mandates strict kernel-level traffic redirection and transparent node-to-node WireGuard encryption via Cilium eBPF, eliminating user-space sidecar proxies and legacy iptables kube-proxy implementations. This invariant enforces socket-level short-circuiting (sockops) and native kernel cryptographic encapsulation to minimize p99 latency overhead and infrastructure compute saturation. 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 (Injecting User-Space Envoy Sidecars and Unencrypted Legacy iptables Kube-Proxy Implementations) 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