82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
|
# 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](https://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
|
||
|
|
```bash
|
||
|
|
# 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:
|
||
|
|
```markdown
|
||
|
|
```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
|