Architecture Overview

System Design

The HomeLab infrastructure is built on a Kubernetes-first approach, utilizing K3s for lightweight container orchestration with enterprise-grade capabilities.

Design Principles

1. GitOps-Driven: All configurations stored in Git, deployed via ArgoCD
2. Zero-Trust Networking: External access through Cloudflare Tunnel only
3. High Availability: Multi-replica deployments where applicable
4. Observability: Full metrics, logging, and tracing stack
5. Immutable Infrastructure: Container-based deployments

High-Level Architecture

graph LR
    subgraph External
        Users[Users]
        CF[Cloudflare]
    end

    subgraph HomeLab Network
        subgraph K3s Cluster
            ArgoCD[ArgoCD]
            Apps[Applications]
            Mon[Monitoring]
            DB[Databases]
        end

        PF[pfSense]
        Proxmox[Proxmox VE]
    end

    subgraph Cloud
        GitHub[GitHub]
        DockerHub[Docker Hub]
    end

    Users --> CF
    CF -->|Tunnel| Apps
    GitHub -->|GitOps| ArgoCD
    ArgoCD --> Apps
    DockerHub --> Apps
    PF --> K3s Cluster

Component Layers

Layer 1: Infrastructure

• Hypervisor: Proxmox VE for VM management
• Firewall: pfSense for network security
• DNS: Local DNS resolution

Layer 2: Platform

• Container Runtime: containerd
• Orchestration: K3s v1.34.3
• Storage: Longhorn distributed block storage
• Networking: Flannel CNI

Layer 3: Services

• GitOps: ArgoCD for continuous deployment
• Ingress: Cloudflare Tunnel (cloudflared)
• Certificates: Managed by Cloudflare

Layer 4: Applications

• Monitoring: Prometheus, Grafana, Alertmanager
• Logging: Elasticsearch, Kibana, Elastic Agent
• Custom Apps: Hub Web/API, Parquet API
• Data Processing: StreamSets

Namespace Organization

Namespace	Purpose
argocd	GitOps deployment controller
cloudflared	Tunnel to Cloudflare
monitoring	Prometheus, Grafana stack
databases	InfluxDB, MongoDB, MySQL
hub	Hub Web and API applications
parquet-api	Parquet file service
streamsets	Data pipeline processing
longhorn-system	Distributed storage

Data Flow

sequenceDiagram
    participant User
    participant Cloudflare
    participant Tunnel
    participant Service
    participant Database

    User->>Cloudflare: HTTPS Request
    Cloudflare->>Tunnel: Forward via tunnel
    Tunnel->>Service: Route to K8s service
    Service->>Database: Query data
    Database-->>Service: Return results
    Service-->>Tunnel: Response
    Tunnel-->>Cloudflare: Return
    Cloudflare-->>User: HTTPS Response

Security Boundaries

1. Internet → Cloudflare: DDoS protection, WAF
2. Cloudflare → Tunnel: Encrypted tunnel, no inbound ports
3. Tunnel → Services: Internal cluster networking
4. Services → Databases: Namespace isolation, network policies