feat: eBPF uSID datapath control-plane packages

[privateip]

Summary

Third PR in the eBPF uSID datapath stack (on top of #281 usid.c/uformat and #282 codegen toolchain).

Adds the Go control-plane library that will drive the TC-BPF program added in #281:

• preflight — kernel capability gate (BTF, HASH maps, SCHED_CLS, bpf_fib_lookup with VRF-tbid support), run before attempting to load anything.
• usidmap — typed read/write/reconcile API for the three kernel maps the program consults (locator_table, function_table, vrf_table).
• attach — load/pin/attach/detach/watch lifecycle for the TC-BPF ingress hook, including netlink-driven re-attachment on interface or route change. Interface selection is auto-detected but can be overridden via the new GALACTIC_CNI_EBPF_INTERFACES env var (internal/config) for multi-homed nodes.
• metrics — Prometheus collector plus load/attach event counters.

Every package here is independently unit-testable against fakes (fake kernel tables, a mock kernel prober, fake closers) — nothing outside this tree calls into it yet, so this remains inert until the CNI/GC/installer wiring PRs later in the stack.

Test plan

• go build ./...
• go vet ./...
• go test ./internal/plumbing/ebpf/... ./internal/config/...
• task lint (0 issues)

Part of the eBPF uSID datapath cutover stack (base: #282).

[ecv]

ecv reviewed this through an AI shell, apologies. Questions, not verdicts.

Two things read well first. Re-attaching every resolved interface, rather than only the ones that changed, is the right call, and the FRR story in the comment shows exactly what the diff-only version missed. The generation cutoff scheme is correct as written.

1. Register writes the whole value struct and leaves Packets, Bytes and LastSeenNs at zero. It runs on every CNI ADD, and again on every retry inside the k8s retry closure, and the comments call that safe because Register overwrites. But those three fields are the datapath's own counters, they reach Prometheus as counters, and they are what R8's gate reads to prove an Argument carried no traffic before cutover. A re-registered entry reads as untouched even after carrying traffic. Should Register read the old value and keep the counters, or should the counters live in a map the control plane never writes?

2. The filter attaches at priority 1 in direct-action mode, and usid.c returns TC_ACT_OK for traffic it does not claim. In direct-action TC_ACT_OK ends the chain, so no filter at a higher priority number on that device runs. Cilium attaches to native device ingress, and the vmtap docs say pods carry Cilium identity, so both run on these hosts. Does something keep the two off the same device? TC_ACT_UNSPEC is the verdict that hands the packet to the next filter — any reason not to use it on the two fail-open paths?

3. Load pins every map by name and reuses whatever pin it finds. Change a value struct or a max_entries and the load fails against the old pin. That failure is fatal, and feat: Grant CNI DaemonSet BPF privileges and wire up e2e #288 puts it behind a liveness probe, so the first such change crashloops every node until someone deletes the pins by hand. vrf_value grew egress_kind this cycle, behavior is still unread, and vrf_table sizing is an open question on feat: eBPF vrf_table GC sweep and control-daemon startup #287. What handles the first schema change — a version in the pin path, or delete and recreate on mismatch?

4. When a netlink subscription channel closes, Watch sets it to nil and keeps looping. Once both close it selects on ctx alone and watches nothing, and nothing logs that. If Watch returns an error, the goroutine in StartWatching logs once and exits, and nothing subscribes again. Health covers the program, the maps and the filter, but not whether the watcher still runs. Should a dead watcher fail health?

5. Only netlink events drive re-attachment. tc filter del raises no link or route event, so nothing reconciles until some unrelated event arrives. Health notices, the liveness probe fires, the container restarts, and startup re-attaches — so a cleared filter costs a restart. Should a failed health check drive a reconcile before it fails the probe?

6. Preflight refuses to start without /sys/kernel/btf/vmlinux, but feat: Add TC-BPF uSID program and bit-layout library #281's package doc says the program reads no kernel structs and needs no vmlinux.h. One of the two is wrong. On a kernel that does not expose BTF, does this refuse to run a datapath that would have worked?

7. Auto-detection lists IPv6 routes from the main table only. A default route in another table stays invisible, and an underlay carrying specific prefixes and no default offers nothing to find. Both end in a fatal startup that only the environment override clears. Is the underlay default always in the main table on these nodes?

8. ensureClsact lists qdiscs and then adds one. Another agent adding clsact between those two calls turns QdiscAdd into an EEXIST error. Cilium adds clsact to these same devices. Worth treating EEXIST as success?

Smaller: ResolveInterfaces dumps the whole IPv6 route table on every health tick and every debounced event. And CLOCK_MONOTONIC reads right to me — it survives a container restart, the pins die with the node, and the zero fallback leaks rather than misdelivers.

[ecv]

and it LIKED this one 😂