---
layout: blog_post
tags: blog
title: 'pve-lab: Running a Proxmox cluster locally using KVM'
permalink: /blog/2026/08/02/pve-lab/
slug: pve-lab
date: 2026-08-02 11:31:06
blogtags:
- linux
- networking
- virtualization
---

![](https://static.garrettmills.dev/assets/blog-images/pve-lab.png)

For years now, I've run my most of my self-hosted tools in a Kubernetes cluster which I run in LXC containers on Proxmox. For the "average" self-hoster, this is massively over-complicated. However, since I work with both Proxmox and Kubernetes (herein, k8s) professionally, this gives me a full-fledged environment to play with.

I'm currently working on a few software tools to make this a nicer/more cloud-like experience, but until now developing them has meant pointing them at my *main* PVE cluster. So, if anything breaks or goes wrong, I have to clean it up by hand lest it destroy any resources in my PVE cluster that I actually rely on.   

I wanted a way to spin up a *representative* PVE cluster to experiment on without trashing my main cluster. I also wanted to be able to destroy the damned thing and re-created it cleanly should anything go awry.   

Enter: `pve-lab`, a collection of scripts that automatically provision and form a Proxmox cluster using KVM virtual machines and a virtual network for local testing on your Linux machine.   

```text
pve-net  (NAT 10.10.10.0/24, gw .1)
├── pve1      10.10.10.11   PVE node   4 vCPU / 8 GB / 48 GB
├── pve2      10.10.10.12   PVE node   4 vCPU / 8 GB / 48 GB
└── pvestore  10.10.10.13   Debian 13  2 vCPU / 2 GB  (NFS + iSCSI target)
```

After running these scripts, you are left with a PVE cluster that:

1. Can run VMs and LXC containers thanks to nested virtualization.
2. Has 2 separate nodes, for testing migrations.
3. Is network-accessible from the host machine via `10.10.10.x` local network.
4. Includes shared storage mounts in both NFS and iSCSI format, thanks to a 3rd "storage VM"
5. Can be torn-down and re-created on a whim using scripts.

These scripts assume you're using Fedora (as I am and, indeed, as we all ought to be), so some adjustment may be required for other distributions.   

I've used this to good effect when testing Proxmox configs and automations. To aid LLM-assisted testing, the `cluster-info` script can output a Markdown file describing the cluster for use w/ LLMs (or myself in the future, when I inevitably forget).   

Of note: I used Claude (namely, Opus 4.8 and Sonnet 5) when drafting these scripts, though I have reviewed and tested them by-hand. These words, however, are [human-written as always](/blog/ai-use/).   

These scripts and accompanying documentation are available [on my Git server](https://code.garrettmills.dev/garrettmills/pve-lab) under the terms of the MIT License.   
