Optimising Your Proxmox Cluster with ProxLB - Smart and Lightweight VM/CT Scheduling for Maximum Efficiency

Introduction

In many Proxmox VE deployments, administrators routinely monitor resource usage and rely on manual workload migration to prevent node overload. However, what if you could let software take care of that scheduling and rebalancing for you? Enter ProxLB - an advanced, open source resource scheduler and load balancer for Proxmox clusters developed by Florian Paul Azim Hoberg (known on GitHub as “gyptazy”). (github.com)

ProxLB is designed to bridge a missing capability in Proxmox VE: intelligent, continuous workload balancing across nodes based on real-time resource metrics. This makes it particularly relevant for IT operations teams, NOC engineers and infrastructure architects seeking to optimise their virtualisation farms.

In this article, we’ll walk through what ProxLB does, how it works, the key features, installation and operational considerations - plus how you might leverage it in your own Proxmox environment.

Why ProxLB Matters

While Proxmox VE provides clustering, live migration, high availability and most of the core functionality needed for modern virtual infrastructure, it lacks a native dynamic resource scheduler akin to VMware’s DRS. ProxLB fills this gap by doing the following:

• Continuously measuring node resource usage (CPU, memory, local disk) and guest usage.
• Calculating “balanciness” - the delta between the highest-loaded node and lowest-loaded node. If that delta exceeds a threshold, it migrates VMs/CTs.
• Supporting affinity and anti-affinity rules (grouping or separating workloads) to meet architecture / high-availability requirements.
• Providing a maintenance mode: designate a node for maintenance and automatically migrate its workloads off.
• Integrating via the Proxmox API (no SSH required), allowing CI/CD pipelines (e.g., Ansible/Terraform) to query the best node for a new VM/CT placement.

For organisations operating multi-node Proxmox clusters (for example: edge-distribution-access architectures, or across racks/data-halls), this means reduced manual scheduling, better resource utilisation, lower risk of hotspots and more deterministic workload placement.

Key Features & Capabilities

Automated balancing by resource type

• Balancing of VMs/containers based on memory, CPU or local disk usage.
• Modes of balancing: ‘used’ resources, ‘assigned’ resources (to avoid over provisioning) or PSI (pressure metrics) if supported.
• One-shot (manual trigger) or daemon (scheduled interval) operation.

Affinity / Anti-Affinity & Pinning

• Tag-based grouping: e.g., plb_affinity_web ensures VMs with that tag run on the same node, plb_anti_affinity_db ensures separation.
• Ignoring VMs: tag a VM/CT with plb_ignore_<tag> to prevent migration.
• Pinning VMs/CTs to specific nodes: tag plb_pin_nodename. Useful for licensing, hardware-attached devices, etc.

Maintenance mode

• Define maintenance_nodes in the configuration. When set, ProxLB migrates all workloads off those nodes, enabling safe updates/reboots.

CI/CD and automation friendly

• A CLI option returns the “best next node” for placement (--best-node), enabling integration in automation pipelines like Terraform or Ansible.
• Runs via Proxmox API - respects ACLs and avoids the need for SSH or root access.

Installation flexibility & platform support

• Supports Proxmox VE versions 7.x, 8.x, 9.x.
• Install via Debian-based repository (.deb), or run as container (Docker/Podman).
• Runs on any architecture supporting Python3 (amd64, arm64, rv64).

How It Works - Under the Hood

To appreciate how ProxLB orchestrates workload balancing, here’s a simplified breakdown:

1. Metric Collection

   • ProxLB queries the Proxmox API for each node in the cluster: CPU usage, memory usage, local disk usage.
   • It also queries each VM/CT running on those nodes.

2. Balanciness Calculation

   • It computes the difference between the most loaded node and least loaded node for the chosen metric.
   • If this delta (balanciness) exceeds a configured threshold (balanciness: 10, for example) then rebalancing is triggered.

3. Migration Decision Matrix

   • It sorts VMs/CTs by highest usage (or highest assigned resources) depending on mode.
   • It picks the guest with highest resource usage as a candidate to be moved.
   • It selects the node with the most free resources for the selected metric.
   • It migrates the guest (live migration if live: true).
   • It repeats until balanciness is within target threshold.

4. Pre-checks

   • Checks affinity/anti-affinity rules, ignoring VMs/CTs, pinning constraints.
   • For example, if an HA group is defined, ProxLB currently warns of possible conflicts.

5. Execution Modes

   • One-time run (e.g., post maintenance or manually triggered).
   • Daemon mode (runs at interval, e.g., every 12 hours).

This mechanism allows ProxLB to bring cluster workloads back into balance without constant manual oversight.

Installation & First-Run Overview

Prerequisites

• Proxmox VE cluster (7.x / 8.x / 9.x) with at least two nodes.
• Python3 available (if running from source) and Proxmox API reachable.
• Create a service user or use API token with appropriate privileges.

Quick Install (Debian-based)

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    # adjust config  
systemctl start proxlb  

Container Install (Docker/Podman)

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    # adjust config  
docker run -it --rm -v $(pwd)/proxlb.yaml:/etc/proxlb/proxlb.yaml proxlb  

Basic Configuration Snippet

proxmox_api:
  hosts:
    - node01.example.com
    - node02.example.com
  user: root@pam
  token_id: proxlb
  token_secret: 430e308f-1337-1337-beef-1337beefcafe
  ssl_verification: true

proxmox_cluster:
  maintenance_nodes:
    - node03.example.com
  ignore_nodes: []
  overprovisioning: false

balancing:
  enable: true
  enforce_affinity: false
  parallel: false
  live: true
  with_local_disks: true
  with_conntrack_state: true
  balance_types: ['vm','ct']
  memory_threshold: 75
  balanciness: 5
  method: memory
  mode: used

Validate and Run

• Start the service and monitor logs (journalctl -u proxlb) or run in dry-run mode (proxlb --dry-run) to preview migrations.
• After the first run, review migration logs and confirm guests landed on optimum nodes.

Operational Considerations

For technical directors and cluster operators:

• Align with HA strategy: ProxLB may conflict with Proxmox HA groups. Test thoroughly if you rely on HA for critical workloads.
• Maintenance windows: Use maintenance mode to drain nodes before hardware or firmware updates.
• Tagging strategy: Define tags for affinity/anti-affinity early so clustering behaviour aligns with service tiers.
• CI/CD integration: Use the --best-node output in Ansible or Terraform workflows for resource-aware deployments.
• Monitoring & Logs: Feed ProxLB logs into your NOC’s monitoring system to track migrations and balance changes.
• Testing in staging: Always validate behaviour using dry-run mode before enabling live migrations.
• Versioning & upgrades: Keep track of releases like 1.1.0, which introduced major refactoring and bug fixes.

Pros & Cons Summary

Advantages

• Automates workload distribution based on real-time metrics, reducing hotspots and manual balancing.
• Supports affinity, anti-affinity, pinning, and ignore rules for fine-grained placement control.
• API-based design integrates cleanly with CI/CD pipelines without relying on SSH.
• Flexible installation options available (Debian package or container) across architectures.

Considerations

• May conflict with Proxmox HA groups and requires careful testing before production rollout.
• Complex configuration demands well-planned tagging and policy strategies.
• Live migrations can impact performance on workloads using local storage.
• Developed by Florian "gyptazy" Hoberg and backed by credativ GmbH, so enterprise-grade support is available.

Use Case Example: Edge / Distributed Infrastructure

For multi-customer NOC operations, ProxLB can be integrated like this:

• Operate a 5-node cluster for an edge location running Wi-Fi controllers and customer VMs.
• Tag VMs as ‘event-ctrl’, ‘wifi-mgmt’, and ‘customer-vm’.
• Set affinity for controllers and anti-affinity for critical customer VMs.
• Configure ProxLB to rebalance every 6 hours by memory usage, threshold 70%, balanciness 10%.
• Use maintenance mode to automatically drain one node nightly.
• Integrate proxlb --best-node --json into Ansible playbooks for optimal placement.
• Monitor logs to identify recurring migrations or hardware issues.

Final Thoughts

ProxLB is an open source solution that finally gives Proxmox administrators a missing link: intelligent, automated workload balancing. With a thoughtful configuration and good monitoring, it can drastically reduce manual intervention and improve resource efficiency across clusters.

For organisations managing multiple Proxmox clusters, ProxLB offers both operational savings and improved reliability. Plan your tag schema, test your migration scenarios, and integrate it into your existing CI/CD pipeline to unlock its full potential.

Additional Resources

• GitHub: gyptazy/ProxLB
• Official site: proxlb.de
• Community discussion: Reddit - ProxLB for Proxmox Load Balancing