# 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.**