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

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