ProxLB - An Intelligent Resource Scheduler for Proxmox Clusters

ProxLB (Prox Load Balancer) (written by gyptazy) is an advanced tool designed to enhance the efficiency and performance of Proxmox clusters by optimizing the distribution of virtual machines (VMs) or Containers (CTs) across the cluster nodes by using the Proxmox API. ProxLB meticulously gathers and analyzes a comprehensive set of resource metrics from both the cluster nodes and the running VMs. These metrics include CPU usage, memory consumption, and disk utilization, specifically focusing on local disk resources.

PLB collects resource usage data from each node in the Proxmox cluster, including CPU, (local) disk and memory utilization. Additionally, it gathers resource usage statistics from all running VMs, ensuring a granular understanding of the cluster’s workload distribution.

Intelligent rebalancing is a key feature of ProxLB where it re-balances VMs based on their memory, disk or CPU usage, ensuring that no node is overburdened while others remain underutilized. The rebalancing capabilities of PLB significantly enhance cluster performance and reliability. By ensuring that resources are evenly distributed, PLB helps prevent any single node from becoming a performance bottleneck, improving the reliability and stability of the cluster. Efficient rebalancing leads to better utilization of available resources, potentially reducing the need for additional hardware investments and lowering operational costs.

Automated rebalancing reduces the need for manual actions, allowing operators to focus on other critical tasks, thereby increasing operational efficiency. Sounds interesting? You can find more details in my dedicated post about it right here.

Features

• Intelligent resource-based VM/CT distribution
• Affinity and anti-affinity rules for VMs/CTs
• Own Affinity/Anti-Affinity rules by Tags
• Own Affinity/Anti-Affinity rules by Pool
• Native Proxmox Affinity/Anti-Affinity rules support
• Pinning of VMs to specific node(s)
• Maintenance mode for nodes
• Customizable thresholds for resource usage
• Detailed logging and reporting
• Open-source and community-driven

Availability

ProxLB is available as a free and open-source tool, which can be easily installed and integrated into existing Proxmox VE clusters. It can be obtained from the gyptazy Debian repository or as a Docker/Container image from the gyptazy image registry.

Installation

ProxLB can be deployed in multiple ways depending on operational requirements. The recommended installation method is via the Debian repository for native system integration, while container images provide a lightweight and isolated alternative.

Debian Repository Installation (Recommended)

Installing ProxLB via the Debian repository ensures automatic dependency resolution, seamless systemd integration, and easy updates.

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 install -y proxlb

After installation, copy and adjust the configuration file:

cp /etc/proxlb/proxlb_example.yaml /etc/proxlb/proxlb.yaml
vi /etc/proxlb/proxlb.yaml

Start and enable the ProxLB service:

systemctl enable proxlb
systemctl start proxlb

Container Image Installation

ProxLB is also available as a ready-to-use container image. This approach is well suited for isolated environments or automation pipelines.

docker pull cr.gyptazy.com/proxlb/proxlb:latest

Run ProxLB by mounting the configuration file:

docker run -it --rm \
  -v $(pwd)/proxlb.yaml:/etc/proxlb/proxlb.yaml:ro \
  cr.gyptazy.com/proxlb/proxlb:latest

Configuration

ProxLB is configured using a single YAML file that defines API access, balancing behavior, scheduling, and optional rules such as affinity or maintenance mode.

Minimal Configuration Example

proxmox_api:
  hosts: ['virt01.example.com']
  token_id: proxlb
  token_secret: 430e308f-1337-1337-beef-1337beefcafe
  ssl_verification: true

balancing:
  enable: true
  method: memory
  mode: used
  balanciness: 10

service:
  daemon: true
  schedule:
    interval: 12
    format: hours

Affinity rules, anti-affinity rules, pinning, and maintenance behavior can be layered on top without modifying the core balancing logic.

Usage Modes

• Daemon Mode: Continuous background balancing at defined intervals
• One-Time Execution: Manual rebalancing on demand
• Dry-Run Mode: Evaluate balancing decisions without migrating workloads
• Automation Mode: Return the best target node for CI/CD tools such as Ansible or Terraform

Security & Best Practices

• Use API tokens instead of passwords
• Restrict API permissions to required objects only
• Avoid SSH-based automation – ProxLB operates fully via the Proxmox API
• Use maintenance mode instead of manual node evacuations
• Test new rules using dry-run mode before enforcing them

Additional Resources for ProxLB