Architecture

Cilium has two halves: a userspace control plane written in Go that runs on every Kubernetes node, and a kernel dataplane written in C and loaded into the Linux kernel as eBPF programs. The control plane watches Kubernetes, computes policy, and writes BPF maps; the dataplane reads those maps and enforces decisions on every packet.

High-level component map

graph TD
    subgraph cluster["Kubernetes cluster"]
        APIServer[kube-apiserver]
        Operator[cilium-operator<br/>cluster-wide controller]
        Relay[hubble-relay<br/>cluster aggregator]
        ClusterMeshAPI[clustermesh-apiserver<br/>cluster identity export]
    end

    subgraph node["Each node"]
        Agent[cilium-agent<br/>userspace control plane]
        Envoy[Envoy proxy<br/>L7 enforcement]
        BPF["eBPF programs<br/>(bpf/bpf_*.c)"]
        Maps["BPF maps<br/>(policy, lb, ct, ipcache, ...)"]
        DNS[Cilium DNS proxy]
    end

    APIServer -->|watch CRDs, pods, services| Agent
    APIServer -->|watch| Operator
    Operator -->|allocate IPs, GC identities| APIServer
    Agent -->|programs| BPF
    Agent <-->|reads/writes| Maps
    BPF <-->|read| Maps
    Agent -->|xDS config| Envoy
    Envoy -->|L7 verdict| Agent
    Agent -->|flow events| Relay
    DNS -->|FQDN policy| Agent
    Agent -->|cluster info| ClusterMeshAPI

Where to find each piece

Component	Path	What it does
Cilium agent	daemon/, pkg/	One DaemonSet pod per node. Owns the dataplane and the local endpoint state.
eBPF dataplane	bpf/	C source for bpf_lxc.c, bpf_host.c, bpf_overlay.c, bpf_xdp.c, bpf_sock.c, etc. Compiled with clang/LLVM and loaded by the agent.
Operator	operator/	One leader-elected Deployment. Handles cluster-wide IPAM, CES batching, identity GC, CRD lifecycle.
CLI	cilium-cli/	cilium user-facing CLI (install, connectivity test, status).
Debug CLI	cilium-dbg/	In-pod CLI shipped with the agent for low-level debugging (cilium endpoint list, cilium bpf ct list, ...).
Hubble	hubble/, hubble-relay/, pkg/hubble/	Per-node observability + cluster-wide gRPC aggregator.
Cluster Mesh	clustermesh-apiserver/, pkg/clustermesh/, pkg/kvstore/	Multi-cluster identity, services, and connectivity.
Standalone DNS proxy	standalone-dns-proxy/	Optional out-of-process DNS proxy for L7 FQDN policy.
Health	cilium-health/	Per-node health probe (cilium-health status).

Packet path

The dataplane follows the same packet path on every node, regardless of cloud or routing mode.

sequenceDiagram
    participant Pod as Source pod
    participant LXC as bpf_lxc (TC ingress)
    participant CT as conntrack map
    participant Pol as policy map
    participant LB as lb maps
    participant Host as bpf_host
    participant Net as Network
    Pod->>LXC: send packet
    LXC->>CT: lookup connection
    LXC->>Pol: identity vs identity policy
    Pol-->>LXC: allow/deny/redirect
    LXC->>LB: service translation if needed
    LXC->>Host: forward
    Host->>Net: route or encapsulate
    Net->>Host: incoming packet
    Host->>LXC: deliver to destination pod

The dataplane is implemented in bpf/bpf_lxc.c (per-pod programs), bpf/bpf_host.c (per-host programs), bpf/bpf_overlay.c (VXLAN/Geneve), and bpf/bpf_xdp.c (XDP fast-path for north-south LB and DDoS defence).

Control-plane structure: Hive

The agent is built on a dependency-injection framework called Hive (pkg/hive/). Each capability is packaged as a cell.Cell that declares its dependencies and lifecycle hooks. daemon/cmd/ wires the cells together. New features are added by writing a cell that publishes its types and consuming the agent's existing cells (k8s clientset, BPF maps, policy repository, endpoint manager, ...).

See systems/control-plane.md for the cell graph and how dependency injection drives startup ordering.

State sources

The agent reconciles state from three sources of truth:

1. Kubernetes API server — pods, services, endpoints, CiliumNetworkPolicy, CiliumIdentity, CiliumEndpoint, CiliumClusterwide* CRDs.
2. kvstore (etcd, optional) — used by Cluster Mesh for cross-cluster identity and service propagation. See pkg/kvstore/.
3. Local on-disk state — restored after agent restart from /var/run/cilium/state/ (endpoints, BPF maps via pinned mounts).

When watching one source produces a change, the agent recomputes the policy verdict for affected endpoints, regenerates BPF programs if required, and updates BPF maps in place to avoid traffic disruption.

Identity model

Cilium does not use IPs in policy decisions. Instead, every workload is mapped to a numeric security identity derived from its labels (pkg/identity/). Policy maps express "identity X is allowed to talk to identity Y on port Z". Identities are allocated in a CRD-backed allocator (pkg/identity/cache/, pkg/allocator/) and propagated to every node so that any node can validate any packet without round-tripping to the API server. See features/identity-and-security.md.

L7 path: Envoy and the DNS proxy

L3/L4 enforcement happens entirely in eBPF. When policy requires L7 awareness (HTTP method, gRPC call, Kafka topic, FQDN), packets are redirected to a userspace proxy:

• Envoy (pkg/envoy/, pkg/proxy/) — handles HTTP, gRPC, TLS termination, and the Kubernetes Gateway API. Configured live via xDS from the agent.
• DNS proxy (pkg/fqdn/) — intercepts DNS responses to learn IP-to-FQDN mappings, then programs toFQDNs policy via the ipcache.

See systems/envoy-l7-proxy.md and features/network-policy.md.