tepichord/milner

Fork 0

Update architecture document for network topology #15

New issue

Closed

opened 2026-08-19 15:44:40 -07:00 by tepichord · 1 comment

tepichord commented

2026-08-19 15:44:40 -07:00

Owner

Architecture.md document missing topological information detailing the planned elements of the network
add a mermaid diagram showcasing the expected network topology of the cluster
add table showing ip’s/ports of applications on the kubernetes cluster, and which ones are accessible where

- Architecture.md document missing topological information detailing the planned elements of the network - add a mermaid diagram showcasing the expected network topology of the cluster - add table showing ip’s/ports of applications on the kubernetes cluster, and which ones are accessible where

tepichord added the

labels

2026-08-19 15:44:40 -07:00

tepichord added this to the MVP project

2026-08-19 15:44:40 -07:00

tepichord commented

2026-08-19 15:56:01 -07:00

Author

Owner

Naina:

Overview

The ARCHITECTURE.md file covers worker sizing, pod scaling, and pod topology but has no network topology section. This plan adds a Mermaid diagram showing the full cluster network (physical hosts, VMs, NAT bridge, Tailscale overlay) and an IP/port table documenting every application's address, port, and accessibility scope.

Technical Approach

Add new section header ## 7. Network Topology after the existing ## 6. Supporting Infrastructure section.
Insert a flowchart TD Mermaid diagram using nested subgraph blocks for boundaries.

flowchart TD
    Internet(["Internet"])
    TS["Tailscale<br>*.faun-snapper.ts.net"]

    subgraph naina["naina — 24 GB, 8 CPU (arm64)"]
        CP["Control Plane VM<br>2 GB, 2 vCPU<br>10.5.0.2"]
        subgraph wl["worker-large — 20 GB, 6 vCPU"]
            K8s["Kubernetes API<br>:6443"]
            VaultSvc["Vault + nginx<br>:8200 / :8443"]
            WP["Woodpecker CI<br>(planned)"]
            RMQ["RabbitMQ<br>:5672 / :15672"]
            Orch["evolved-npcs orchestrator"]
        end
    end

    subgraph ida["ida — 8 GB, 8 CPU (arm64)"]
        subgraph ws["worker-sim — 7 GB, 8 vCPU"]
            Sim["Simulation Pods<br>(KEDA-scaled)"]
        end
    end

    subgraph nat["NAT Bridge — cp-bridge<br>IPv4: 10.5.0.0/24<br>IPv6: 2001:db8:b84b:5::/64"]
        CP
        wl
        ws
    end

    Internet -->|"Tailscale"| TS
    TS -->|"HTTPS"| K8s
    TS -->|"HTTPS"| VaultSvc
    K8s -->|"k8s API"| Orch
    Orch -->|"AMQP"| RMQ
    RMQ -->|"AMQP"| Sim

Insert a Markdown table below the diagram with columns: Service, Type, Port(s), Protocol, Accessibility, Status.

| Service | Type | Port(s) | Protocol | Accessibility | Status |
|---------|------|---------|----------|---------------|--------|
| Talos API | External | 50000 | TCP | host-only (naina) | deployed |
| Kubernetes API | NodePort | 6443 | TCP | tailscale | deployed |
| Vault | NodePort | 8200 | TCP | tailscale | deployed |
| nginx (HTTPS) | NodePort | 8443 | TCP | tailscale | deployed |
| nginx (HTTP redirect) | NodePort | 8080 | TCP | tailscale | deployed |
| Woodpecker UI | ClusterIP | 8000 | TCP | tailscale (via ingress) | planned |
| RabbitMQ AMQP | ClusterIP | 5672 | TCP | cluster-only | planned |
| RabbitMQ Mgmt | ClusterIP | 15672 | TCP | cluster-only (KEDA) | planned |
| Simulation Pods | ClusterIP | — | TCP | cluster-only | planned |

NodePort values for Vault (32706, 30266, 32536) are from hc-vault/example.yaml and may be auto-assigned. The table will note this with a footnote.

Add a brief prose paragraph (2 sentences max) above the diagram explaining dual-stack NAT and Tailscale TLS termination.
Add a footnote below the table clarifying NodePort auto-assignment and that planned services are target-architecture items.

Implementation Details

File to modify: ARCHITECTURE.md

Insert new ## 7. Network Topology section after section 6
Contains: Mermaid diagram, IP/port table, brief prose intro, footnotes

Source files referenced (read-only):

control-plane/main.tf — network name control-plane-net, bridge cp-bridge
control-plane/control-plane-net.xsl — dual-stack ranges: 10.5.0.0/24, 2001:db8:b84b:5::/64
hc-vault/example.yaml — NodePort values for Vault (32706, 30266, 32536)
worker/vm-setup/create-worker-vm.sh — QEMU user-mode networking, MAC generation

Dependencies: None (documentation-only change).

Constraints:

Must use flowchart TD (not graph TD) — modern Mermaid keyword, supports subgraph features
Dual-stack IPs shown in node labels with   separator
All images must be arm64-compatible (existing constraint from AGENTS.md)

Out-of-scope notes:

No changes to Terraform, patches, or any source files
Exact IP assignments for worker VMs are DHCP-assigned; diagram shows expected ranges, not fixed IPs
architecture-beta Mermaid type is still beta — using flowchart TD + subgraphs instead

Acceptance Criteria

ARCHITECTURE.md contains a ## 7. Network Topology section with a Mermaid flowchart TD diagram
Diagram shows physical hosts (naina, ida), VMs (control-plane, worker-large, worker-sim), NAT bridge (dual-stack), and Tailscale overlay
IP/port table lists all currently deployed and planned services with port, protocol, and accessibility scope
Table distinguishes deployed vs. planned services via a Status column
New content follows existing ARCHITECTURE.md style (code blocks, Mermaid fenced blocks, Markdown tables)

Testing Plan

Render test: Open the updated ARCHITECTURE.md in a Mermaid-capable viewer (GitHub, VS Code with Mermaid extension) and verify the diagram renders without syntax errors
Completeness check: Verify every service listed in the table corresponds to a node or subgraph in the diagram
Lint: Run existing yamllint and Markdown linting checks against the file to ensure no formatting regressions

ARCHITECTURE.md — primary file being modified
PLAN.md — project roadmap (Phase 4 worker nodes)

Naina: #### Overview The `ARCHITECTURE.md` file covers worker sizing, pod scaling, and pod topology but has no network topology section. This plan adds a Mermaid diagram showing the full cluster network (physical hosts, VMs, NAT bridge, Tailscale overlay) and an IP/port table documenting every application's address, port, and accessibility scope. #### Technical Approach 1. **Add new section header `## 7. Network Topology` after the existing `## 6. Supporting Infrastructure` section.** 2. **Insert a `flowchart TD` Mermaid diagram using nested `subgraph` blocks for boundaries.** ```mermaid flowchart TD Internet(["Internet"]) TS["Tailscale *.faun-snapper.ts.net"] subgraph naina["naina — 24 GB, 8 CPU (arm64)"] CP["Control Plane VM 2 GB, 2 vCPU 10.5.0.2"] subgraph wl["worker-large — 20 GB, 6 vCPU"] K8s["Kubernetes API :6443"] VaultSvc["Vault + nginx :8200 / :8443"] WP["Woodpecker CI (planned)"] RMQ["RabbitMQ :5672 / :15672"] Orch["evolved-npcs orchestrator"] end end subgraph ida["ida — 8 GB, 8 CPU (arm64)"] subgraph ws["worker-sim — 7 GB, 8 vCPU"] Sim["Simulation Pods (KEDA-scaled)"] end end subgraph nat["NAT Bridge — cp-bridge IPv4: 10.5.0.0/24 IPv6: 2001:db8:b84b:5::/64"] CP wl ws end Internet -->|"Tailscale"| TS TS -->|"HTTPS"| K8s TS -->|"HTTPS"| VaultSvc K8s -->|"k8s API"| Orch Orch -->|"AMQP"| RMQ RMQ -->|"AMQP"| Sim ``` 3. **Insert a Markdown table below the diagram with columns: Service, Type, Port(s), Protocol, Accessibility, Status.** ```markdown | Service | Type | Port(s) | Protocol | Accessibility | Status | |---------|------|---------|----------|---------------|--------| | Talos API | External | 50000 | TCP | host-only (naina) | deployed | | Kubernetes API | NodePort | 6443 | TCP | tailscale | deployed | | Vault | NodePort | 8200 | TCP | tailscale | deployed | | nginx (HTTPS) | NodePort | 8443 | TCP | tailscale | deployed | | nginx (HTTP redirect) | NodePort | 8080 | TCP | tailscale | deployed | | Woodpecker UI | ClusterIP | 8000 | TCP | tailscale (via ingress) | planned | | RabbitMQ AMQP | ClusterIP | 5672 | TCP | cluster-only | planned | | RabbitMQ Mgmt | ClusterIP | 15672 | TCP | cluster-only (KEDA) | planned | | Simulation Pods | ClusterIP | — | TCP | cluster-only | planned | ``` > NodePort values for Vault (32706, 30266, 32536) are from `hc-vault/example.yaml` and may be auto-assigned. The table will note this with a footnote. 4. **Add a brief prose paragraph (2 sentences max) above the diagram explaining dual-stack NAT and Tailscale TLS termination.** 5. **Add a footnote below the table clarifying NodePort auto-assignment and that planned services are target-architecture items.** #### Implementation Details **File to modify:** `ARCHITECTURE.md` - Insert new `## 7. Network Topology` section after section 6 - Contains: Mermaid diagram, IP/port table, brief prose intro, footnotes **Source files referenced (read-only):** - `control-plane/main.tf` — network name `control-plane-net`, bridge `cp-bridge` - `control-plane/control-plane-net.xsl` — dual-stack ranges: `10.5.0.0/24`, `2001:db8:b84b:5::/64` - `hc-vault/example.yaml` — NodePort values for Vault (32706, 30266, 32536) - `worker/vm-setup/create-worker-vm.sh` — QEMU user-mode networking, MAC generation **Dependencies:** None (documentation-only change). **Constraints:** - Must use `flowchart TD` (not `graph TD`) — modern Mermaid keyword, supports subgraph features - Dual-stack IPs shown in node labels with ` ` separator - All images must be arm64-compatible (existing constraint from `AGENTS.md`) **Out-of-scope notes:** - No changes to Terraform, patches, or any source files - Exact IP assignments for worker VMs are DHCP-assigned; diagram shows expected ranges, not fixed IPs - `architecture-beta` Mermaid type is still beta — using `flowchart TD` + subgraphs instead #### Acceptance Criteria - [ ] `ARCHITECTURE.md` contains a `## 7. Network Topology` section with a Mermaid `flowchart TD` diagram - [ ] Diagram shows physical hosts (naina, ida), VMs (control-plane, worker-large, worker-sim), NAT bridge (dual-stack), and Tailscale overlay - [ ] IP/port table lists all currently deployed and planned services with port, protocol, and accessibility scope - [ ] Table distinguishes deployed vs. planned services via a Status column - [ ] New content follows existing ARCHITECTURE.md style (code blocks, Mermaid fenced blocks, Markdown tables) #### Testing Plan 1. **Render test:** Open the updated `ARCHITECTURE.md` in a Mermaid-capable viewer (GitHub, VS Code with Mermaid extension) and verify the diagram renders without syntax errors 2. **Completeness check:** Verify every service listed in the table corresponds to a node or subgraph in the diagram 3. **Lint:** Run existing `yamllint` and Markdown linting checks against the file to ensure no formatting regressions #### Related Issues/PRs - [ARCHITECTURE.md](https://git.gloom.garden/tepichord/milner/src/branch/main/ARCHITECTURE.md) — primary file being modified - [PLAN.md](https://git.gloom.garden/tepichord/milner/src/branch/main/PLAN.md) — project roadmap (Phase 4 worker nodes)

tepichord added

and removed

labels

2026-08-19 15:56:18 -07:00

tepichord referenced this issue from a commit

2026-08-19 19:05:21 -07:00

docs(architecture): add network topology section with Mermaid diagram and IP/port table

tepichord referenced this issue from a pull request that will close it,