ProxLB – The advanced Load Balancer for Proxmox Clusters

Table of Content

Introduction

ProxLB

ProxLB is an advanced, fully automated load-balancing solution purpose-built for Proxmox Virtual Environment (PVE) clusters.
It fills the gap left by Proxmox’s built-in scheduler by intelligently distributing workloads across nodes — ensuring optimal resource usage, reducing overprovisioning, and improving cluster stability.

Workloads can be balanced automatically based on CPU, memory, or disk usage, or even according to assignment rules and time intervals. ProxLB empowers administrators to define exactly how resources should be utilized — from lightweight homelabs to complex multi-node enterprise setups.

ProxLB is 100% open-source and free to use, modify, and extend. It fully supports filtering and exclusion rules via configuration files or API calls, allowing highly customized balancing behavior.

A key highlight is the maintenance mode:
When a node is marked for maintenance, all running guests are automatically migrated to other nodes, allowing safe reboots, updates, or hardware work — without service interruption.

Additionally, affinity and anti-affinity rules let operators control VM grouping and separation for optimal redundancy and performance. ProxLB can even return the best next node for CI/CD automation, integrating seamlessly with Ansible, Terraform, and other orchestration tools.

Because it operates purely over the Proxmox API, ProxLB inherits Proxmox’s ACL system for secure access — no SSH required.

In short, ProxLB intelligently distributes workloads, minimizes downtime, respects complex placement rules, and enhances automation — making it an essential companion for serious Proxmox users.

Video of Migration with ProxLB

You can also find my talk about ProxLB on YouTube and PeerTube in my list of my tech-talks.

Features

ProxLB provides intelligent, rule-based load balancing for both VMs and CTs, allowing automatic or on-demand rebalancing based on real resource utilization.
It integrates deeply with the Proxmox API, supports maintenance automation, affinity logic, and multiple usage modes — from single runs to continuous background operation.

Key Features of ProxLB

• Intelligent VM/CT rebalancing based on:
  • Memory
  • CPU
  • Local Disk Usage
• Determine the best node for new VM/CT placements
• Maintenance Mode:
  • Mark node(s) as maintenance
  • Automatically migrate workloads away
• Affinity & Anti-Affinity Rules
• Complete API-based operation:
  • Fully integrated with Proxmox ACLs
  • No SSH required
• Supported Usage Modes:
  • One-Time Execution
  • Continuous Daemon Service
  • Optional Proxmox Web GUI Integration

How does it work?

ProxLB collects live resource data from all nodes in a Proxmox cluster via the Proxmox API — including memory, CPU, and disk utilization for each VM and CT.
It then calculates a balanciness index, measuring how evenly resources are used across the cluster. If this index exceeds a configurable threshold, ProxLB initiates the rebalancing process.

Using a balancing matrix, ProxLB identifies the guests with the highest resource usage and migrates them to the nodes with the most free capacity — based on the selected balancing type (CPU, memory, or disk).
This process repeats recursively until balance is achieved, either by used or assigned resources, depending on configuration.

The result: a cluster that automatically maintains equilibrium, without manual intervention or downtime.

Installation

Requirements

• Proxmox VE 7.x / 8.x / 9.x
• Python 3.x
• proxmoxer, requests, urllib3, pyyaml

Install dependencies manually:

pip install -r requirements.txt

Using .deb or Docker images automatically handles all dependencies.

Debian Package Installation

ProxLB runs on multiple architectures (amd64, arm64, rv64, etc.) and can be installed directly via APT.

Quick-Start

echo "deb https://repo.gyptazy.com/stable /" > /etc/apt/sources.list.d/proxlb.list
wget -O /etc/apt/trusted.gpg.d/proxlb.asc https://repo.gyptazy.com/repository.gpg
apt-get update && apt-get -y install proxlb
cp /etc/proxlb/proxlb_example.yaml /etc/proxlb/proxlb.yaml
vi /etc/proxlb/proxlb.yaml
systemctl start proxlb

After setup, ProxLB runs in the background, balancing your cluster according to the defined method (default: memory).

Repository Info

• Stable: https://repo.gyptazy.com/stable
• Testing: https://repo.gyptazy.com/testing

GPG key: repository.gpg

Manual Installation (.deb)

If you prefer, download .deb packages directly:

• https://cdn.gyptazy.com/debian/

Then install manually:

dpkg -i proxlb_*.deb
cp /etc/proxlb/proxlb_example.yaml /etc/proxlb/proxlb.yaml
vi /etc/proxlb/proxlb.yaml
systemctl start proxlb

Container Images / Docker

Running ProxLB as a container is straightforward.

docker pull cr.gyptazy.com/proxlb/proxlb:latest
wget -O proxlb.yaml https://raw.githubusercontent.com/gyptazy/ProxLB/main/config/proxlb_example.yaml
vi proxlb.yaml
docker run -it --rm -v $(pwd)/proxlb.yaml:/etc/proxlb/proxlb.yaml proxlb

Official registries:

• cr.gyptazy.com

Source Installation

Clone and run directly from source:

git clone https://github.com/gyptazy/ProxLB.git
cd ProxLB
python3 proxlb/main.py -c config/proxlb.yaml

To build your own container image:

docker build -t proxlb .
docker run -it --rm -v $(pwd)/proxlb.yaml:/etc/proxlb/proxlb.yaml proxlb

Usage & Configuration

ProxLB runs anywhere with Python 3 and network access to the Proxmox API — locally, remotely, or in containers.
It can rebalance automatically on a schedule or run on demand.

Affinity & Anti-Affinity Rules

ProxLB uses Proxmox guest tags to define placement rules directly from the Web UI.

Affinity

To group guests on the same host:
plb_affinity_talos

This allows you to group and stick multiple guests to the same node.

Anti-Affinity

To keep guests apart across different hosts:
plb_anti_affinity_ntp

If more guests than available nodes exist, ProxLB automatically selects the least loaded node.

Ignore Guests

To exclude a guest from any balancing: plb_ignore_dev

Pin Guests

To restrict guests to specific nodes:
plb_pin_node03

Multiple pin tags can be used to define allowed nodes.

The maintenance_nodes key allows marking one or more nodes for maintenance.
ProxLB automatically migrates workloads from those nodes while honoring affinity rules and available capacity.

Example:

proxmox_cluster:
  maintenance_nodes: ['virt66.example.com']

Misc

Support

Need help? Join the ProxLB community!

Note: ProxLB is maintained by a single developer — coding, packaging, and infrastructure included.
Please be patient and kind when reporting issues.

Enterprise Support

Running ProxLB in mission-critical production environments may require 24×7 support, SLA guarantees, or custom integration services. While ProxLB itself is a one-man open-source project, several organizations offer professional support for it. The following companies currently provide enterprise support for ProxLB:

• Germany: credativ.de