385 lines
22 KiB
Markdown
385 lines
22 KiB
Markdown
# Network Architecture Diagram
|
|
|
|
## 🌐 Infrastructure Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ Home/Lab Network │
|
|
│ 192.168.1.0/24 │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌──────────────────────────┐ ┌──────────────────────────┐
|
|
│ Orange Pi (Gitea) │ │ K3s Cluster (RPi) │
|
|
│ 192.168.1.208 │ │ Master: 192.168.1.X │
|
|
│ │ │ Workers: 192.168.1.Y/Z │
|
|
│ ┌────────────────────┐ │ │ │
|
|
│ │ Gitea Server │ │ │ ┌────────────────────┐ │
|
|
│ │ :3000 (HTTP) │ │ │ │ K3s API Server │ │
|
|
│ │ │ │ │ │ :6443 (HTTPS) │ │
|
|
│ └────────────────────┘ │ │ └────────────────────┘ │
|
|
│ │ │ │
|
|
│ ┌────────────────────┐ │ │ ┌────────────────────┐ │
|
|
│ │ Container Reg. │ │ │ │ socktop-webterm │ │
|
|
│ │ :3002 (HTTP) │◄─┼──────┼──┤ Deployment │ │
|
|
│ └────────────────────┘ │ │ │ • 3 replicas │ │
|
|
│ ▲ │ │ │ • Port 8082 │ │
|
|
│ │ │ │ └────────────────────┘ │
|
|
│ ┌────────┴───────────┐ │ │ │
|
|
│ │ Actions Runner │ │ │ ┌────────────────────┐ │
|
|
│ │ (act_runner) │──┼──────┼─►│ Ingress │ │
|
|
│ │ │ │ │ │ webterm.example │ │
|
|
│ │ • Docker builder │ │ │ └────────────────────┘ │
|
|
│ │ • kubectl client │ │ │ │
|
|
│ └────────────────────┘ │ └──────────────────────────┘
|
|
│ │
|
|
└──────────────────────────┘
|
|
│
|
|
│ (Optional)
|
|
▼
|
|
┌──────────────────────────┐
|
|
│ Rancher (Management) │
|
|
│ 192.168.1.X:8443 │
|
|
│ │
|
|
│ • Visual K8s mgmt │
|
|
│ • Monitoring │
|
|
│ • YAML editor │
|
|
└──────────────────────────┘
|
|
```
|
|
|
|
## 🔄 CI/CD Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ DEVELOPER WORKFLOW │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
|
|
[Developer Workstation]
|
|
│
|
|
│ 1. Update Cargo.toml version
|
|
│ 2. git commit -m "Bump version"
|
|
│ 3. git push origin main
|
|
▼
|
|
┌───────────────────┐
|
|
│ Gitea Server │
|
|
│ 192.168.1.208 │
|
|
└────────┬──────────┘
|
|
│
|
|
│ 4. Webhook triggers Action
|
|
▼
|
|
┌───────────────────────────────────────────┐
|
|
│ Gitea Actions Runner (Orange Pi) │
|
|
│ │
|
|
│ ╔═══════════════════════════════════╗ │
|
|
│ ║ JOB 1: BUILD & PUSH ║ │
|
|
│ ╚═══════════════════════════════════╝ │
|
|
│ │
|
|
│ 5. Clone repository │
|
|
│ 6. Extract version from Cargo.toml │
|
|
│ 7. docker buildx build --platform arm64 │
|
|
│ ▼ │
|
|
│ 8. Push to registry ─────────────────┐ │
|
|
│ 192.168.1.208:3002/ │ │
|
|
│ jason/socktop-webterm:0.2.2 │ │
|
|
│ │ │
|
|
│ ╔═══════════════════════════════════╗│ │
|
|
│ ║ JOB 2: DEPLOY ║│ │
|
|
│ ╚═══════════════════════════════════╝│ │
|
|
│ │ │
|
|
│ 9. kubectl --kubeconfig=(secret) │ │
|
|
│ 10. kubectl set image deployment/... │ │
|
|
│ socktop-webterm:0.2.2 │ │
|
|
│ │ │
|
|
└───────────────┬───────────────────────┘ │
|
|
│ │
|
|
│ 11. kubectl talks to k3s │
|
|
▼ │
|
|
┌─────────────────────────────────────┐ │
|
|
│ K3s Cluster │ │
|
|
│ │ │
|
|
│ 12. Pull new image ◄───────────────┘ │
|
|
│ from registry │
|
|
│ │
|
|
│ 13. Rolling update: │
|
|
│ Pod 1: old → new ✓ │
|
|
│ Pod 2: old → new ✓ │
|
|
│ Pod 3: old → new ✓ │
|
|
│ │
|
|
│ 14. Deployment complete! │
|
|
│ All pods running new version │
|
|
└───────────────────────────────────────────┘
|
|
```
|
|
|
|
## 🔐 Authentication Flow
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ SECURITY & AUTHENTICATION │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
|
|
╔══════════════════════════════════════════════════════════════╗
|
|
║ 1. CONTAINER REGISTRY ACCESS ║
|
|
╚══════════════════════════════════════════════════════════════╝
|
|
|
|
Actions Runner
|
|
│
|
|
│ docker login 192.168.1.208:3002
|
|
│ Username: $REGISTRY_USERNAME (secret)
|
|
│ Password: $REGISTRY_PASSWORD (secret/token)
|
|
▼
|
|
Container Registry
|
|
│
|
|
│ Token validated
|
|
▼
|
|
✓ Authenticated - can push images
|
|
|
|
|
|
╔══════════════════════════════════════════════════════════════╗
|
|
║ 2. KUBERNETES CLUSTER ACCESS ║
|
|
╚══════════════════════════════════════════════════════════════╝
|
|
|
|
Actions Runner
|
|
│
|
|
│ kubectl --kubeconfig=$KUBECONFIG (secret)
|
|
│ Contains: Service Account Token
|
|
▼
|
|
K3s API Server (:6443)
|
|
│
|
|
│ Validates token
|
|
│ Checks RBAC permissions
|
|
▼
|
|
ServiceAccount: gitea-deployer
|
|
│
|
|
│ Bound to Role: gitea-deployer-role
|
|
│ Permissions:
|
|
│ - get/list/watch/update/patch deployments
|
|
│ - get/list/watch pods
|
|
│ - get/list/watch replicasets
|
|
▼
|
|
✓ Authorized - can update deployment
|
|
|
|
|
|
╔══════════════════════════════════════════════════════════════╗
|
|
║ 3. IMAGE PULL ACCESS (K3s → Registry) ║
|
|
╚══════════════════════════════════════════════════════════════╝
|
|
|
|
K3s Node
|
|
│
|
|
│ imagePullPolicy: Always
|
|
│ image: 192.168.1.208:3002/jason/socktop-webterm:0.2.2
|
|
▼
|
|
Container Registry
|
|
│
|
|
│ Public or registry secret configured
|
|
▼
|
|
✓ Image pulled successfully
|
|
```
|
|
|
|
## 📊 Network Ports & Services
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ PORT MAPPING │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
|
|
ORANGE PI (192.168.1.208)
|
|
├─ :3000 → Gitea Web UI (HTTP/HTTPS)
|
|
├─ :3002 → Gitea Container Registry (HTTP)
|
|
└─ :22 → SSH/Git access
|
|
|
|
K3S MASTER NODE
|
|
├─ :6443 → Kubernetes API Server (HTTPS)
|
|
├─ :8080 → K3s metrics (optional)
|
|
└─ :10250 → Kubelet API
|
|
|
|
K3S WORKER NODES
|
|
├─ :10250 → Kubelet API
|
|
└─ :30000+ → NodePort services (if used)
|
|
|
|
SOCKTOP-WEBTERM PODS
|
|
├─ :8082 → HTTP server (web terminal)
|
|
└─ :3001 → Socktop agent
|
|
|
|
RANCHER (if installed)
|
|
└─ :8443 → Rancher UI (HTTPS)
|
|
|
|
INGRESS (External Access)
|
|
└─ :80/:443 → Routes to webterm service
|
|
```
|
|
|
|
## 🔧 Required Network Access
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ NETWORK CONNECTIVITY MATRIX │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
|
|
FROM: Developer Workstation
|
|
TO: Gitea (192.168.1.208:3000) [✓] HTTPS/Git Push
|
|
TO: Rancher [✓] HTTPS (optional)
|
|
TO: K3s cluster [✓] kubectl (optional)
|
|
|
|
FROM: Actions Runner (on Orange Pi)
|
|
TO: Gitea Server (localhost) [✓] HTTP API
|
|
TO: Container Registry (localhost) [✓] HTTP (Docker API)
|
|
TO: K3s API (192.168.1.X:6443) [✓] HTTPS (kubectl)
|
|
TO: Internet [✓] Download dependencies
|
|
|
|
FROM: K3s Cluster
|
|
TO: Container Registry (192.168.1.208:3002) [✓] HTTP (image pull)
|
|
TO: Internet [✓] External services (opt)
|
|
|
|
FROM: End Users
|
|
TO: Ingress/NodePort [✓] HTTP/HTTPS (webterm)
|
|
```
|
|
|
|
## 🎯 Component Responsibilities
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ COMPONENT ROLES │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
|
|
╔════════════════════════════════════════════════════════════════╗
|
|
║ GITEA SERVER (Orange Pi) ║
|
|
╠════════════════════════════════════════════════════════════════╣
|
|
║ • Git repository hosting ║
|
|
║ • Actions workflow execution coordinator ║
|
|
║ • Container registry ║
|
|
║ • Secret storage ║
|
|
║ • Webhook management ║
|
|
╚════════════════════════════════════════════════════════════════╝
|
|
|
|
╔════════════════════════════════════════════════════════════════╗
|
|
║ ACTIONS RUNNER (Orange Pi) ║
|
|
╠════════════════════════════════════════════════════════════════╣
|
|
║ • Execute workflow jobs ║
|
|
║ • Build Docker images (arm64) ║
|
|
║ • Push images to registry ║
|
|
║ • Run kubectl commands ║
|
|
║ • Report status back to Gitea ║
|
|
╚════════════════════════════════════════════════════════════════╝
|
|
|
|
╔════════════════════════════════════════════════════════════════╗
|
|
║ K3S CLUSTER (Raspberry Pi nodes) ║
|
|
╠════════════════════════════════════════════════════════════════╣
|
|
║ • Container orchestration ║
|
|
║ • Service discovery & load balancing ║
|
|
║ • Rolling deployments ║
|
|
║ • Health monitoring ║
|
|
║ • Persistent storage (if needed) ║
|
|
╚════════════════════════════════════════════════════════════════╝
|
|
|
|
╔════════════════════════════════════════════════════════════════╗
|
|
║ RANCHER (Optional - separate or on cluster) ║
|
|
╠════════════════════════════════════════════════════════════════╣
|
|
║ • Visual cluster management ║
|
|
║ • YAML editor for resources ║
|
|
║ • Monitoring dashboards ║
|
|
║ • User-friendly kubectl alternative ║
|
|
╚════════════════════════════════════════════════════════════════╝
|
|
```
|
|
|
|
## 🔄 Data Flow
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ BUILD PIPELINE │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
|
|
SOURCE CODE ARTIFACTS RUNTIME
|
|
────────────
|
|
Cargo.toml ─┐ Docker Image ─┐ Running Pods
|
|
src/**/*.rs ├─build──► :0.2.2 ├─pull──► [webterm]
|
|
templates/** │ + :latest │ [webterm]
|
|
static/** │ │ │ [webterm]
|
|
Dockerfile ─┘ │ │
|
|
▼ │
|
|
Container Registry │
|
|
192.168.1.208:3002 │
|
|
/jason/socktop-webterm │
|
|
│
|
|
Cargo.toml │
|
|
version ─────────extract────────────────────┘
|
|
(by workflow)
|
|
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ DEPLOYMENT PIPELINE │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
|
|
WORKFLOW K8S API CLUSTER STATE
|
|
────────
|
|
kubectl set K3s API Server Deployment
|
|
image ───► validates ────► • spec.image updated
|
|
│ RBAC • triggers rollout
|
|
│
|
|
▼ ▼
|
|
Authentication ReplicaSet
|
|
• Service Account • New RS created
|
|
• Token • Old RS scaled down
|
|
• RBAC check
|
|
▼
|
|
Pods
|
|
• New pods: 0→1→2→3
|
|
• Old pods: 3→2→1→0
|
|
• Zero downtime
|
|
```
|
|
|
|
## 🔍 Monitoring Points
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ WHERE TO LOOK │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
|
|
📊 BUILD STATUS
|
|
├─ Gitea → Repository → Actions tab
|
|
├─ Runner logs: journalctl -u act_runner -f
|
|
└─ Docker build output in workflow logs
|
|
|
|
📊 DEPLOYMENT STATUS
|
|
├─ kubectl get deployment socktop-webterm -n default
|
|
├─ kubectl rollout status deployment/socktop-webterm
|
|
├─ kubectl get pods -l app=socktop-webterm
|
|
└─ Rancher → Deployments → socktop-webterm
|
|
|
|
📊 APPLICATION HEALTH
|
|
├─ kubectl logs -l app=socktop-webterm --tail=100 -f
|
|
├─ HTTP health check: curl http://pod-ip:8082/
|
|
├─ Ingress: https://webterm.yourdomain.com
|
|
└─ Rancher → Workloads → Pod logs
|
|
|
|
📊 REGISTRY
|
|
├─ Gitea → Repository → Packages
|
|
├─ docker images | grep socktop-webterm
|
|
└─ curl http://192.168.1.208:3002/v2/jason/socktop-webterm/tags/list
|
|
```
|
|
|
|
## 💾 Persistent Data
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ DATA PERSISTENCE │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
|
|
GITEA (Orange Pi)
|
|
/var/lib/gitea/
|
|
├─ data/ → Git repositories
|
|
├─ data/packages/ → Container images
|
|
└─ data/actions_logs/ → Workflow logs
|
|
|
|
K3S CLUSTER
|
|
/var/lib/rancher/k3s/
|
|
├─ server/manifests/ → Auto-deployed manifests
|
|
└─ agent/containerd/ → Container images cache
|
|
|
|
CONFIGMAPS & SECRETS
|
|
├─ socktop-webterm-config → Application config
|
|
└─ socktop-webterm-certs → TLS certificates
|
|
|
|
VOLUMES (if used)
|
|
└─ PersistentVolumeClaims → App data (not currently used)
|
|
```
|
|
|
|
---
|
|
|
|
**This diagram shows the complete network topology and data flow for your CI/CD pipeline.** |