Other utilities

A reading guide to the many small pkg/ subdirectories that show up across the codebase. Each is a focused library; most are imported by multiple binaries.

Core infrastructure

Package	Purpose
pkg/lock/	Mutex / RWMutex with deadlock checking under -tags lockdebug.
pkg/logging/	slog-based loggers + per-subsystem fields (logfields.LogSubsys, ...).
pkg/metrics/	Prometheus metric registry, helpers for emitting per-cell metrics.
pkg/option/	The legacy DaemonConfig global (incrementally being broken up into per-cell configs).
pkg/version/	Build version + git commit.
pkg/components/	Identifies which binary is running (agent vs operator vs ...).
pkg/defaults/	Compile-time default constants.
pkg/time/	Wall + monotonic clock helpers.

Concurrency and lifecycle

Package	Purpose
pkg/controller/	Periodic reconciliation loops with backoff and metrics.
pkg/eventqueue/	Per-endpoint serial event queue.
pkg/trigger/	Coalesce many events into one delayed callback.
pkg/promise/	One-shot value with subscribers.
pkg/dynamiclifecycle/	Lifecycle for dynamically created components.
pkg/signal/	Plumb agent <-> dataplane signals via a BPF map.
pkg/loadinfo/	CPU / mem load reporting helpers.
pkg/spanstat/	In-memory span-style perf stats.
pkg/safetime/	Clamped timestamps for BPF maps.
pkg/safeio/	I/O helpers with size limits.

Networking primitives

Package	Purpose
pkg/cidr/	CIDR parsing and helpers.
pkg/ip/	IP address utilities.
pkg/ipalloc/	Per-pool IP allocators.
pkg/iana/	IANA protocol constants.
pkg/u8proto/	One-byte protocol encoding.
pkg/byteorder/	Network byte order.
pkg/labels/	Label set type + canonical string forms.
pkg/labelsfilter/	Filter labels per Helm config.
pkg/source/	Source-of-truth tags (Kubernetes, KVStore, Local).
pkg/types/	Core type aliases used across packages.
pkg/mac/	MAC address parsing.
pkg/tuple/	(src, dst, port, proto) tuple type used in conntrack.
pkg/maglev/	Consistent hashing.
pkg/murmur3/	Vendored MurmurHash3 (used in some BPF compatible hashing).
pkg/netns/	Network namespace helpers.
pkg/dial/	Cilium-aware net.Dialer.

Diagnostics

Package	Purpose
pkg/pprof/	pprof endpoint plumbing.
pkg/gops/	gops agent integration.
pkg/debug/	Debug subsystem registry.
pkg/flowdebug/	Verbose datapath logs.
pkg/status/	Per-subsystem status reporter consumed by cilium status.
pkg/healthconfig/	Per-component health reporting config.
pkg/health/	The cilium-health daemon implementation.

Datapath helpers (besides the main pkg/datapath/)

Package	Purpose
pkg/socketlb/	Socket LB program lifecycle.
pkg/cgroups/	cgroup root detection.
pkg/mountinfo/	Linux mount inspection.
pkg/multicast/	Multicast group config.
pkg/mcastmanager/	Multicast manager.
pkg/l2announcer/	L2 (ARP/NDP) announcement.
pkg/wireguard/	WireGuard manager (also see bpf/bpf_wireguard.c).
pkg/auth/	Mutual auth manager.
pkg/maglev/	Consistent hashing.
pkg/bandwidth/ (where present)	EDT-based bandwidth manager.

Config / dynamic config

Package	Purpose
pkg/dynamicconfig/	Hot-reload of certain config values without restart.
pkg/healthconfig/	Cell health policy config.
pkg/svcrouteconfig/	Service routing config.
pkg/lbipamconfig/	LB-IPAM config.
pkg/nodeipamconfig/	Node IPAM config.

CRD-adjacent

Package	Purpose
pkg/annotation/	Kubernetes annotation constants used across the project.
pkg/comparator/	Equality helpers for struct comparisons.
pkg/policyderivative/	(in operator) — derive K8s NetworkPolicy from CCNP for compatibility.

Misc

Package	Purpose
pkg/shortener/	Resource name shortening (Kubernetes 63-char limit).
pkg/idpool/	Generic numeric id pool used by service / proxy port allocation.
pkg/rate/	Rate limiters.
pkg/resiliency/	Retry helpers.
pkg/util/	Bag of misc helpers.
pkg/wal/	Write-ahead log (used in newer reconciliation paths).
pkg/xds/	xDS protocol helpers shared with pkg/envoy/.
pkg/ztunnel/	Integration scaffolding for ztunnel-based service mesh experiments.

Reading order for newcomers

If you are new to the codebase and want a tour, read in this order:

1. pkg/option/config.go — what knobs exist.
2. pkg/hive/ and daemon/cmd/cells.go — the cell graph.
3. pkg/identity/ — the identity model.
4. pkg/policy/repository.go and pkg/policy/distillery.go — policy compilation.
5. pkg/endpoint/endpoint.go — the endpoint lifecycle.
6. pkg/datapath/cells.go and a few bpf/bpf_*.c files — what gets loaded into the kernel.
7. pkg/maps/policymap/policymap.go — the dataplane's view of policy.

That sequence gets you from "what is the agent" to "how a packet ends up allowed or denied".