I built a Proxmox VE node driver for Rancher
I run Kubernetes on Proxmox at home and got sick of building VMs by hand every time I wanted another node, so I wrote a Rancher node driver for PVE. Figured someone here might get some use out of it.
If you haven't used Rancher: it's an open source tool for managing Kubernetes clusters, and one of the things it can do is create them for you. You tell it you want 3 control plane nodes and 5 workers, and it goes off and makes the VMs, installs RKE2 or K3s on them, and joins them all into a cluster. It does that with things called node drivers, basically plugins that know how to make a VM on a given platform. There are official ones for AWS, vSphere, Azure, etc. There wasn't one for Proxmox.
Rancher cluster creation with Proxmox VE
So now there is. Once it's installed, Proxmox shows up as an option when you create a cluster in Rancher. You pick your template, node, CPU and RAM, data disks, say how many machines you want, and it clones them, runs cloud init, and joins them to the cluster. Scale a pool from 3 to 5 and two more VMs appear and join by themselves. Delete the cluster and they all get cleaned up.
Stuff it does that I actually cared about:
- Auth is a PVE API token, no root password sitting in a config. Every VM it makes goes into a resource pool you pick, so if you scope the token to that pool it genuinely can't touch the rest of your VMs becauseProxmox enforces it.
- Data disks get attached, formatted and mounted before the node joins, so Longhorn or Ceph get a real block device instead of a folder on the root disk. It finds them by disk serial rather than /dev/sdb, since that ordering goes out the window as soon as a VM has two data disks.
- DHCP or static IPs. For DHCP it asks the guest agent for the address and matches on MAC, so it doesn't grab some CNI bridge IP by accident.
- There's a UI extension too, which gives you proper dropdowns for node, template, storage and bridge pulled live from your PVE API.
You need Rancher 2.10 or newer, Proxmox 8 or 9, and a template with qemu-guest-agent and cloud init on it. There are template recipes for Debian 13 and openSUSE Leap Micro in the docs if you want to just follow along.
Install is two Helm charts on the Rancher local cluster, one for the driver and one for the UI bit. Both are in the repo.
If you want to take a look at the repo, here you go: https://github.com/Lore09/pve-rancher-driver
Questions welcome, and bug reports even more so if you try it on a setup that looks nothing like mine. My install is a single node with a flat network, so multi node clusters, Ceph and VLAN tagged bridges have all had far less real world use than the basic path has. If you run any of those and it breaks, I'd genuinely like to hear about it.
Posted Aug 3, 2026, 2:03 PM UTC