# osialek/homelab-k3s-proxmox architecture

> Architecture diagram of the GitHub repository osialek/homelab-k3s-proxmox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/osialek/homelab-k3s-proxmox
- Repository: https://github.com/osialek/homelab-k3s-proxmox

## Overview

##### Project Type and Purpose
- This is an infrastructure-as-code project designed to set up a lightweight Kubernetes (K3s) cluster deployed on a Proxmox VE cluster in a homelab environment. The project uses Terraform for provisioning the Proxmox-based infrastructure and Flux as a GitOps tool to manage the Kubernetes applications (like the NFS CSI Driver and MetalLB).

##### Analyzing the File Structure
- The directory tree is split into two main areas:
- The “terraform” directory holds Infrastructure-as-Code files that configure the K3s cluster provisioning on the Proxmox nodes (e.g., nodes, networking, Proxmox provider setup, etc.).
- The “flux” directory contains subdirectories for the K3s cluster’s GitOps configuration. It includes definitions for various applications (such as the “csi-driver-nfs” and “metallb”) using Helm charts and Kustomize to deploy networking components.
- Notice the separation of responsibility: Terraform scripts manage the infrastructure layer, while Flux manages the continuous deployment aspect on the K3s cluster.

a. Main Components to Identify:
- Physical Infrastructure:
- ISP & Router – the external connectivity point.
- Room 1: Contains the MiniPC Cluster running Proxmox VE (each host with noted hardware specifications).
- Room 2: Contains the NAS for storage, UPS, and access point.
- Virtual Infrastructure:
- Proxmox Cluster – the hypervisor platform running on the MINI PCs.
- K3s Cluster – deployed on top of the Proxmox cluster. It should detail the control plane and worker nodes (1 control, 2 workers based on the README).
- GitOps/Flux System – responsible for deploying and managing networking apps (such as the NFS CSI Driver and MetalLB).
- Terraform Provisioner – automates the node provisioning and cluster setup.
- External Integrations:
- Synology NAS – illustrates storage integration using NFS CSI Driver.
- External network connections (ISP router, access points).

b. Relationships and Interactions:
- Links between the Proxmox cluster and the K3s cluster to indicate that K3s is deployed on top of the virtual machines provisioned by Terraform.
- NAS to the K3s cluster (through the NFS CSI Driver) indicating external storage integration.
- Networking flows from the ISP router to Room 1 and Room 2, showing access points and switches connecting the mini PCs, NAS, etc.

c. Architectural Patterns and Design Principles:
- Clearly separate the infrastructure provisioning (Terraform) from the application deployment (Flux GitOps). This separation of concerns is crucial.
- Automation for both provisioning and deployment, reflecting the GitOps approach where the desired state is defined in code.

d. Technologies and Frameworks to Highlight:
- Terraform for provisioning and configuration of the Proxmox nodes and K3s cluster.
- Kubernetes (K3s) as the container orchestration platform.
- Flux as the GitOps operator managing Kubernetes applications/configurations.
- Specific components deployed via Flux: NFS CSI Driver for storage integration with the NAS, and MetalLB for load balancing.
- The hardware (Proxmox VE on MINI PCs) and network infrastructure aspects (ISP router, access points, and NAS).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Physical Infrastructure Layer
    subgraph "Physical Infrastructure"
        ISP["ISP & Router"]:::physical
        Room1["Room 1: MiniPC Cluster"]:::physical
        Room2["Room 2: NAS & Access Point"]:::physical
    end

    %% Virtual Infrastructure Layer
    subgraph "Virtual Infrastructure"
        PVE["Proxmox VE Cluster"]:::virtual
        K3sCluster["K3s Cluster (1 CP, 2 Workers)"]:::virtual
    end

    %% Automation & GitOps Layer
    subgraph "Automation & GitOps"
        Terraform["Terraform Provisioner"]:::automation
        Flux["Flux GitOps System"]:::automation
    end

    %% Applications Layer
    subgraph "Applications"
        NFS["NFS CSI Driver"]:::application
        MetalLB["MetalLB"]:::application
    end

    %% Connections between Physical components
    ISP -->|"connects"| Room1
    ISP -->|"connects"| Room2
    Room1 -->|"hosts"| PVE
    Room2 -->|"provides storage"| NFS

    %% Infrastructure provisioning & deployment
    Terraform -->|"provisions"| PVE
    PVE -->|"hosts VMs for"| K3sCluster
    Flux -->|"deploys to"| K3sCluster

    %% GitOps deploys applications
    Flux -->|"deploys"| NFS
    Flux -->|"deploys"| MetalLB

    %% Styling
    classDef physical fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef virtual fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef automation fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef application fill:#FFFF99,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click Terraform "https://github.com/osialek/homelab-k3s-proxmox/blob/main/terraform/k3s-cluster/terraform.tf"
    click K3sCluster "https://github.com/osialek/homelab-k3s-proxmox/tree/main/flux/k3s-cluster"
    click Flux "https://github.com/osialek/homelab-k3s-proxmox/tree/main/flux/k3s-cluster/flux-system"
    click NFS "https://github.com/osialek/homelab-k3s-proxmox/tree/main/flux/k3s-cluster/apps/networking/csi-driver-nfs"
    click MetalLB "https://github.com/osialek/homelab-k3s-proxmox/tree/main/flux/k3s-cluster/apps/networking/metallb"
```
