9d7b4684c4
Move the naming-scheme spec from notes/dev/specs/ into docs/guides/ so it publishes to docs.makerfloss.eu, add it under the Hardware nav, and link it from the editing guide. Repoint the stale references in CLAUDE.md and the migration plan to the new path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
117 lines
5 KiB
Markdown
117 lines
5 KiB
Markdown
# 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` | cluster omitted until a real assignment is given |
|
||
| `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.
|