From aa729590cf46be01721f0a114de5ef6a6f8f023d Mon Sep 17 00:00:00 2001 From: jarvis Date: Sat, 30 May 2026 00:45:04 -0400 Subject: [PATCH] Revise network topology section with verified Tailscale/NetBird facts; add topology diagram (.mmd + .svg) --- README.md | 22 +++++++++++++---- iron-legion-topology.mmd | 53 ++++++++++++++++++++++++++++++++++++++++ iron-legion-topology.svg | 1 + 3 files changed, 71 insertions(+), 5 deletions(-) create mode 100644 iron-legion-topology.mmd create mode 100644 iron-legion-topology.svg diff --git a/README.md b/README.md index d9d25dc..3e2c09e 100644 --- a/README.md +++ b/README.md @@ -111,13 +111,25 @@ Your ansible-pull CI/CD pattern as a standalone template: systemd auto-update ti ## Network Topology Note -The Iron Legion fleet uses **two distinct overlay networks** with zero overlap: +The Iron Legion fleet runs **two completely separate mesh VPN overlays** managed by different companies, on different coordination servers, with zero interoperability between them. -- **Tailscale (`100.x.x.x`)** — Strictly for admin/management traffic. Used by Artemis (AI Foreman), Mark44 (Ollama backend), Mark5 (research agent), and MK7 (swarm manager) for SSH access, monitoring, and agent orchestration. Not exposed to end-user services. -- **NetBird (`100.x.x.x`, separate tailnet)** — Used for user-facing services on Neo: Nextcloud AIO, Vaultwarden, Dockhand, and Trilium Notes. These services are reachable by crew members via NetBird, not Tailscale. Separate tailnet from the Tailscale mesh; both use CGNAT `100.x.x.x` ranges. -- **LAN (`192.168.0.0/18`)** — Fleet subnet via Beryl router. Swarm nodes (MK33–42, MK7) communicate here. External services on Neo do NOT bridge into this subnet. +| Overlay | Technology | Company | IP Range | Use Case | +|---------|-----------|---------|----------|----------| +| **Admin/Management** | **Tailscale** | Tailscale Inc. (Canada) | `100.64.0.0/10` (CGNAT) | SSH access, monitoring, agent orchestration between Artemis, Mark44, Mark5, and MK7. Called a **"tailnet"** in Tailscale terminology. | +| **User-facing services** | **NetBird** | WireTrustee SA (Latvia/EU) | `100.64.0.0/10` (CGNAT, configurable) | Access to Nextcloud AIO, Vaultwarden, Dockhand, and Trilium Notes on Neo. Called a **"NetBird network"** in NetBird terminology. | +| **LAN backbone** | Beryl router (OpenWrt) | N/A | `192.168.0.0/18` | Internal swarm node-to-node traffic (MK33–42, MK7). No VPN involved. | -**Implication for the blueprint buyer:** The Swarm stack (Path A) is entirely self-contained on the LAN segment. Technitium handles internal DNS. Traefik routes HTTP internally. If a buyer wants NetBird-style user-facing services, those are a separate deployment pattern not covered here. +**Critical clarifications:** + +1. **"Tailnet" is Tailscale's proprietary term.** NetBird does not call its mesh a "tailnet" — it uses "network." These are separate, non-interoperable systems from different vendors. + +2. **Same CGNAT range does not mean same network.** Both Tailscale and NetBird default to `100.64.0.0/10` for overlay addressing, but devices on one cannot reach devices on the other. The coordination servers (Tailscale Inc. cloud vs. NetBird cloud/self-hosted) are completely isolated. + +3. **Neo is the boundary.** Neo runs the NetBird client for user-facing services. Neo does **not** participate in the Tailscale tailnet. User-facing services are isolated from the admin/management plane by design. + +4. **The Swarm stack (Path A) is LAN-contained.** Traefik on MK7 routes HTTP internally. Technitium handles LAN DNS. Neither Tailscale nor NetBird is required for the blueprint buyer's stack to function. + +**Buyer implication:** If a homelaber wants the Iron Legion admin/management pattern (Tailscale) AND the user-facing services pattern (NetBird), those are two separate deployments, two separate vendor accounts, and two separate documentation paths. Path A covers only the LAN self-contained stack. --- diff --git a/iron-legion-topology.mmd b/iron-legion-topology.mmd new file mode 100644 index 0000000..6a49d58 --- /dev/null +++ b/iron-legion-topology.mmd @@ -0,0 +1,53 @@ +flowchart TB + subgraph TAILSCALE["🛡️ Tailscale Overlay — Tailscale Inc. (Admin/Management)"] + direction TB + TSCOORD["Tailscale Coordination Server
(proprietary SaaS)"] + TSART["🤖 Artemis (AI Foreman)
100.100.97.18"] + TSM44["🔧 Mark44 (Ollama)
100.75.26.83"] + TSM5["📚 Mark5 (Research)
100.118.67.105"] + TSM7["⚡ MK7 Swarm Manager
100.66.70.51"] + end + + subgraph NETBIRD["🕊️ NetBird Overlay — WireTrustee SA (User-facing)"] + direction TB + NBCOORD["NetBird Coordination Server
(cloud or self-hosted)"] + NBNEO["🖥️ Neo (Nebuchadnezzar)
100.92.224.74"] + NBNC["☁️ Nextcloud AIO"] + NBVW["🔐 Vaultwarden"] + NBDOCK["🐳 Dockhand"] + NBTRIL["📝 Trilium Notes"] + end + + subgraph LAN["🏠 LAN Backbone — Beryl Router (OpenWrt)"] + direction TB + BERYL["🌐 Beryl 7
Gateway + DHCP
192.168.0.0/18"] + MK7LAN["⚡ MK7
Traefik | Technitium | Prometheus
Beszel Hub | Portainer CE | Dozzle | Homepage
192.168.7.7"] + WORKERS["🔩 MK33 / MK34 / MK39 / MK42
Swarm Workers (G9 nodes)
192.168.0.x"] + end + + %% Tailscale connections + TSCOORD ---|"admin mesh
WireGuard tunnel"| TSART + TSCOORD ---|"admin mesh"| TSM44 + TSCOORD ---|"admin mesh"| TSM5 + TSCOORD ---|"admin mesh"| TSM7 + + %% NetBird connections + NBCOORD ---|"user mesh
WireGuard tunnel"| NBNEO + NBNEO ---|"Docker Compose"| NBNC + NBNEO ---|"Docker Compose"| NBVW + NBNEO ---|"Docker Compose"| NBDOCK + NBNEO ---|"Docker Compose"| NBTRIL + + %% LAN connections + BERYL -.->|"DHCP lease"| MK7LAN + BERYL -.->|"DHCP lease"| WORKERS + MK7LAN ---|"swarm overlay"| WORKERS + + %% Cross-plane: management SSH from Tailscale to LAN + TSM7 --"SSH mgmt"--> MK7LAN + TSART --"SSH mgmt"--> MK7LAN + + %% Isolation boundaries + NBNEO -.-x|"🔒 ISOLATED
no route"| LAN + TSART -.-x|"🔒 ISOLATED
no route"| NBNEO + TSM7 -.-x|"🔒 ISOLATED
no route"| NBNEO diff --git a/iron-legion-topology.svg b/iron-legion-topology.svg new file mode 100644 index 0000000..dce6a6b --- /dev/null +++ b/iron-legion-topology.svg @@ -0,0 +1 @@ +

🏠 LAN Backbone — Beryl Router (OpenWrt)

🕊️ NetBird Overlay — WireTrustee SA (User-facing)

🛡️ Tailscale Overlay — Tailscale Inc. (Admin/Management)

admin mesh
WireGuard tunnel

admin mesh

admin mesh

admin mesh

user mesh
WireGuard tunnel

Docker Compose

Docker Compose

Docker Compose

Docker Compose

DHCP lease

DHCP lease

swarm overlay

SSH mgmt

SSH mgmt

🔒 ISOLATED
no route

🔒 ISOLATED
no route

🔒 ISOLATED
no route

Tailscale Coordination Server
(proprietary SaaS)

🤖 Artemis (AI Foreman)
100.100.97.18

🔧 Mark44 (Ollama)
100.75.26.83

📚 Mark5 (Research)
100.118.67.105

⚡ MK7 Swarm Manager
100.66.70.51

NetBird Coordination Server
(cloud or self-hosted)

🖥️ Neo (Nebuchadnezzar)
100.92.224.74

☁️ Nextcloud AIO

🔐 Vaultwarden

🐳 Dockhand

📝 Trilium Notes

🌐 Beryl 7
Gateway + DHCP
192.168.0.0/18

⚡ MK7
Traefik | Technitium | Prometheus
Beszel Hub | Portainer CE | Dozzle | Homepage
192.168.7.7

🔩 MK33 / MK34 / MK39 / MK42
Swarm Workers (G9 nodes)
192.168.0.x

\ No newline at end of file