KNELPerf/scheduler/README.md

🗓️ KNELPerf scheduler — breakout from Ultix (#826)

The scheduling subsystem of the Ultix workstation repo (~/projects/ultix) was broken out here on 2026-09-06 and redesigned for fleet use. Ultix remains the live workstation deployment; this module is the going-forward home.

What was ported and what changed

Ultix source	KNELPerf destination	Redesign delta
staged/ukrrs-daynight.sh	daynight/knelperf-daynight.sh	Slice targets, devices, and every knob are conf-driven lists (was: hardcoded reachableceo-* slices, /dev/sdb, user 1001). Slice specs are slice:weight:cpus:memhigh so any host participates.
staged/etc-ukrrs-daynight.conf	daynight/knelperf-daynight.conf.example	Self-documenting example; post-upgrade values live per-host, not in comments of the engine.
staged/systemd/reachableceo-{day,night}profile.*	daynight/systemd/knelperf-*	Generic units; the conf — never a sed-edit of a live timer — is the only value source.
staged/reachableceo-perfsnap.sh	collectors/knelperf-perfsnap.sh	Watched cgroups/interfaces are env-driven lists; no baked-in uids/NICs. Same pipe-delimited log format.
staged/ukrrs-psi-textfile.sh	collectors/knelperf-psi-textfile.sh	Cgroup glob + metric prefix env-driven; emits for any slice namespace.
staged/proxmox-ctl.sh	proxmox/proxmox-ctl.sh	Ported as-is (was already generic + guarded: PROTECTED vmids, graceful shutdown only, pvesh local-or-token).

Not ported (stay workstation-local in ultix): mkacct.sh account tiers, 21-priority-ladder.sh GUI-first cgroup ladder (host-specific by design), gateway-ensure.sh, RTMP stack.

Lessons learned carried forward (from ultix REPORT.md / TRACKING.md)

1. Slice= is create-time only — set-property cannot set it; caps go in unit drop-ins AND live via set-property --runtime.
2. CPUWeight on user-manager units is inert until cpu is in the parent's cgroup.subtree_control — enable it explicitly.
3. IOWeight is inert under the none I/O scheduler (virtio) — don't bother.
4. Guests have no cpufreq driver — governor tuning is PVE-host-side only.
5. Reboot must land in DAY mode: slice unit files carry day defaults; the profile engine only does runtime mutations. Non-negotiable invariant.
6. Persistent=true timers replay missed flips at boot (intentional).
7. Duplicated truth is the failure mode: one conf file per host is the only place values live (the 07:00 sed-edit of a live timer was the wart that motivated this redesign).
8. Measure before touching; collectors install data, they tune nothing.

Fleet rollout model

• Workstation (ultix-streaming): stays on its live ultix units until this module is UAT'd, then converges onto knelperf-* units.
• PVE nodes: daynight engine applies to host-level services + VM cgroup scopes (qemu.slice children) via the same conf mechanism; timers install from daynight/systemd/.
• Everything deploys through AWX job templates (KNELIAC) per the 100%-IaC mandate; this repo supplies the scripts, not ad-hoc ssh.

See docs/ARCHITECTURE.md for the full baseline → audit → tweak → re-baseline program this module feeds.

Docs live on Discourse — this repo is the executable source of truth. Perf topic: https://community.turnsys.com/t/328