67 lines
3.2 KiB
Markdown
67 lines
3.2 KiB
Markdown
|
# Evaluate the homelab's hardware capacity and workload placement
|
||
|
|
|
||
|
|
Assess current allocation headroom, HA posture, and workload placement against declared
|
||
|
|
intent, and write a tracked report to `docs/hardware/reviews/`. On-demand only;
|
||
|
|
scheduled runs are deferred (see `docs/TODO.md` 8.4).
|
||
|
|
|
||
|
|
## Reference material
|
||
|
|
|
||
|
|
- `docs/hardware/reference.md` — physical node specs, workload allocations, and the
|
||
|
|
free-text intent columns (`criticality`, `ha_intent`, `profile`, `constraints`, `growth`).
|
||
|
|
- `scripts/capacity-scan.py` — deterministic scan; emits JSON with keys `nodes`,
|
||
|
|
`workloads`, `usage`, `warnings`.
|
||
|
|
|
||
|
|
## Process
|
||
|
|
|
||
|
|
### Phase 0 — gather facts
|
||
|
|
|
||
|
|
Run `python3 scripts/capacity-scan.py` and parse its JSON output:
|
||
|
|
|
||
|
|
- `nodes` — per-node physical totals, allocated totals, `ram_headroom_pct`, and the
|
||
|
|
`oversubscribed` flag.
|
||
|
|
- `workloads` — per-workload allocation rows from `reference.md`.
|
||
|
|
- `usage` — live usage stats if available; check `usage.available`. If `false`, every
|
||
|
|
recommendation in the report is **intent-based, not usage-based** — state this
|
||
|
|
prominently in the report header.
|
||
|
|
- `warnings` — drift findings the scan has already detected (reference vs Terraform/inventory).
|
||
|
|
|
||
|
|
### Phase 1 — read intent
|
||
|
|
|
||
|
|
Read `docs/hardware/reference.md` for the free-text columns the scan does not parse:
|
||
|
|
`criticality`, `ha_intent`, `profile`, `constraints`, and `growth`, plus the
|
||
|
|
"Capacity notes" section at the bottom of the file.
|
||
|
|
|
||
|
|
### Phase 2 — reason across five dimensions
|
||
|
|
|
||
|
|
Produce concrete, actionable recommendations. Tag every item with its type and the
|
||
|
|
basis it rests on (**intent-based** vs **usage-based**):
|
||
|
|
|
||
|
|
1. **HA / redundancy** — anti-affinity violations (e.g. an HA pair co-located on one
|
||
|
|
node), single points of failure, HA posture that looks like overkill for the
|
||
|
|
declared `criticality`, and high-criticality workloads with no redundancy.
|
||
|
|
2. **Right-sizing** — over- or under-provisioned workloads compared to their `profile`.
|
||
|
|
Today this is intent-based (declared allocation vs profile); flag explicitly that it
|
||
|
|
becomes usage-based once the `gather_usage()` hook in the scan script is live.
|
||
|
|
3. **Placement / moves** — oversubscribed nodes (`oversubscribed: true` or low
|
||
|
|
`ram_headroom_pct`) and constraint-driven relocations indicated by `constraints`.
|
||
|
|
4. **Upgrade timing** — cross-reference `growth` notes against current headroom to
|
||
|
|
estimate a rough runway before a node upgrade is needed.
|
||
|
|
5. **Drift** — surface every entry in the scan's `warnings` array verbatim.
|
||
|
|
|
||
|
|
### Phase 3 — write the report
|
||
|
|
|
||
|
|
Save the report to `docs/hardware/reviews/YYYY-MM-DD-capacity.md` and overwrite
|
||
|
|
`docs/hardware/reviews/latest.md` with the same content.
|
||
|
|
|
||
|
|
Report structure:
|
||
|
|
|
||
|
|
- **One-line summary** — overall health signal (e.g. "All nodes within headroom;
|
||
|
|
two HA violations detected").
|
||
|
|
- **Run metadata** — date, reviewed commit SHA, `usage.available` status.
|
||
|
|
- **Section per dimension** — each with concrete, actionable items; every item states
|
||
|
|
its basis (intent-based or usage-based) and the evidence behind it.
|
||
|
|
- **Follow-up prompt** — a generated, copy-pasteable prompt for the next review or
|
||
|
|
for acting on the top finding.
|
||
|
|
|
||
|
|
Commit the report files per CLAUDE.md git conventions.
|