Building a Home Lab with Proxmox and Terraform (for Kubernetes)

Lately, I’ve been exploring new topics and decided it was time to level up my DevOps skills. This led me to build something I genuinely enjoyed working on: a home lab using Proxmox, with Terraform to provision virtual machines.

And yes — if you’re wondering what this is all for…
👉 we’re heading toward a Kubernetes cluster.

🎯 What You Will Build

In this post, we will set up:

A Proxmox-based home lab
A reusable VM template
A Terraform configuration to provision: 3 control plane nodes and 3 worker nodes
An automatically generated Ansible inventory for future automation

This creates a solid foundation for building and experimenting with Kubernetes locally.

Here is the diagram of what we are trying to achieve.

🤔 Why This Setup?

Before jumping into the implementation, let’s talk about the decisions behind it.

🧠 Why Proxmox vs Cloud?

Cloud providers like AWS or Azure are incredibly convenient. However, for experimentation and learning, I wanted something more predictable and cost-efficient.

Running a home lab with Proxmox gives me:

Full control over the infrastructure
No ongoing costs for spinning resources up and down
A safe environment where I can break things without worrying about billing
In the cloud, even small experiments can become expensive if you forget to tear resources down. With Proxmox, once the hardware is set up, I can experiment freely.

That said, this is not a replacement for the cloud — it’s a complement for learning and testing before moving workloads to production environments.

⚙️ Why Terraform vs Ansible-only?

Ansible is excellent for configuration management, but when it comes to provisioning infrastructure, Terraform is a better fit.

With Terraform, I get:

Declarative infrastructure (desired state)
Idempotency by design
A clear execution plan (terraform plan)
While Ansible can provision VMs, that’s not its primary strength.

In this setup:

Terraform → provisions infrastructure
Ansible → configures what runs inside it (coming next 👀)

🌐 Why Static IP vs DHCP Reservation?

I chose to assign static IPs using cloud-init instead of relying on DHCP reservations.

Why?

Predictability → IPs are defined in code
Portability → no dependency on router configuration
Reproducibility → same setup anywhere
DHCP reservations work fine, but they introduce an external dependency. By keeping everything in Terraform, the entire infrastructure becomes reproducible.

☁️ Why Not Just Use the Cloud?

For many real-world scenarios, the cloud is absolutely the right choice.

But for learning:

Costs can grow quickly
You depend on internet access
You may hesitate to experiment freely
With a home lab:

You can break things safely
No cost anxiety
Faster iteration for small tests
The goal here is to validate ideas locally before scaling them in the cloud.

☸️ Why Not Use k3s Instead of Full Kubernetes?

k3s is a fantastic lightweight Kubernetes distribution — especially for edge or low-resource environments.

However, my goal is to:

Learn Kubernetes closer to production setups
Understand control plane components
Get hands-on experience with kubeadm
k3s simplifies a lot of this (which is great in practice), but I want to understand what’s happening under the hood.

🖥️ Lab Setup

Let’s talk about the hardware.

I used a gaming desktop that I originally built for gaming — ironically, that’s the one thing I’m not using it for anymore.

I added a 1 TB SATA SSD, which is more than enough for this setup. Even a 500 GB drive would work fine.

If you have more budget, you could:

Buy a Mini PC
Build a dedicated home server
At minimum, you need:

A machine that supports virtualization

🧰 Tools Used

Proxmox VE
Terraform
Basic Linux knowledge

🧠 What is Proxmox VE?

Proxmox VE (Virtual Environment) is an open-source virtualization platform based on Debian Linux.

It allows you to:

Create and manage virtual machines
Use containers (LXC)
Manage everything via a web UI
It’s a powerful and lightweight alternative to tools like VMware.

🌐 Networking Considerations

Before installing Proxmox, it’s a good idea to plan your network.

Your router assigns IP addresses via DHCP. To avoid conflicts, you should reserve a range of IPs.

Example:

DHCP range: 192.168.0.100 → 192.168.0.250
Reserved range: 192.168.0.2 → 192.168.0.99

During Proxmox installation, you can assign a static IP (e.g., 192.168.0.50).

💡 Nice Trick: Local DNS

You can add an entry to your hosts file:

192.168.0.50 myproxmox.lab

Now you can access:

http://myproxmox.lab:8006

Much nicer than using raw IPs.

🧱 VM Templates with QCOW2

Instead of manually creating VMs every time, we can use templates.

I created a script that:

Downloads a Debian image
Converts it into a Proxmox template
Prepares it for cloud-init

👉 Run it like this:

./create-debian12-template.sh 9000 local-lvm
This creates a reusable baseline for all VMs.

⚠️ Important

Make sure your template has:

qemu-guest-agent installed and enabled
This is required for proper VM communication with Proxmox.

⚙️ Provisioning with Terraform

Now comes the fun part.

Provider setup:

terraform {
  required_providers {
    proxmox = {
      source  = "bpg/proxmox"
      version = "~> 0.69"
    }
  }
}

provider "proxmox" {
  endpoint  = var.proxmox_host_address
  api_token = "${var.pm_api_token_id}=${var.pm_api_token_secret}"
  insecure  = true
}

🔐 API Token Format

You can create the API Token using Proxmox VE UI

<user>@<realm>!<tokenid>=<secret>

⚠️ About insecure = true

This is used because Proxmox uses a self-signed certificate.

Better alternatives:

Add Proxmox certificate to trusted store
Use Let’s Encrypt

🖥️ Creating Control Plane VMs

Using Terraform, we define:

CPU / Memory
Network
Static IP
Cloud-init configuration
Each VM is cloned from the template and customized.

📦 Variables: The Real Power

All configuration is centralized in variables.tf.

This allows you to:

Scale nodes easily
Change resources quickly
Reuse the setup in different environments

🚀 Running Terraform

terraform validate
terraform plan
terraform apply
Then watch the magic happen in the Proxmox UI.

📄 Generating Ansible Inventory

Terraform also generates a ready-to-use inventory:

resource "local_file" "ansible_inventory" {
  ...
}

This will be used in the next step when we configure Kubernetes with Ansible.

📦 Full Source Code

👉 https://github.com/PellizzoniCode/proxmox_terraform

🔜 What’s Next?

This is just the beginning.

In the next post, I’ll:

Bootstrap Kubernetes using kubeadm
Configure networking with a CNI plugin
Prepare the cluster for real workloads

👋 Final Thoughts

This setup has been a great way to:

Learn DevOps in a practical way
Experiment without worrying about cost
Build a solid foundation for Kubernetes
If you have any questions or suggestions, feel free to reach out — I’d love to hear your feedback.

Also, visit the original post with more details on my blog PellizzoniCode.NET

See you in the next one 🚀

If you found this useful, feel free to share or leave a comment — it really helps 🙌

推荐订阅源

DEV Community