From 58b410792c25beb9ccbc586bbe96d9c08e6f76da Mon Sep 17 00:00:00 2001 From: Joshua Gilman Date: Fri, 14 Aug 2026 21:28:14 -0700 Subject: [PATCH] docs: adopt canonical device names across documentation Adds reference/naming.md as the canonical name registry, sweeps the networking reference docs and the Lab v2 core network draft to use the canonical names, and records the previously missing nas01 5GbE link to sw-mgmt01 port 8 (PHY-019). --- .../designs/drafts/lab-v2-core-network.md | 94 +++++++++---------- docs/docs/index.md | 2 + docs/docs/reference/hardware-inventory.md | 3 +- docs/docs/reference/naming.md | 51 ++++++++++ docs/docs/reference/networking/hardware.md | 14 +-- .../networking/physical-connections.md | 46 ++++----- docs/mkdocs.yml | 1 + 7 files changed, 134 insertions(+), 77 deletions(-) create mode 100644 docs/docs/reference/naming.md diff --git a/docs/docs/designs/drafts/lab-v2-core-network.md b/docs/docs/designs/drafts/lab-v2-core-network.md index 7bf258e..ff1c32b 100644 --- a/docs/docs/designs/drafts/lab-v2-core-network.md +++ b/docs/docs/designs/drafts/lab-v2-core-network.md @@ -13,12 +13,13 @@ related-decisions: ## Summary -The core network uses a Minisforum VP6630 running VyOS for Layer 3 routing, -firewall policy, and NAT. A MikroTik CRS309-1G-8S+IN handles core Layer 2 -switching and VLAN transport. A TRENDnet TEG-3102WS connects both non-SFP NICs -from each MS-02 to the VP6630 for management/OOB traffic. A second MikroTik -CRS309-1G-8S+IN acts as the home router and connects the lab to the home -network and the internet. +The core network uses `gw01`, a Minisforum VP6630 running VyOS, for Layer 3 +routing, firewall policy, and NAT. `sw-core01`, a MikroTik CRS309-1G-8S+IN, +handles core Layer 2 switching and VLAN transport. `sw-mgmt01`, a TRENDnet +TEG-3102WS, connects both non-SFP NICs from each MS-02 node to `gw01` for +management/OOB traffic. `rtr01`, a second MikroTik CRS309-1G-8S+IN, acts as the +home router and connects the lab to the home network and the internet. Device +names are canonical per the [naming registry](../../reference/naming.md). This design defines device responsibilities, logical topology, configuration requirements, failure boundaries, and verification criteria. Address @@ -27,11 +28,11 @@ ownership are outside this document. ## Goals -- Keep routing and traffic policy on VyOS. -- Keep core VLAN transport and physical switching on the core CRS309-1G-8S+IN. -- Carry MS-02 management/OOB traffic through the TEG-3102WS. +- Keep routing and traffic policy on `gw01`. +- Keep core VLAN transport and physical switching on `sw-core01`. +- Carry MS-02 management/OOB traffic through `sw-mgmt01`. - Route home-to-lab traffic without source NAT. -- Apply source NAT to lab-to-internet traffic on VyOS. +- Apply source NAT to lab-to-internet traffic on `gw01`. - Store network-device configuration in version control. - Validate behavior before saving a deployed configuration. - Preserve a recovery path that does not depend on the primary network path. @@ -52,19 +53,19 @@ ownership are outside this document. ```mermaid flowchart LR - HOME[Home network] --> RTR[Home router CRS309-1G-8S+IN] - RTR -->|Routed transit| VYOS[VP6630 running VyOS] - VYOS -->|802.1Q trunk| CRS[Core CRS309-1G-8S+IN] + HOME[Home network] --> RTR[rtr01 home router] + RTR -->|Routed transit| VYOS[gw01 VyOS gateway] + VYOS -->|802.1Q trunk| CRS[sw-core01 core switch] CRS --> SEGMENTS[Lab network segments] - VYOS -->|Management/OOB uplink| TEG[TEG-3102WS] - TEG -->|Two non-SFP NICs per node| MS02[MS-02 nodes] + VYOS -->|Management/OOB uplink| TEG[sw-mgmt01] + TEG -->|Two non-SFP NICs per node| MS02[lab01, lab02, lab03] ``` -The home router routes traffic between the home network and the VyOS transit -interface. VyOS routes lab prefixes, applies firewall policy, and performs -source NAT for internet egress. The core CRS309-1G-8S+IN carries lab VLANs between -VyOS and connected lab devices. The TEG-3102WS connects directly to the VP6630 -and carries management/OOB traffic for both non-SFP NICs on each MS-02. +`rtr01` routes traffic between the home network and the `gw01` transit +interface. `gw01` routes lab prefixes, applies firewall policy, and performs +source NAT for internet egress. `sw-core01` carries lab VLANs between `gw01` +and connected lab devices. `sw-mgmt01` connects directly to `gw01` and carries +management/OOB traffic for both non-SFP NICs on each MS-02 node. The [physical connection map](../../reference/networking/physical-connections.md) is the authoritative port-to-port cabling record. @@ -72,10 +73,10 @@ authoritative port-to-port cabling record. | Device | Responsibilities | | --- | --- | -| MikroTik CRS309-1G-8S+IN (home router) | Home-network routing, internet access, and the upstream side of the routed lab transit | -| Minisforum VP6630 running VyOS | Lab gateways, route selection, firewall policy, source NAT, the downstream side of the routed transit, and the management/OOB gateway | -| MikroTik CRS309-1G-8S+IN (core switch) | Core VLAN transport, access ports, trunks, and physical link aggregation | -| TRENDnet TEG-3102WS | Layer 2 management/OOB connectivity for both non-SFP NICs on each MS-02 and a direct uplink to the VP6630 | +| `rtr01` (MikroTik CRS309-1G-8S+IN) | Home-network routing, internet access, and the upstream side of the routed lab transit | +| `gw01` (Minisforum VP6630 running VyOS) | Lab gateways, route selection, firewall policy, source NAT, the downstream side of the routed transit, and the management/OOB gateway | +| `sw-core01` (MikroTik CRS309-1G-8S+IN) | Core VLAN transport, access ports, trunks, and physical link aggregation | +| `sw-mgmt01` (TRENDnet TEG-3102WS) | Layer 2 management/OOB connectivity for both non-SFP NICs on each MS-02 and a direct uplink to `gw01` | [ADR-0001](../../decisions/0001-use-vyos-for-layer-3-and-switches-for-layer-2.md) defines the Layer 2 and Layer 3 boundary. @@ -84,24 +85,24 @@ defines the Layer 2 and Layer 3 boundary. The routing design has these invariants: -- The home router has routes for lab prefixes through the VyOS transit address. -- VyOS uses the home router's transit address as its default route. -- VyOS owns the gateway address for every routed lab segment. -- The core CRS309-1G-8S+IN and TEG-3102WS do not route between lab segments. +- `rtr01` has routes for lab prefixes through the `gw01` transit address. +- `gw01` uses the `rtr01` transit address as its default route. +- `gw01` owns the gateway address for every routed lab segment. +- `sw-core01` and `sw-mgmt01` do not route between lab segments. - Home-to-lab traffic retains its original source address. -- VyOS applies source NAT to lab-to-internet traffic. +- `gw01` applies source NAT to lab-to-internet traffic. - Firewall rules distinguish new connections from established reply traffic. ## Traffic Policy -VyOS enforces policy for: +`gw01` enforces policy for: - Home network to lab segments - Lab segments to the home network - Lab segments to the internet - Traffic between routed lab segments -- Traffic addressed to VyOS -- Management/OOB traffic through the TEG-3102WS +- Traffic addressed to `gw01` +- Management/OOB traffic through `sw-mgmt01` - Management traffic addressed to network devices Each firewall rule identifies the source, destination, protocol, destination @@ -111,8 +112,8 @@ the reverse direction. ## Configuration Requirements -VyOS and both switches each have one version-controlled configuration source. -The deployment process: +`gw01`, `sw-core01`, and `sw-mgmt01` each have one version-controlled +configuration source. The deployment process: 1. Renders the effective configuration. 2. Validates syntax and policy before deployment. @@ -127,8 +128,8 @@ Drift detection compares each running configuration with its repository source. ## Management and Recovery Firewall policy limits routine management access to approved source networks. -The TEG-3102WS carries management/OOB traffic from both non-SFP NICs on each -MS-02 directly to the VP6630. +`sw-mgmt01` carries management/OOB traffic from both non-SFP NICs on each +MS-02 node directly to `gw01`. Each network device has a recovery path that remains available when its production configuration or primary network link fails. Recovery credentials do @@ -138,12 +139,12 @@ not reside in device configuration committed to the repository. | Failure | Effect | | --- | --- | -| Home router failure | The lab loses home-network and internet connectivity. Internal lab switching and routing remain available. | -| VP6630 or VyOS failure | Routed lab segments lose their gateways, inter-segment routing, policy enforcement, management/OOB gateway, and internet egress. | -| Core switch failure | Devices connected through the core switch lose Layer 2 connectivity. | -| TEG-3102WS or its VP6630 uplink failure | Both non-SFP NICs on each MS-02 lose management/OOB connectivity. | +| `rtr01` failure | The lab loses home-network and internet connectivity. Internal lab switching and routing remain available. | +| `gw01` failure | Routed lab segments lose their gateways, inter-segment routing, policy enforcement, management/OOB gateway, and internet egress. | +| `sw-core01` failure | Devices connected through `sw-core01` lose Layer 2 connectivity. | +| `sw-mgmt01` or its `gw01` uplink failure | Both non-SFP NICs on each MS-02 lose management/OOB connectivity. | | Routed transit failure | Home-to-lab and lab-to-internet traffic stop. Internal lab traffic remains available within its unaffected Layer 2 and Layer 3 paths. | -| VyOS-to-core-switch trunk failure | VLANs carried by the trunk lose their VyOS gateways. | +| `gw01`-to-`sw-core01` trunk failure | VLANs carried by the trunk lose their `gw01` gateways. | | Invalid configuration | Deployment verification fails and the previous configuration is restored. | ## Verification @@ -152,15 +153,14 @@ A deployment is valid when the observed behavior matches these checks: - Every connected interface reports the assigned link state and speed. - Each VLAN is present only on its assigned access ports and trunks. -- A client in each routed segment reaches its VyOS gateway. -- The home router and VyOS route tables contain the required transit and lab routes. +- A client in each routed segment reaches its `gw01` gateway. +- The `rtr01` and `gw01` route tables contain the required transit and lab routes. - Home-to-lab traffic retains its home-network source address. -- Lab-to-internet traffic uses the VyOS source-NAT address. +- Lab-to-internet traffic uses the `gw01` source-NAT address. - Each permitted firewall flow succeeds. - Each denied firewall flow fails. - Established reply traffic succeeds without enabling a new reverse flow. -- Both non-SFP NICs on each MS-02 connect through the TEG-3102WS. -- MS-02 management/OOB traffic reaches the VP6630 through the TEG-3102WS - uplink. +- Both non-SFP NICs on each MS-02 connect through `sw-mgmt01`. +- MS-02 management/OOB traffic reaches `gw01` through the `sw-mgmt01` uplink. - Management access succeeds only from approved source networks. - A failed deployment restores the previous configuration. diff --git a/docs/docs/index.md b/docs/docs/index.md index 2318f1b..6e4fb38 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -23,6 +23,8 @@ and runbook lives here. ## Reference +- [Device naming](reference/naming.md) is the canonical registry of device + names and the rules for assigning them. - [Hardware inventory](reference/hardware-inventory.md) records every physical device in the lab with its model and specifications. - [Networking hardware](reference/networking/hardware.md) identifies the core diff --git a/docs/docs/reference/hardware-inventory.md b/docs/docs/reference/hardware-inventory.md index d31ebcf..70ddd31 100644 --- a/docs/docs/reference/hardware-inventory.md +++ b/docs/docs/reference/hardware-inventory.md @@ -8,7 +8,8 @@ description: Physical inventory of lab equipment with models, quantities, and sp This document is the physical inventory of lab equipment. It records models, quantities, product references, and concrete specifications. -Role assignments for core network devices live in the +Canonical device names live in the [naming registry](naming.md). Role +assignments for core network devices live in the [networking hardware reference](networking/hardware.md). Installed cabling lives in the [physical connection map](networking/physical-connections.md). IP addressing, VLANs, and other network configuration belong to the network diff --git a/docs/docs/reference/naming.md b/docs/docs/reference/naming.md new file mode 100644 index 0000000..dffc86e --- /dev/null +++ b/docs/docs/reference/naming.md @@ -0,0 +1,51 @@ +--- +title: Device Naming +description: Canonical device names and the rules for assigning them. +--- + +# Device Naming + +Every commissioned device has exactly one canonical name. The canonical name +is: + +- the device's configured system identity (hostname, RouterOS identity, or + web-UI system name), +- the physical label on the chassis, and +- the only device identifier used in documentation and configuration. + +## Rules + +- Names are lowercase DNS-safe labels: `a-z`, `0-9`, and `-`. +- Names are role-based with a zero-padded two-digit ordinal, for example + `gw01`. +- Uncommissioned hardware has no name. The + [hardware inventory](hardware-inventory.md) refers to it by model. A name is + assigned when the device is commissioned. +- Repurposing a device renames it. Update this registry, the device's system + identity, its chassis label, and every document that references the old + name in the same unit of work. + +## Registry + +| Name | Device | Role | +| --- | --- | --- | +| `gw01` | Protectli VP6630 | Lab gateway running VyOS | +| `rtr01` | MikroTik CRS309-1G-8S+IN (unit 1) | Home router and internet edge | +| `sw-core01` | MikroTik CRS309-1G-8S+IN (unit 2) | Core Layer 2 switch | +| `sw-mgmt01` | TRENDnet TEG-3102WS | Management/OOB switch | +| `lab01` | Minisforum MS-02 Ultra (unit 1) | Compute node | +| `lab02` | Minisforum MS-02 Ultra (unit 2) | Compute node | +| `lab03` | Minisforum MS-02 Ultra (unit 3) | Compute node | +| `nas01` | Minisforum N5 Pro | NAS | +| `pikvm01` | PiKVM V4 Plus | KVM-over-IP console | +| `kvm01` | TESmart HKS801-EB23 8x1 KVM | Console switch | +| `ups01` | APC Smart-UPS SMT1000 | UPS | + +## Unnamed hardware + +| Device | Status | +| --- | --- | +| Minisforum UM760 | Shelf spare; named at commissioning | + +Models and physical specifications live in the +[hardware inventory](hardware-inventory.md). diff --git a/docs/docs/reference/networking/hardware.md b/docs/docs/reference/networking/hardware.md index a9582ad..42df2fe 100644 --- a/docs/docs/reference/networking/hardware.md +++ b/docs/docs/reference/networking/hardware.md @@ -5,19 +5,21 @@ description: Core network devices and their assigned roles. # Hardware +Device names are canonical per the [naming registry](../naming.md). + ## Core devices -| Component | Platform | Role | +| Device | Platform | Role | | --- | --- | --- | -| Lab gateway | Minisforum VP6630 running VyOS | Routes lab networks, enforces firewall policy, and performs source NAT | -| Core switch | MikroTik `CRS309-1G-8S+IN` | Carries lab VLANs and connects lab devices at Layer 2 | -| Management/OOB switch | TRENDnet `TEG-3102WS` | Connects both non-SFP NICs from each MS-02 for management/OOB traffic | +| `gw01` | Protectli VP6630 running VyOS | Routes lab networks, enforces firewall policy, and performs source NAT | +| `sw-core01` | MikroTik `CRS309-1G-8S+IN` | Carries lab VLANs and connects lab devices at Layer 2 | +| `sw-mgmt01` | TRENDnet `TEG-3102WS` | Connects both non-SFP NICs from each MS-02 for management/OOB traffic | ## External dependency -| Component | Platform | Role | +| Device | Platform | Role | | --- | --- | --- | -| Home router | MikroTik `CRS309-1G-8S+IN` (second unit of the core-switch model) | Routes the home network, provides internet access, and terminates the upstream side of the routed lab transit | +| `rtr01` | MikroTik `CRS309-1G-8S+IN` | Routes the home network, provides internet access, and terminates the upstream side of the routed lab transit | Models and physical specifications live in the [hardware inventory](../hardware-inventory.md). The diff --git a/docs/docs/reference/networking/physical-connections.md b/docs/docs/reference/networking/physical-connections.md index 05c9885..3064b9d 100644 --- a/docs/docs/reference/networking/physical-connections.md +++ b/docs/docs/reference/networking/physical-connections.md @@ -5,33 +5,34 @@ description: Authoritative port-to-port map of the installed network cabling. # Physical Connections -Each row records one installed cable. Port names match the labels on the device +Each row records one installed cable. Device names are canonical per the +[naming registry](../naming.md). Port names match the labels on the device chassis. `Unlabeled Ethernet port` identifies a physical Ethernet port that has -no printed label. Two MikroTik CRS309-1G-8S+IN units are installed; rows -qualify them by role as `(home router)` and `(core switch)`. +no printed label. ## Connected ports | Connection | Device A | Port A | Device B | Port B | | --- | --- | --- | --- | --- | -| `PHY-001` | MikroTik CRS309-1G-8S+IN (home router) | `SFP+ 1` | Minisforum VP6630 | `SFP+ 1` | -| `PHY-002` | Minisforum VP6630 | `SFP+ 2` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 8` | -| `PHY-003` | Minisforum VP6630 | `Port 2` | TRENDnet TEG-3102WS | `Port 1` | -| `PHY-004` | Minisforum VP6630 | `Port 3` | PiKVM | `Unlabeled Ethernet port` | -| `PHY-005` | Minisforum VP6630 | `Port 4` | TESmart 8x1 KVM | `Unlabeled Ethernet port` | -| `PHY-006` | TRENDnet TEG-3102WS | `Port 2` | LAB01 | `Top Port` | -| `PHY-007` | TRENDnet TEG-3102WS | `Port 3` | LAB01 | `Bottom Port` | -| `PHY-008` | TRENDnet TEG-3102WS | `Port 4` | LAB02 | `Top Port` | -| `PHY-009` | TRENDnet TEG-3102WS | `Port 5` | LAB02 | `Bottom Port` | -| `PHY-010` | TRENDnet TEG-3102WS | `Port 6` | LAB03 | `Top Port` | -| `PHY-011` | TRENDnet TEG-3102WS | `Port 7` | LAB03 | `Bottom Port` | -| `PHY-012` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 1` | LAB01 | `Right SFP 25G` | -| `PHY-013` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 2` | LAB01 | `Left SFP 25G` | -| `PHY-014` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 3` | LAB02 | `Right SFP 25G` | -| `PHY-015` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 4` | LAB02 | `Left SFP 25G` | -| `PHY-016` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 5` | LAB03 | `Right SFP 25G` | -| `PHY-017` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 6` | LAB03 | `Left SFP 25G` | -| `PHY-018` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 7` | NAS | `10GB Port` | +| `PHY-001` | `rtr01` | `SFP+ 1` | `gw01` | `SFP+ 1` | +| `PHY-002` | `gw01` | `SFP+ 2` | `sw-core01` | `Port 8` | +| `PHY-003` | `gw01` | `Port 2` | `sw-mgmt01` | `Port 1` | +| `PHY-004` | `gw01` | `Port 3` | `pikvm01` | `Unlabeled Ethernet port` | +| `PHY-005` | `gw01` | `Port 4` | `kvm01` | `Unlabeled Ethernet port` | +| `PHY-006` | `sw-mgmt01` | `Port 2` | `lab01` | `Top Port` | +| `PHY-007` | `sw-mgmt01` | `Port 3` | `lab01` | `Bottom Port` | +| `PHY-008` | `sw-mgmt01` | `Port 4` | `lab02` | `Top Port` | +| `PHY-009` | `sw-mgmt01` | `Port 5` | `lab02` | `Bottom Port` | +| `PHY-010` | `sw-mgmt01` | `Port 6` | `lab03` | `Top Port` | +| `PHY-011` | `sw-mgmt01` | `Port 7` | `lab03` | `Bottom Port` | +| `PHY-012` | `sw-core01` | `Port 1` | `lab01` | `Right SFP 25G` | +| `PHY-013` | `sw-core01` | `Port 2` | `lab01` | `Left SFP 25G` | +| `PHY-014` | `sw-core01` | `Port 3` | `lab02` | `Right SFP 25G` | +| `PHY-015` | `sw-core01` | `Port 4` | `lab02` | `Left SFP 25G` | +| `PHY-016` | `sw-core01` | `Port 5` | `lab03` | `Right SFP 25G` | +| `PHY-017` | `sw-core01` | `Port 6` | `lab03` | `Left SFP 25G` | +| `PHY-018` | `sw-core01` | `Port 7` | `nas01` | `10GB Port` | +| `PHY-019` | `sw-mgmt01` | `Port 8` | `nas01` | `5GB Port` | ## Unconnected ports @@ -39,8 +40,7 @@ Only ports explicitly identified as unconnected are listed. | Device | Port | | --- | --- | -| Minisforum VP6630 | `Port 1` | -| TRENDnet TEG-3102WS | `Port 8` | +| `gw01` | `Port 1` | IP addresses, VLANs, bonds, interface names, and link settings belong to the network configuration rather than this physical map. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index cf5dbde..e21d559 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -37,6 +37,7 @@ nav: - Drafts: - Lab v2 core network: designs/drafts/lab-v2-core-network.md - Reference: + - Device naming: reference/naming.md - Hardware inventory: reference/hardware-inventory.md - Networking: - Hardware: reference/networking/hardware.md