sjat 4dc975062a

Build docs site / build (push) Successful in 49s

Details

Build slides / build (push) Successful in 1m11s

Details

docs(hardware): reconcile rack01 to as-mounted layout and document cabling

Rebuild rack01 from the physically remounted hardware:
- Correct stale positions/ports/outlets for pp01, pp02, sw01, pdu01-04
- Model shelves as 1U trays (towers stand above without consuming rack U's);
  add shf02 and empty half-depth shf03/shf04
- Add ups01/ups02; reseat nas01/02 and sw02-05; move srv04-07 onto shf02
- Add `wan` hardware kind; add WAN demarcation hosts wan01 (active) and
  wan02 (staging)
- Document full live network wiring: srv01-07 -> pp02 -> sw01 (LAN) and
  srv01 eth0 -> pp02 -> pp01 -> wan01 (WAN); keep non-active lines
  (wan2, working-table patches, sw01 mgmt) in notes only
- Regenerate hardware index + rack01 elevation/network/power artifacts

Also includes the in-progress generator updates (gen_rack.py, gen_overview.py,
Makefile, tests) that the regenerated artifacts depend on.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-30 21:31:48 +02:00

5.1 KiB

Raw Permalink Blame History

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`
WAN uplink / ISP demarcation	`wan`	`wan`	`wan01`

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.

5.1 KiB Raw Permalink Blame History Unescape Escape