add source code and readme
This commit is contained in:
81
diagrams/README.md
Normal file
81
diagrams/README.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# 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
|
||||
163
diagrams/network-architecture.mmd
Normal file
163
diagrams/network-architecture.mmd
Normal file
@@ -0,0 +1,163 @@
|
||||
graph TB
|
||||
%% External Users and Services
|
||||
subgraph "Internet"
|
||||
User[👤 Users]
|
||||
Dev[👨💻 Developers with Tailscale]
|
||||
end
|
||||
|
||||
%% Cloudflare Infrastructure
|
||||
subgraph "Cloudflare Infrastructure"
|
||||
subgraph "Cloudflare Edge"
|
||||
CDN[🌐 Cloudflare CDN<br/>Global Edge Network]
|
||||
ZT[🔒 Zero Trust Tunnels<br/>Secure Gateway]
|
||||
end
|
||||
|
||||
subgraph "CDN Endpoints"
|
||||
CDN_PX[📸 pm.keyboardvagabond.com<br/>Pixelfed CDN]
|
||||
CDN_PF[📋 pfm.keyboardvagabond.com<br/>PieFed CDN]
|
||||
CDN_M[🐦 mm.keyboardvagabond.com<br/>Mastodon CDN]
|
||||
end
|
||||
|
||||
subgraph "Zero Trust Domains"
|
||||
ZT_AUTH[🔐 auth.keyboardvagabond.com<br/>Authentik SSO]
|
||||
ZT_REG[📦 <YOUR_REGISTRY_URL><br/>Harbor Registry]
|
||||
ZT_OBS[📊 obs.keyboardvagabond.com<br/>OpenObserve]
|
||||
ZT_MAST[🐦 mastodon.keyboardvagabond.com<br/>Mastodon Web]
|
||||
ZT_STREAM[📡 streamingmastodon.keyboardvagabond.com<br/>Mastodon Streaming]
|
||||
ZT_PX[📸 pixelfed.keyboardvagabond.com<br/>Pixelfed]
|
||||
ZT_PF[📋 piefed.keyboardvagabond.com<br/>PieFed]
|
||||
ZT_PIC[🖼️ picsur.keyboardvagabond.com<br/>Picsur]
|
||||
end
|
||||
end
|
||||
|
||||
%% Tailscale Infrastructure
|
||||
subgraph "Tailscale Network (100.64.0.0/10)"
|
||||
TS_CONTROL[🎛️ Tailscale Control Plane<br/>tailscale.com]
|
||||
TS_CLIENT[💻 Client IP: <TAILSCALE_CLIENT_IP><br/>kubectl context]
|
||||
end
|
||||
|
||||
%% Backblaze B2 Storage
|
||||
subgraph "Backblaze B2 Storage"
|
||||
B2_PX[📦 pixelfed-bucket]
|
||||
B2_PF[📦 piefed-bucket]
|
||||
B2_M[📦 mastodon-bucket]
|
||||
B2_BACKUP[💾 Longhorn Backups]
|
||||
end
|
||||
|
||||
%% NetCup Cloud Infrastructure
|
||||
subgraph "NetCup Cloud - VLAN 1004963 (10.132.0.0/24)"
|
||||
subgraph "Node n1 (<NODE_1_EXTERNAL_IP>)"
|
||||
subgraph "Control Plane + Worker"
|
||||
API[🎯 Kubernetes API<br/>:6443]
|
||||
TALOS1[⚙️ Talos API<br/>:50000/50001]
|
||||
|
||||
subgraph "Infrastructure Pods"
|
||||
NGINX[🌐 NGINX Ingress<br/>hostNetwork mode]
|
||||
CILIUM1[🛡️ Cilium CNI<br/>Host Firewall]
|
||||
LONGHORN1[💽 Longhorn Storage]
|
||||
CLOUDFLARED[☁️ Cloudflared<br/>Zero Trust Client]
|
||||
TS_ROUTER[🔗 Tailscale Subnet Router<br/>keyboardvagabond-cluster]
|
||||
end
|
||||
|
||||
subgraph "Application Pods"
|
||||
POSTGRES[🗄️ PostgreSQL Cluster<br/>CloudNativePG]
|
||||
REDIS[📋 Redis]
|
||||
HARBOR[📦 Harbor Registry]
|
||||
OPENOBS[📊 OpenObserve]
|
||||
AUTHENTIK[🔐 Authentik SSO]
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
subgraph "Node n2 (<NODE_2_EXTERNAL_IP>)"
|
||||
subgraph "Worker Node"
|
||||
TALOS2[⚙️ Talos API<br/>:50000/50001]
|
||||
|
||||
subgraph "Infrastructure Pods n2"
|
||||
CILIUM2[🛡️ Cilium CNI<br/>Host Firewall]
|
||||
LONGHORN2[💽 Longhorn Storage<br/>2-replica]
|
||||
end
|
||||
|
||||
subgraph "Application Pods n2"
|
||||
MASTODON[🐦 Mastodon]
|
||||
PIXELFED[📸 Pixelfed]
|
||||
PIEFED[📋 PieFed]
|
||||
PICSUR[🖼️ Picsur]
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
%% Connections - External User Access
|
||||
User --> CDN
|
||||
User --> ZT
|
||||
|
||||
%% CDN to Storage
|
||||
CDN_PX --> B2_PX
|
||||
CDN_PF --> B2_PF
|
||||
CDN_M --> B2_M
|
||||
|
||||
%% Zero Trust Tunnels (Secure)
|
||||
ZT_AUTH -.->|"🔒 Secure Tunnel"| AUTHENTIK
|
||||
ZT_REG -.->|"🔒 Secure Tunnel"| HARBOR
|
||||
ZT_OBS -.->|"🔒 Secure Tunnel"| OPENOBS
|
||||
ZT_MAST -.->|"🔒 Secure Tunnel"| MASTODON
|
||||
ZT_STREAM -.->|"🔒 Secure Tunnel"| MASTODON
|
||||
ZT_PX -.->|"🔒 Secure Tunnel"| PIXELFED
|
||||
ZT_PF -.->|"🔒 Secure Tunnel"| PIEFED
|
||||
ZT_PIC -.->|"🔒 Secure Tunnel"| PICSUR
|
||||
|
||||
%% Tailscale Connections
|
||||
Dev --> TS_CONTROL
|
||||
TS_CLIENT --> TS_CONTROL
|
||||
TS_CONTROL -.->|"🔗 Mesh VPN"| TS_ROUTER
|
||||
|
||||
%% Tailscale Administrative Access
|
||||
TS_CLIENT -.->|"🔗 kubectl via <NODE_1_IP>:6443"| API
|
||||
TS_CLIENT -.->|"🔗 talosctl"| TALOS1
|
||||
TS_CLIENT -.->|"🔗 talosctl"| TALOS2
|
||||
|
||||
%% Internal Cluster Networking
|
||||
NGINX --> MASTODON
|
||||
NGINX --> PIXELFED
|
||||
NGINX --> PIEFED
|
||||
NGINX --> PICSUR
|
||||
NGINX --> HARBOR
|
||||
NGINX --> OPENOBS
|
||||
NGINX --> AUTHENTIK
|
||||
|
||||
%% Database Connections
|
||||
MASTODON --> POSTGRES
|
||||
PIXELFED --> POSTGRES
|
||||
PIEFED --> POSTGRES
|
||||
PICSUR --> POSTGRES
|
||||
AUTHENTIK --> POSTGRES
|
||||
PIEFED --> REDIS
|
||||
|
||||
%% Storage Connections
|
||||
MASTODON --> B2_M
|
||||
PIXELFED --> B2_PX
|
||||
PIEFED --> B2_PF
|
||||
LONGHORN1 --> B2_BACKUP
|
||||
LONGHORN2 --> B2_BACKUP
|
||||
|
||||
%% Cilium Host Firewall Rules
|
||||
CILIUM1 -.->|"🛡️ Firewall Rules"| API
|
||||
CILIUM1 -.->|"🛡️ Firewall Rules"| TALOS1
|
||||
CILIUM2 -.->|"🛡️ Firewall Rules"| TALOS2
|
||||
|
||||
%% Network Labels
|
||||
classDef external fill:#e1f5fe
|
||||
classDef cloudflare fill:#ff9800,color:#fff
|
||||
classDef tailscale fill:#4caf50,color:#fff
|
||||
classDef secure fill:#f44336,color:#fff
|
||||
classDef storage fill:#9c27b0,color:#fff
|
||||
classDef node fill:#2196f3,color:#fff
|
||||
classDef blocked fill:#757575,color:#fff,stroke-dasharray: 5 5
|
||||
|
||||
class User,Dev external
|
||||
class CDN,ZT,CDN_PX,CDN_PF,CDN_M,ZT_AUTH,ZT_REG,ZT_OBS,ZT_MAST,ZT_STREAM,ZT_PX,ZT_PF,ZT_PIC cloudflare
|
||||
class TS_CONTROL,TS_CLIENT,TS_ROUTER tailscale
|
||||
class CILIUM1,CILIUM2,API,TALOS1,TALOS2 secure
|
||||
class B2_PX,B2_PF,B2_M,B2_BACKUP,LONGHORN1,LONGHORN2 storage
|
||||
class NGINX,POSTGRES,REDIS,MASTODON,PIXELFED,PIEFED,PICSUR,HARBOR,OPENOBS,AUTHENTIK,CLOUDFLARED node
|
||||
Reference in New Issue
Block a user