Cilium eBPF Datapath Transparent mTLS & SPIFFE Cryptographic Assertion

--- description: Cilium eBPF Datapath Transparent mTLS & SPIFFE Cryptographic Assertion - Enforces cryptographic SPIFFE workload identity validation and transparent mutual TLS directly inside the Cilium eBPF datapath. Non-conforming packets MUST be dropped at the kernel tc/XDP ingress hooks, completely eliminating user-space context switches and protecting L7 proxy stacks against unauthorized traffic. globs: **/cilium-values.yaml, **/cilium-config.yaml, **/cilium-helm-values.yaml, **/policies/**/*.yaml, **/k8s/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-ebpf-transparent-mtls-spiffe-assertion-standard" --- # Cilium eBPF Datapath Transparent mTLS & SPIFFE Cryptographic Assertion > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Bypassing Kernel Datapath Cryptographic Filters and Deferring mTLS to User-Space Envoy Proxies ## System Constraints You are a Principal Software Architect and DevOps Security Engineer enforcing kernel-level identity guarantees using Cilium eBPF and SPIFFE-based transparent mutual TLS. You must ensure that workload authentication never falls back to unauthenticated network labels or raw pod IP evaluation. All network policies must explicitly mandate kernel-verified cryptographic identity assertions via SPIFFE/SPIRE integrations before any packet can be routed to user-space L7 proxies or local sockets. ## Strict Guidelines - Engineers MUST ALWAYS enforce Cilium SPIFFE-based mutual TLS in the Cilium agent configuration (`authentication.mutual.spire.enabled: true`) to link eBPF identity maps with SPIRE cryptographic assertions. - Engineers MUST NOT allow plaintext fallback or silent authentication degradation when a workload fails to negotiate a valid SPIFFE x509-SVID in the kernel datapath. - Code and Helm configurations MUST define explicit `authentication.mode: required` in all sensitive `CiliumNetworkPolicy` and `CiliumClusterwideNetworkPolicy` ingress and egress rules. - Services MUST validate SPIFFE IDs strictly against expected trust domains and workload paths (`spiffe://<trust-domain>/ns/<namespace>/sa/<serviceaccount>`), disallowing broad regex wildcards across foreign trust domains. - Components NEVER route unauthenticated mesh traffic into Envoy or user-space application proxies; packets failing eBPF socket-level authentication MUST be dropped immediately via eBPF TC/XDP ingress programs. ## Bad vs Good Implementations ### CiliumNetworkPolicy Ingress Authentication Specification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This policy depends only on Kubernetes pod labels resolved to IP addresses in the Cilium BPF map. It lacks cryptographic proof of identity, allowing compromised cluster nodes or spoofed internal packets to trigger user-space context switches and reach the application. ```yaml # INSECURE: Relies solely on mutable L3/L4 labels without cryptographic assertion. # Unauthenticated or IP-spoofed packets bypass kernel checks and reach user-space. apiVersion: "cilium.io/v2" kind: CiliumNetworkPolicy metadata: name: secure-payment-ingress namespace: payments spec: endpointSelector: matchLabels: app: payment-service ingress: - fromEndpoints: - matchLabels: app: checkout-frontend toPorts: - ports: - port: "8443" protocol: TCP ``` #### Production Standard (Correct) > **Standard**: The `authentication.mode: required` field instructs Cilium's eBPF datapath to verify mutual TLS and cryptographic SPIFFE identity prior to admitting traffic into the local socket buffer or dispatching to Envoy L7 filters. ```yaml # SECURE: Enforces kernel-level SPIFFE identity verification via Cilium eBPF transparent mTLS. # Packets failing mutual TLS cryptographic assertion are dropped in the kernel datapath. apiVersion: "cilium.io/v2" kind: CiliumNetworkPolicy metadata: name: secure-payment-ingress namespace: payments spec: endpointSelector: matchLabels: app: payment-service ingress: - fromEndpoints: - matchLabels: app: checkout-frontend authentication: mode: required toPorts: - ports: - port: "8443" protocol: TCP rules: http: - method: POST path: "/v1/charge" ``` ### Cilium Helm Configuration for Datapath SPIRE mTLS Integration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Disabling mutual authentication forces Cilium to rely strictly on raw connection tracking IDs without SPIFFE cryptographic assertions, deferring all zero-trust validation to application-level proxies. ```yaml # INSECURE: Mutual authentication disabled; eBPF handles routing without cryptographic identity validation authentication: mutual: enabled: false envoy: enabled: true ``` #### Production Standard (Correct) > **Standard**: Configuring Cilium with SPIRE integration enables node-level SPIFFE identity exchange and populates the eBPF auth map. This ensures datapath-level packet verification without user-space proxy overhead for non-authorized packets. ```yaml # SECURE: Enables SPIRE-backed transparent mTLS directly within the Cilium eBPF datapath authentication: mutual: enabled: true spire: enabled: true adminSocketPath: /run/spire/sockets/admin.sock trustDomain: prod.mesh.internal connectionTimeout: 10s tunnelProtocol: geneve envoy: enabled: true ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Datapath Transparent mTLS & SPIFFE Cryptographic Assertion

Cilium eBPF Datapath Transparent mTLS & SPIFFE Cryptographic Assertion defines an industrial-grade behavioral standard for devops engineering. Enforces cryptographic SPIFFE workload identity validation and transparent mutual TLS directly inside the Cilium eBPF datapath. Non-conforming packets MUST be dropped at the kernel tc/XDP ingress hooks, completely eliminating user-space context switches and protecting L7 proxy stacks against unauthorized traffic. 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: Bypassing Kernel Datapath Cryptographic Filters and Deferring mTLS to User-Space Envoy Proxies 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 Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Bypassing Kernel Datapath Cryptographic Filters and Deferring mTLS to User-Space Envoy Proxies	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 Inconsistency	AI 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:

Engineers MUST ALWAYS enforce Cilium SPIFFE-based mutual TLS in the Cilium agent configuration (`authentication.mutual.spire.enabled

Engineers MUST ALWAYS enforce Cilium SPIFFE-based mutual TLS in the Cilium agent configuration (`authentication.mutual.spire.enabled: true`) to link eBPF identity maps with SPIRE cryptographic assertions.

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.