Proxmox Mini - Homelab Automation

This repository contains Infrastructure as Code (IaC) configurations and scripts for automating a Proxmox-based homelab, specifically focused on deploying and managing a k0s Kubernetes cluster.

🚀 Overview

The project provides two primary methods for managing Proxmox infrastructure:

1. Terraform (k0s-homelab/): The original implementation for provisioning VMs and setting up the initial k0s cluster.
2. Pulumi (pulumi-homelab/): A Python-based implementation offering more dynamic management, used for ongoing operations and scaling.

⚙️ Proxmox Setup

Before deploying the infrastructure, ensure your Proxmox environment is prepared:

1. API Access: Create an API token (e.g., root@pam!token-id) with appropriate permissions (Administrator or a custom role with VM/Storage access).
2. Cloud-Init Image: Download and store a cloud-init compatible image (e.g., Ubuntu 24.04 Noble) in your Proxmox ISO/Snippet datastore.
   • Default expected ID: local:iso/ubuntu-24.04-server-cloudimg-amd64.img.
3. SSH Configuration: Ensure the workstation running these tools has SSH access to the Proxmox nodes for snippet management and VM initial setup.
4. Network: The configuration assumes a bridge (e.g., vmbr0) with access to your desired subnet (e.g., 192.168.1.0/24).

☸️ k0s Cluster

The cluster is designed as a highly available (HA) or single-controller k0s deployment across multiple physical hosts.

Cluster Topology (Example)

• Control Plane: 1 Controller (k0s-controller)
• Worker Nodes: 3-4 Workers (k0s-worker-1, k0s-worker-2, etc.)
• OS: Ubuntu 24.04 LTS (Cloud-Init managed)
• Network Plugin: Kube-Router (default k0s)

Deployment Workflow

1. Provision: Use Terraform or Pulumi to create the virtual machines.
2. Guest Agent: Ensure qemu-guest-agent is installed on all nodes.
3. Bootstrap: Execute k0sctl apply --config k0sctl.yaml to install and initialize the k0s service on all nodes.
4. Access: Retrieve the kubeconfig via k0sctl kubeconfig > kubeconfig.yaml.

📁 Project Structure

• k0s-homelab/: Terraform modules and configurations to provision Proxmox VMs and deploy k0s using k0sctl.
• pulumi-homelab/: Python-based Pulumi project for managing VMs.
• scripts/: Utility scripts for cluster inspection and management.
• docs/: Supplemental documentation and resource references.

🏗️ Infrastructure Details (Default)

The default configuration can be customized in terraform.tfvars or Pulumi.dev.yaml.

Node Name	Role	Resources
k0s-controller	Controller	2 vCPU, 4GB RAM
k0s-worker-1	Worker	4 vCPU, 8GB RAM
k0s-worker-2	Worker	4 vCPU, 8GB RAM
k0s-worker-3	Worker	4 vCPU, 8GB RAM

🏁 Quick Start: 0 to 1 Deployment

This guide will take you from a fresh clone to a running k0s cluster.

1. Configuration Setup

The repository uses .example templates for all sensitive configurations to prevent accidental credential leaks. You must create local versions of these files before proceeding:

For Terraform (Provisioning):

cp k0s-homelab/terraform.tfvars.example k0s-homelab/terraform.tfvars
cp k0s-homelab/k0sctl.yaml.example k0s-homelab/k0sctl.yaml
# Edit both files with your Proxmox IPs, API tokens, and SSH keys.

For Pulumi (Alternative Provisioning/Ops):

cp pulumi-homelab/Pulumi.dev.yaml.example pulumi-homelab/Pulumi.dev.yaml
cp pulumi-homelab/nodes.py.example pulumi-homelab/nodes.py
# Edit these with your environment-specific node maps and settings.

2. Infrastructure Provisioning

Choose either Terraform (recommended for initial setup) or Pulumi.

Option A: Using Terraform

cd k0s-homelab
terraform init
terraform apply

Option B: Using Pulumi

1. Set up environment:

   cd pulumi-homelab
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

2. Configure credentials: Pulumi uses environment variables for Proxmox access (see OPERATIONS_GUIDE.md for details):

   export PROXMOX_VE_ENDPOINT='https://<PROXMOX_IP>:8006/'
   export PROXMOX_VE_API_TOKEN='USER@REALM!TOKENID=UUID'
   export PROXMOX_VE_INSECURE='true'

3. Deploy:

   pulumi stack init dev
   pulumi up

3. Kubernetes Deployment

Once the VMs are running and qemu-guest-agent is active:

1. Bootstrap the cluster:

   k0sctl apply --config k0sctl.yaml

2. Access the cluster:

   k0sctl kubeconfig --config k0sctl.yaml > kubeconfig.yaml
   export KUBECONFIG=$(pwd)/kubeconfig.yaml
   kubectl get nodes

---

⚙️ Proxmox Setup

Refer to the project's license file for usage terms (if applicable).