How Cilium Implements Network Policies: A Five‑Layer Deep Dive with Real‑World Configurations

Core Implementation Mechanism

Cilium’s network‑policy enforcement is built on eBPF (extended Berkeley Packet Filter) , differentiating it from traditional iptables solutions.

Layer 1: eBPF Program Loading

When a CiliumNetworkPolicy is created, the Cilium Agent compiles the policy rules into eBPF bytecode and loads the programs into the Linux kernel, attaching them to specific hook points such as a pod’s virtual Ethernet (veth) interface. Running in kernel space allows early‑stage packet filtering with high performance.

Layer 2: Identity System

Instead of IP‑based matching, Cilium assigns each pod a numeric security identity derived from its labels (e.g., all pods with app=frontend share the same ID). This identity remains stable across pod restarts, keeping policies effective even when IPs change.

Layer 3: Policy Storage and Distribution

Policies are stored in eBPF Maps, an efficient kernel‑space key‑value store. At packet arrival, the eBPF program queries these maps to decide whether communication is allowed, e.g., a map entry may map source identity 1234 to target identity 5678 on port 80.

Layer 4: Packet Processing Flow

For a packet from Pod A to Pod B, the egress eBPF program on Pod A checks the outbound policy, reads the destination identity, and looks up the map. If allowed, the packet proceeds; otherwise it is dropped—all within the kernel. The inbound program on Pod B performs a symmetric check.

Layer 5: Supported Policy Types

Cilium supports L3/L4 rules (IP, port) and L7 rules (HTTP method, path, gRPC service). L7 policies are enforced by a user‑space Envoy proxy; packets are redirected to Envoy for deep inspection before being forwarded.

Performance Advantages

Compared with iptables, Cilium’s eBPF implementation benefits from JIT compilation (near‑native speed), O(1) hash‑table lookups versus O(n) chain traversal, and entirely kernel‑space processing that eliminates user‑kernel context switches.

Dynamic Update Mechanism

When a policy changes, the Cilium Agent recomputes affected pod identities and updates eBPF maps atomically. Only the data structures are refreshed, avoiding full program reloads, so policy changes take effect almost instantly without network disruption.

Practical Policy Configuration Examples

Scenario 1: Basic L3/L4 Policy

Three‑tier application (frontend → backend → database). The backend ingress policy allows traffic only from pods labeled app=frontend to port 8080:

apiVersion: "cilium.io/v2"
kind: CiliumNetworkPolicy
metadata:
  name: backend-ingress
  namespace: production
spec:
  endpointSelector:
    matchLabels:
      app: backend
      tier: api
  ingress:
  - fromEndpoints:
    - matchLabels:
        app: frontend
    toPorts:
    - ports:
      - port: "8080"
        protocol: TCP

The policy relies on label‑based identities, so it remains valid even if pod IPs change.

Scenario 2: Namespace‑Based Isolation

Restricts access to a PostgreSQL pod in the production namespace, allowing only backend pods from the same namespace:

apiVersion: "cilium.io/v2"
kind: CiliumNetworkPolicy
metadata:
  name: database-strict-access
  namespace: production
spec:
  endpointSelector:
    matchLabels:
      app: postgres
      role: primary
  ingress:
  - fromEndpoints:
    - matchLabels:
        app: backend
        tier: api
      matchExpressions:
      - key: k8s:io.kubernetes.pod.namespace
        operator: In
        values:
        - production
    toPorts:
    - ports:
      - port: "5432"
        protocol: TCP

Scenario 3: Egress Control with FQDNs and DNS Rules

Limits a frontend pod’s outbound traffic to the backend service, specific external domains, and DNS resolution:

apiVersion: "cilium.io/v2"
kind: CiliumNetworkPolicy
metadata:
  name: frontend-egress-control
  namespace: production
spec:
  endpointSelector:
    matchLabels:
      app: frontend
  egress:
  - toEndpoints:
    - matchLabels:
        app: backend
    toPorts:
    - ports:
      - port: "8080"
        protocol: TCP
  - toFQDNs:
    - matchName: "api.stripe.com"
    - matchPattern: "*.amazonaws.com"
    toPorts:
    - ports:
      - port: "443"
        protocol: TCP
  - toEndpoints:
    - matchLabels:
        k8s:io.kubernetes.pod.namespace: kube-system
        k8s-app: kube-dns
    toPorts:
    - ports:
      - port: "53"
        protocol: UDP
    rules:
      dns:
      - matchPattern: "*.stripe.com"
      - matchPattern: "*.amazonaws.com"

This example highlights the toFQDNs feature, DNS monitoring, and the need to explicitly allow DNS traffic when egress policies are enforced.

Generic Veth Chaining Overview

The generic veth‑chaining plugin enables CNI chaining on top of any CNI that uses a veth device model, allowing multiple plugins to be invoked sequentially.

Architecture: VPC‑CNI + Cilium

The design separates responsibilities into two components: a custom VPC‑CNI that provides pods with real VPC IP addresses and handles routing, and Cilium, which focuses solely on security policy enforcement. VPC‑CNI creates a veth pair, assigns a VPC IP from a pre‑allocated pool, configures routes, and passes the network information to Cilium via the standard CNI input/output mechanism.

When Cilium runs as the second plugin, it receives the already‑configured pod interface, computes the pod’s security identity from its labels, translates applicable CiliumNetworkPolicy objects into eBPF instructions, and attaches them to the veth interface. This non‑intrusive overlay adds a packet‑processing checkpoint without altering the underlying network stack.

Benefits of the Two‑Layer Design

Clear responsibility: VPC‑CNI handles cloud‑specific networking (elastic NICs, IP reclamation, API integration); Cilium provides enterprise‑grade security via eBPF.

Flexibility: Because the plugins follow the standard CNI chaining spec, swapping the security component requires only a configuration change.

Performance: VPC‑CNI runs once at pod creation, while Cilium’s JIT‑compiled eBPF programs process each packet with minimal overhead.

Deployment Details

Each node needs a CNI configuration file (typically under /etc/cni/net.d/) that lists the plugins in order, e.g., first vpc-cni then cilium-cni. When kubelet creates a pod, it reads this file, invokes the VPC‑CNI executable, receives a JSON result containing the assigned IP, gateway, and routes, and then passes that result to the Cilium plugin, which contacts the local Cilium Agent to load the appropriate eBPF programs.

Thus, the combined solution enables CNI components to support full network‑policy functionality with high performance and dynamic updates.