Keybard-Vagabond-Demo/diagrams/README.md

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

1. Go to mermaid.live
2. Copy the contents of the .mmd file
3. 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