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.
|