Control plane (Hive)

Active contributors: joamaki, gandro, aanm, ti-mo, joestringer

Purpose

The control plane is the userspace half of Cilium that watches Kubernetes, computes policy, and programs the datapath. As of v1.13+ it is structured as a graph of dependency-injected Hive cells rather than a single monolithic constructor. Hive lives at pkg/hive/ and is built on the dig DI library.

The model: every subsystem (k8s clientset, identity allocator, policy repository, endpoint manager, datapath loader, ...) is a cell.Cell. Cells declare what they consume (cell.In) and what they provide (cell.Out). Hive resolves the graph, calls constructors in dependency order, runs OnStart hooks, and on shutdown runs OnStop hooks in reverse.

Directory layout

pkg/hive/
├── hive.go            # the Hive type
├── cmd/               # cobra integration (cmd.Run)
├── job/               # cell.Job: long-running goroutines tied to lifecycle
├── health/            # health reporting plumbing
└── ...

vendor/github.com/cilium/hive/  # the upstream cilium/hive library
vendor/github.com/cilium/statedb/  # the StateDB transactional table library

The cilium/hive and cilium/statedb libraries originated in this repo and were extracted into separate Go modules; both are vendored.

Key abstractions

Type	File	Role
cell.Cell	vendor/github.com/cilium/hive/cell/	The fundamental unit — provide constructors, register lifecycle hooks.
cell.Module	same	Group of cells with a stable name and description.
cell.Lifecycle	same	Register OnStart / OnStop hooks tied to the agent's lifetime.
cell.Config	same	Bind a struct to CLI flags via pflag tags.
job.Group	vendor/github.com/cilium/hive/job/	Schedule goroutines whose lifetime is tied to a cell.
statedb.DB / Table	vendor/github.com/cilium/statedb/	Transactional in-memory tables (radix-tree backed). Used for routes, devices, services, neigh, ...

How the agent wires it together

graph LR
    AgentMain[daemon/main.go]
    AgentCells[daemon/cmd/cells.go]
    K8s[k8s.Cell<br/>pkg/k8s]
    Identity[identitycache.Cell<br/>pkg/identity/cache]
    Policy[policy.Cell<br/>pkg/policy]
    Endpoint[endpointmanager.Cell<br/>pkg/endpointmanager]
    Datapath[datapath.Cell<br/>pkg/datapath]
    Envoy[envoy.Cell<br/>pkg/envoy]
    Hubble[hubble.Cell<br/>pkg/hubble]
    REST[restapi.Cell<br/>daemon/restapi]

    AgentMain -->|hive.New| AgentCells
    AgentCells --> K8s
    AgentCells --> Identity
    AgentCells --> Policy
    AgentCells --> Endpoint
    AgentCells --> Datapath
    AgentCells --> Envoy
    AgentCells --> Hubble
    AgentCells --> REST
    K8s --> Identity
    K8s --> Policy
    Identity --> Policy
    Policy --> Endpoint
    Endpoint --> Datapath
    Endpoint --> Envoy
    Endpoint --> Hubble

The cell graph is the canonical place to read what the agent does, in what order, and with what dependencies. daemon/cmd/cells.go lists every top-level cell module. Operator wiring lives in operator/cmd/cells.go. Hubble Relay, clustermesh-apiserver, and standalone-dns-proxy follow the same pattern.

StateDB tables

The agent's mutable state is moving from per-package mutex-protected maps to StateDB tables: append-only typed tables with a transaction system, secondary indexes, change watchers, and reconciliation primitives.

Examples:

• pkg/datapath/tables/devices.go — observed network devices.
• pkg/datapath/tables/route.go — desired and observed routes.
• pkg/loadbalancer/... — service tables.
• pkg/l2announcer/ — VIPs to announce via ARP/NDP.

Reconcilers under pkg/datapath/orchestrator/ and pkg/loadbalancer/reconciler/ watch the tables and program the kernel/BPF accordingly. This gives consistent transactional semantics across multiple writers.

CLI debugging of the cell graph

Hive ships CLI tools to inspect the live graph:

cilium-agent hive
cilium-agent hive print-objects
cilium-agent hive dot-graph

These print every cell, its dependencies, its config, and (for print-objects) the StateDB tables it owns.

Integration points

• Cobra: Hive integrates with cobra via pkg/hive/cmd/. The agent's root command runs the hive on RunE.
• Logging: every cell receives a child logger via cell.In, scoped by module name.
• Metrics: pkg/metrics/cell.go exposes Prometheus metrics including per-cell health.
• Health: cell.Health lets each cell report degraded/ok/error states; aggregated by daemon/healthz/.

Entry points for modification

• Adding a feature: create pkg/<feature>/cell.go, expose a Cell, depend on what you need via constructor parameters, then include it from daemon/cmd/cells.go.
• Replacing an old import-time singleton: convert it to a cell that provides the type, change consumers to take it via constructor parameters.
• Ordering issues: Hive resolves the constructor order from the dependency graph; if you need a side-effect to run after another, make it depend on something only the predecessor publishes.

Key source files

File	Purpose
daemon/cmd/cells.go	Agent cell graph.
operator/cmd/cells.go	Operator cell graph.
pkg/hive/hive.go	Hive integration glue.
vendor/github.com/cilium/hive/cell/	Upstream cell library.
vendor/github.com/cilium/statedb/	Transactional state library.

See how-to-contribute/patterns-and-conventions.md for cell-writing conventions.