resctrl-mon: add NRI plugin for per-pod resctrl monitoring groups

[cmcantalupo]

Description

Add nri-resctrl-mon, a standalone NRI plugin that creates per-pod resctrl monitoring groups (mon_groups) to support passive monitoring of Application Energy Telemetry (AET) via consumers.

Motivation

Userspace daemon approaches to resctrl mon_group management suffer from a fork race: a container's first threads can execute before the daemon writes their PIDs into the mon_group's tasks file, causing energy attribution gaps. By using the NRI PostCreateContainer hook, this plugin assigns container PIDs to mon_groups before exec/fork, eliminating the race entirely.

What's included

Commit 1: Core plugin

• Plugin source (main.go, plugin.go, resctrl.go, state.go)
• Unit tests (plugin_test.go, resctrl_test.go)
• Dockerfile following the nri-memory-qos pattern
• Helm chart (Chart.yaml, values.yaml, templates, JSON schema)
• Documentation (new "monitoring" category, plugin docs, Helm docs)
• Sample configuration

Commit 2: Counter snapshots

• Snapshot store (snapshot.go, snapshot_test.go) that mirrors the resctrl mon_data layout at /run/nri-resctrl-mon/<pod-uid>/
• On first PID write: records .begin counter files and creates symlinks to live kernel event files
• On last container stop: reads final counters as .end files, removes symlinks, writes completed_at
• Consumers compute lifetime energy as end − begin with no new parsing logic
• Completed snapshots are pruned after a configurable TTL (default 5 min)
• New config keys: snapshotDir, snapshotTTL

Snapshot directory layout

/run/nri-resctrl-mon/<pod-uid>/
    created_at
    completed_at
    mon_data/
        mon_PERF_PKG_00/
            core_energy          → symlink to live resctrl counter (removed on stop)
            core_energy.begin    # counter value at mon_group creation
            core_energy.end      # counter value at mon_group removal
        mon_L3_00/
            llc_occupancy
            llc_occupancy.begin
            llc_occupancy.end
            ...

Design decisions

• Hook selection: PostCreateContainer ensures PIDs are assigned before any user code runs.
• Kernel RMID management: mkdir/rmdir on resctrl delegates RMID lifecycle to the kernel, avoiding userspace exhaustion bugs.
• Symlink-based live access: While a pod is running, consumers can read live counters via symlinks without knowing the resctrl path. Symlinks are removed atomically when .end files are written (before the mon_group directory is removed), so dangling symlinks never exist.
• Crash recovery: Synchronize re-creates mon_groups for running pods on plugin restart.
• Minimal privileges: SYS_ADMIN + DAC_OVERRIDE only (no privileged: true).

Testing

• Unit tests cover plugin lifecycle, resctrl operations, snapshot store, TTL pruning, and path traversal rejection.
• Manually validated full pod lifecycle (create → run → delete → prune) on a Clearwater Forest system with k3s, confirming correct .begin/.end values and symlink cleanup.

Stats

24 files changed, 2861 insertions(+), 1 deletion(-)