docs(hardware): hardware naming scheme design

notes/dev/specs/2026-06-24-hardware-naming-scheme.md

@@ -0,0 +1,117 @@
+# Hardware Naming Scheme Design
+
+**Date:** 2026-06-24
+**Status:** Approved
+
+## Goal
+
+Settle a single, clear hardware naming scheme for the MakerFLOSS rack that the
+team can grow within, before more devices are documented. The scheme assigns
+every physical device a stable identifier and pushes everything that changes
+over time (which cluster a node serves, its role) into frontmatter, so the
+identifier never has to be renamed when hardware is repurposed.
+
+## Context
+
+- Hardware is documented one-file-per-device under `docs/hardware/*.md`, with the
+  file name equal to the device identifier (enforced by `scripts/gen_overview.py`).
+- Current names are inconsistent: compute uses an org/brand prefix
+  (`mf00`–`mf04`), infrastructure uses kind prefixes (`pdu01/02`, `sw01`, `pp01`).
+- The inventory to be documented is a mix of rack and home-office gear, grouped
+  into clusters (TaPPaaS production + four test clusters) plus crosscutting
+  power/network gear. Stationary PCs will sit on rack shelves.
+- Hardware moves between test clusters over time, so cluster membership is a
+  changeable attribute, not an intrinsic property of a device.
+
+## Decisions
+
+### 1. Identifier nature (mixed)
+
+- **Compute nodes (stationary PCs) and managed switches:** the identifier *is*
+  the device's real OS/DNS hostname. It must be DNS-safe (lowercase letters,
+  digits, hyphens) and stable — renaming costs OS/DNS/Ansible churn.
+- **Passive gear (UPS, PDU/power strip, patch panel, unmanaged switch):** the
+  identifier is a documentation/physical-label id only; the device has no OS.
+
+### 2. Format
+
+`<kind-abbrev><NN>` — a kind abbreviation followed by a **2-digit zero-padded
+sequence**, **globally unique within a kind**, starting at `01`. The number is
+just "next free"; it encodes nothing — not cluster, rack, role, or port count.
+A 10-port and a 24-port switch are still `sw01` and `sw02`.
+
+### 3. Kind abbreviation table
+
+The prefix equals the `kind` field, so the name is self-describing.
+
+| Device | `kind` | abbrev | example |
+|--------|--------|--------|---------|
+| Stationary PC / server | `server` | `srv` | `srv01` |
+| Switch (managed or dumb) | `switch` | `sw` | `sw01` |
+| Patch / network panel | `patch-panel` | `pp` | `pp01` |
+| PDU / power strip | `pdu` | `pdu` | `pdu01` |
+| UPS | `ups` | `ups` | `ups01` |
+| Shelf | `shelf` | `shf` | `shf01` |
+
+Existing enum kinds not yet in the rack reuse their natural short form when
+first used (`ap` → `ap`, `kvm` → `kvm`, `sbc` → `sbc`, `laptop` → `lt`,
+`desktop` → `dt`, `blank` → `blank`); register the chosen abbrev in this table
+at that time.
+
+Distinguishing attributes (port/outlet count, managed vs dumb, speed) live in
+frontmatter (`ports:`, `outlets:`, …), never in the name.
+
+### 4. Grouping in frontmatter, not the name
+
+- `cluster:` — one of `tappaas`, `test-1`, `test-2`, `test-3`, `test-4`, or
+  `shared` (crosscutting gear that spans clusters: power strips, shared patch
+  panels). Editing this field is the entire cost of moving a node between
+  clusters.
+- `role:` — optional, free-form (e.g. `control`, `worker`); added only where it
+  earns its keep.
+
+A future generator step may group/table hardware by `cluster`, exactly as the
+hardware index groups by `kind` today. That is **not** part of this scheme — the
+scheme only fixes the field and its allowed values.
+
+### 5. Exceptions
+
+Cloud / externally-named hosts keep their real FQDN as the identifier (e.g.
+`makerfloss.eu`) instead of `srvNN`. They are not racked and DNS owns the name.
+Such hosts carry no `rack:` field and need no `cluster:`.
+
+### 6. Growth rules
+
+- **New device class:** add the `kind` to the `hardware` enum in
+  `scripts/overview_config.yml` and register a short abbrev in the table above.
+- **New grouping:** add a `cluster:` value.
+- **More than 99 of one kind:** widen that kind's sequence to 3 digits.
+- **More racks:** already supported via the `rack:` field (Phase 1).
+- **Multiple sites:** deferred until real (YAGNI); a site prefix or field can be
+  added without disturbing existing names.
+
+## Migration of current names
+
+| Current | New | Notes |
+|---------|-----|-------|
+| `mf00` | `srv01` | "TaPPaaS node 1" → `cluster: tappaas` |
+| `mf01` | `srv02` | set `cluster:` per its real assignment |
+| `mf02` | `srv03` | |
+| `mf03` | `srv04` | |
+| `mf04` | `srv05` | |
+| `pdu01`, `pdu02` | unchanged | already conform |
+| `sw01`, `pp01` | unchanged | already conform |
+| `makerfloss.eu` | unchanged | cloud FQDN exception |
+
+The `mf0x` machines are staging placeholders, so renaming is cheap now. The
+rename touches their files, the `power:`/`links:` references to them in
+`pdu*`/`sw*`/`pp*` and sibling host files, and the regenerated artifacts under
+`docs/hardware/index.md` and `docs/infrastructure/racks/`. The cluster
+assignments for `srv02`–`srv05` are provisional until real values are given;
+`srv01` = `tappaas` is the one known mapping.
+
+## Out of scope
+
+- Choosing the *best distribution* of hardware across clusters.
+- Building a generator view that groups by `cluster` (possible future work).
+- Real cluster assignments beyond `srv01` = TaPPaaS.