Cilium agent

Active contributors: aanm, joestringer, joamaki, gandro, christarazi

Purpose

The Cilium agent (binary cilium-agent, image quay.io/cilium/cilium) is the userspace control plane that runs as a DaemonSet on every Kubernetes node. It watches the API server and the optional kvstore, computes per-endpoint policy, programs the eBPF dataplane, manages the L7 proxy (Envoy), and exports state via REST and gRPC.

Directory layout

daemon/
├── main.go                 # ~15 lines: build a Hive and run it
├── cmd/
│   ├── root.go             # cobra root command
│   ├── cells.go            # the cell graph that defines the agent
│   ├── daemon.go           # the legacy `Daemon` struct, shrinking over time
│   ├── daemon_main.go      # CLI flags + DaemonConfig binding
│   ├── endpoint_restore.go # restoring endpoints after agent restart
│   └── ...
├── healthz/                # /healthz endpoint
├── infraendpoints/         # internal endpoint definitions
├── k8s/                    # k8s-specific startup helpers
└── restapi/                # REST API server wiring

Key abstractions

Type	File	Role
cmd.Agent	daemon/cmd/cells.go	The root cell.Module that defines the agent's cell graph.
cmd.NewAgentCmd	daemon/cmd/root.go	Builds the cobra command and wires Hive into Cobra's RunE.
Daemon	daemon/cmd/daemon.go	The legacy "everything bag" struct that still owns endpoint restore and the restapi.
daemonConfig	daemon/cmd/daemon_main.go	Maps every CLI flag onto option.DaemonConfig and other typed configs.
endpointRestoreState	daemon/cmd/endpoint_restore.go	Restores endpoints from /var/run/cilium/state/ after restart.

How it works

graph TD
    Main[daemon/main.go] -->|hive.New(cmd.Agent)| Hive
    Hive -->|cells.go| K8sCells[k8s clientset cell]
    Hive --> EndpointMgr[endpoint manager cell]
    Hive --> PolicyRepo[policy repository cell]
    Hive --> Datapath[datapath orchestrator cell]
    Hive --> Envoy[envoy + proxy cell]
    Hive --> Hubble[hubble cell]
    Hive --> RESTAPI[REST API cell]
    Hive --> Restore[endpoint restore]
    K8sCells -->|watches| APIServer[kube-apiserver]
    PolicyRepo -->|computes| EndpointMgr
    EndpointMgr -->|regen| Datapath
    Datapath -->|loader| BPF[eBPF programs]
    EndpointMgr -->|xDS| Envoy
    Hubble -->|monitor events| Relay[hubble-relay]

Startup is driven by hive.Run(). Each cell's OnStart hook fires in dependency order:

1. Boot — pkg/version/, signal handling, pidfile, gops.
2. Kubernetes — clientset, watchers, informers (pkg/k8s/).
3. Identity — allocator (pkg/identity/cache/).
4. Policy — repository and selector cache (pkg/policy/).
5. Datapath — link discovery, route table, BPF loader (pkg/datapath/).
6. Endpoint manager — restore, regenerate (pkg/endpoint/, pkg/endpointmanager/).
7. Envoy — proxy startup and xDS server (pkg/envoy/, pkg/proxy/).
8. Hubble — local observer + gRPC server (pkg/hubble/).
9. REST API + health — daemon/restapi/, daemon/healthz/.

Shutdown reverses the order; OnStop hooks drain queues and persist endpoint state to disk.

Integration points

• Kubernetes: all CRDs and core resources via informers in pkg/k8s/watchers/.
• kvstore: optional, used by Cluster Mesh and historical paths (pkg/kvstore/).
• CNI: plugins/cilium-cni/ writes endpoint metadata to daemon/cmd/cni/.
• Envoy: xDS over Unix socket; bootstrap config emitted by pkg/envoy/.
• Hubble Relay: the agent's gRPC observer endpoint (pkg/hubble/relay/) is consumed by hubble-relay.
• Operator: the operator allocates pod CIDRs and identity GC; the agent only consumes those allocations.

Entry points for modification

• To add a new agent capability, write a cell under pkg/<name>/cell.go, then include it in daemon/cmd/cells.go.
• To add a new flag, prefer cell-local config (cell.Config(...)) over daemonConfig. Update Helm values under install/kubernetes/cilium/values.yaml so it can be exposed to users.
• To add a new REST endpoint, edit api/v1/openapi.yaml, run make generate-api, and implement the handler in daemon/restapi/.

Key source files

File	Purpose
daemon/main.go	Entry point; builds Hive and runs the cobra command.
daemon/cmd/cells.go	The complete cell graph for the agent.
daemon/cmd/daemon.go	The legacy Daemon struct.
daemon/cmd/daemon_main.go	CLI flag definitions.
daemon/cmd/endpoint_restore.go	Endpoint state restoration.
daemon/healthz/	Health probe handler.
daemon/restapi/	REST API wiring.

See systems/control-plane.md for the Hive cell model in depth, and systems/datapath.md for the agent's relationship with the BPF dataplane.