Ballast is a load balancer for Proxmox VE. It reads the load on every node and every guest, finds the imbalance, and produces a live-migration plan that levels it — which guest moves from the hottest node to the coolest, and what that does to the spread between them. Planning is read-only and safe to run anywhere; the migrations only happen when you ask for them with apply -yes.

One binary, standard library only. It ships a simulated Proxmox so you can plan and even apply against a fake cluster with nothing set up.

On the command line

$ ballast plan -endpoint https://pve.example.com:8006 -token svc@pve!ballast=uuid
spread 70% → 4%  ·  2 migration(s)  ·  balanced

VMID  GUEST   FROM  TO    REASON
102   db-01   pve1  pve2  frees 25% off pve1 onto pve2
103   app-01  pve1  pve3  frees 13% off pve1 onto pve3

plan shows the migrations; apply -yes performs them. With no -endpoint, Ballast runs against a built-in simulated cluster, so both work out of the box.

The console

The panel is a balance board. Each node shows its pressure now, in red when it is hot, beside its pressure after the plan, in green as it cools — so the overloaded node visibly empties and the idle ones fill. Next to it sit the spread the plan closes, the ordered list of live migrations with the memory each frees, and every node's projected state. The panel only ever shows the plan; performing it stays an explicit command.

Run the demo

The demo runs a simulated Proxmox with one badly overloaded node, so the board fills with a real imbalance and a plan that levels it.

make demo          # console at http://127.0.0.1:18260
make demo-down

Install

go install github.com/cansarihan/ballast/cmd/ballast@latest

or build from source:

git clone https://github.com/cansarihan/ballast
cd ballast
make build         # ./bin/ballast

Pointing at a real cluster

Create an API token in Proxmox with Sys.Audit and VM.Audit for planning, plus VM.Migrate to apply, then:

export BALLAST_TOKEN='svc-ballast@pve!ballast=00000000-0000-0000-0000-000000000000'
ballast plan  -endpoint https://pve.example.com:8006 -insecure
ballast apply -endpoint https://pve.example.com:8006 -insecure -yes

apply is a dry run until you pass -yes. -tolerance, -max-moves and -cap tune how aggressively it rebalances and how full it will let a target node get.

Commands

ballast serve   -listen 127.0.0.1:8080 [-endpoint https://pve:8006 -token ... -insecure]
ballast plan    [-endpoint https://pve:8006 -token ...]
ballast apply   [-endpoint https://pve:8006 -token ...] -yes
ballast sim     -listen 0.0.0.0:8006     # run the simulated Proxmox API on its own
ballast version

docs/architecture.md explains how the pieces fit together.

License

MIT — see LICENSE.