Keyboard Vagabond Network Diagrams

This directory contains network architecture diagrams for the Keyboard Vagabond Kubernetes cluster.

Files

`network-architecture.mmd`

Mermaid diagram showing the complete network architecture including:

Cloudflare Zero Trust tunnels and CDN infrastructure
Tailscale mesh VPN for administrative access
NetCup Cloud VLAN setup with node topology
Backblaze B2 storage integration
Application and infrastructure pod distribution

How to View/Edit Mermaid Diagrams

Option 1: GitHub (Automatic Rendering)

GitHub automatically renders .mmd files in the web interface
Simply view the file on GitHub to see the rendered diagram

Option 2: Mermaid Live Editor

Go to mermaid.live
Copy the contents of the .mmd file
Paste into the editor to view/edit

Option 3: VS Code Extensions

Install one of these VS Code extensions:

Mermaid Markdown Syntax Highlighting by bpruitt-goddard
Mermaid Preview by vstirbu
Markdown Preview Mermaid Support by bierner

Option 4: Local Mermaid CLI

# Install Mermaid CLI
npm install -g @mermaid-js/mermaid-cli

# Generate PNG/SVG from diagram
mmdc -i network-architecture.mmd -o network-architecture.png
mmdc -i network-architecture.mmd -o network-architecture.svg

Option 5: Integration in Documentation

Add to Markdown files using:

```mermaid
graph TB
    // Paste diagram content here


## Architecture Overview

The current network architecture implements a **zero-trust security model** with:

### 🔒 Security Layers
1. **Cloudflare Zero Trust**: All public application access via secure tunnels
2. **Tailscale Mesh VPN**: Administrative access to Kubernetes/Talos APIs
3. **Cilium Host Firewall**: Node-level security with CGNAT-only access to APIs

### 🌐 Public Access Paths
- **Applications**: `https://*.keyboardvagabond.com` → Cloudflare Zero Trust → Internal services
- **CDN Assets**: `https://{pm,pfm,mm}.keyboardvagabond.com` → Cloudflare CDN → Backblaze B2

### 🔧 Administrative Access
- **kubectl**: Tailscale client (`<TAILSCALE_CLIENT_IP>`) → Tailscale mesh → Internal API (`<NODE_1_IP>:6443`)
- **talosctl**: Tailscale client → Tailscale mesh → Talos APIs on both nodes

### 🛡️ Security Achievements
- ✅ Zero external ports exposed directly to internet
- ✅ All administrative access via authenticated mesh VPN
- ✅ All public access via authenticated Zero Trust tunnels
- ✅ Host firewall blocking world access to critical APIs
- ✅ Dedicated CDN endpoints per application with $0 egress costs

## Maintenance

When architecture changes occur, update the diagram by:
1. Editing the `.mmd` file with new components/connections
2. Testing the rendering in Mermaid Live Editor
3. Updating this README if new concepts are introduced
4. Committing both the diagram and documentation updates