pkg/bpf and pkg/maps

Active contributors: borkmann, julianwiedmann, ti-mo, joestringer, jrfastab

Purpose

Cilium maintains a typed Go abstraction over Linux BPF maps. pkg/bpf/ provides the low-level map type; pkg/maps/ defines the per-purpose wrappers (conntrack, NAT, LB, ipcache, policy, ...).

Why a custom abstraction even when cilium/ebpf exists? Cilium predates the modern ebpf-go library and has needs the upstream library does not directly cover: pinned-by-default, recoverable across agent restarts, custom Dump() for debug CLIs, and per-map metrics. Today pkg/bpf/ builds on cilium/ebpf for the core map operations and adds the Cilium-specific behaviours on top.

Layout

pkg/bpf/
├── bpf.go            # core types (Map, MapInfo)
├── map.go            # the Map struct
├── map_linux.go      # linux-specific syscalls
├── perf.go           # perf event ring buffer
├── ringbuf.go        # ringbuf
├── pinning/          # pinning bpffs
├── prog/             # program loader helpers
└── ...

pkg/maps/
├── ctmap/            # conntrack tables (IPv4/v6, TCP/UDP/ICMP)
├── nat/              # NAT tables
├── lbmap/            # service load balancer tables
├── policymap/        # per-endpoint policy entries
├── ipcache/          # IP -> identity
├── tunnel/           # encapsulation endpoints
├── neighbormap/      # neighbour cache
├── fragmap/          # fragmentation reassembly
├── recorder/         # pcap recorder map
├── eventsmap/        # perf event ring map
├── signalmap/        # agent <-> dataplane signals
├── auth/             # mutual auth state
├── encrypt/          # IPSec key state
├── eppolicymap/      # endpoint policy aux
├── srv6map/          # SRv6
├── multicast/        # multicast group membership
├── vtep/             # VXLAN VTEP tunnels
├── timestamp/        # time-related helpers
├── bwmap/            # bandwidth manager
├── lxcmap/           # endpoint identity table
├── nodemap/          # node IPs and identities
├── metricsmap/       # exported metrics
├── envoymap/         # Envoy redirect ports
├── egressmap/        # egress gateway rules
└── ...

Per-map pattern

Each pkg/maps/<name>/ package follows the same shape:

type Key struct { /* fixed-size struct that mirrors the BPF map key */ }
type Value struct { /* fixed-size struct that mirrors the value */ }

func NewMap(name string) *bpf.Map { ... }     // construct a typed Map
func (k *Key) String() string { ... }          // human-readable key
func (v *Value) String() string { ... }        // human-readable value
func DumpMap(m *bpf.Map, cb DumpCallback)     // iterate and decode

The cilium-dbg CLI imports each Dump() to render cilium bpf <map> list output. Tests use pkg/maps/fake/ or per-map fakes.

Key abstractions

Type	File	Role
bpf.Map	pkg/bpf/map.go	Wraps a libbpf-style file descriptor with typed key/value sizes.
bpf.MapKey / bpf.MapValue	pkg/bpf/bpf.go	Interfaces every typed key/value implements.
bpf.PerfEventArray	pkg/bpf/perf.go	The monitor ring buffer.
bpf.Pinning	pkg/bpf/pinning/	Manage /sys/fs/bpf/<path> pins so maps survive agent restarts.
bpf.UpdateLock	pkg/bpf/map_linux.go	RW lock around batched map updates.

Integration points

• Datapath: pkg/datapath/loader/ and pkg/datapath/orchestrator/ use these wrappers to programme maps after BPF objects are loaded.
• Endpoint manager: owns per-endpoint maps (policy, ct, nat) and pin lifetimes.
• CLI: cilium-dbg and cilium status consume the dump primitives.

Entry points for modification

• New BPF map: define a sub-package under pkg/maps/<name>/, declare the layout, write a Dump() and tests, plumb it from the relevant cell, and add a cilium bpf <name> subcommand for visibility.
• Map layout migration: bump the map version in pkg/maps/<name>/migrate.go (where present); the agent will recreate the map at startup.
• Custom map type (LRU, hash, array, longest-prefix-match): pick the appropriate MapType in the constructor.

Key source files

File	Purpose
pkg/bpf/map.go	Core Map type.
pkg/bpf/perf.go	Perf event array.
pkg/maps/policymap/policymap.go	Per-EP policy map.
pkg/maps/ctmap/ctmap.go	Conntrack map.
pkg/maps/lbmap/lbmap.go	LB maps.
pkg/maps/ipcache/ipcache.go	IP -> identity map.

See systems/datapath.md and features/load-balancing.md for users of these maps.