MakerFLOSS/docs/guides/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	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.