pkg/hive and StateDB

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

Purpose

pkg/hive/ is Cilium's integration layer for the upstream cilium/hive dependency-injection library, plus helpers shared by every binary that runs as a Hive (cilium-agent, cilium-operator, hubble-relay, clustermesh-apiserver, standalone-dns-proxy).

cilium/statedb is a transactional in-memory table library used to replace ad-hoc, mutex-guarded shared maps. Both libraries originated in this repo and are vendored back in.

Hive

Layout

pkg/hive/
├── hive.go             # the cilium-cli helper to construct a Hive
├── cmd/                # cobra/Hive integration: cmd.Run, hive subcommands
├── job/                # cell.Job: long-running goroutines tied to lifecycle
├── health/             # cell.Health -> agent /healthz integration
└── ...

vendor/github.com/cilium/hive/cell/
├── cell.go             # cell.Cell
├── module.go           # cell.Module
├── provide.go          # cell.Provide
├── invoke.go           # cell.Invoke
├── config.go           # cell.Config + pflag binding
├── lifecycle.go        # cell.Lifecycle
└── ...

Cell anatomy

var Cell = cell.Module(
    "policy",
    "Policy repository and selector cache",
    cell.Provide(newRepository, newSelectorCache),
    cell.Invoke(registerHandlers),
    cell.Config(defaultConfig{}),
)

• cell.Provide — return constructors that can take any other provided type as a parameter, plus optional cell.Lifecycle, cell.Health, *slog.Logger, etc.
• cell.Invoke — run side-effecting initialisation that depends on already-provided types.
• cell.Config — register a pflag-bound config struct.
• cell.Lifecycle — register OnStart / OnStop hooks.
• job.Group — declare goroutines whose lifetime tracks the cell.

Hive resolves the dependency graph at startup, runs all OnStart hooks in order, and reverses the order on shutdown.

CLI integration

Each binary exposes hive subcommands automatically:

cilium-agent hive            # print the cell tree
cilium-agent hive print-objects  # inspect StateDB tables
cilium-agent hive dot-graph  # produce a graphviz file

StateDB

What it is

StateDB is a typed, transactional in-memory database. Each table is an append-only radix tree keyed by one or more indexes, with snapshot reads and copy-on-write writes. Watchers receive a channel that fires when the table changes.

Use cases in Cilium:

• pkg/datapath/tables/devices.go — observed network devices.
• pkg/datapath/tables/route.go — routes to programme.
• pkg/datapath/tables/neigh.go — neighbour entries.
• pkg/loadbalancer/... — service tables (frontend, backend).
• pkg/l2announcer/ — VIPs to announce.
• and more across pkg/.

Reconcilers convert table content into kernel/BPF state. Reconciliation is idempotent and resumable; transactions allow consistent multi-table updates.

Why it matters

Before StateDB, agent-internal state was a tangle of mutex-guarded maps with bespoke notification mechanisms. StateDB gives:

• Atomic multi-table updates.
• Consistent point-in-time reads via snapshots.
• Built-in change watchers without bespoke subscriber lists.
• A natural place to hang reconcilers that programme external state.

Integration points

• Every Cilium binary uses Hive to wire up its cells.
• Every new feature is expected to be a cell.
• StateDB tables are the preferred place for shared mutable agent state.

Key source files

File	Purpose
pkg/hive/hive.go	Hive integration helpers.
pkg/hive/cmd/cmd.go	Cobra/Hive bridge.
vendor/github.com/cilium/hive/	Upstream library.
vendor/github.com/cilium/statedb/	Upstream StateDB.
daemon/cmd/cells.go	Example: agent's full cell graph.

See systems/control-plane.md for the broader narrative.