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