How osialek/homelab-k3s-proxmox works
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).