public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
From: Thomas Lamprecht <t.lamprecht@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH docs 15/15] pvecm: document balancing the cluster load with migrations
Date: Wed, 18 Nov 2026 12:05:22 +0100	[thread overview]
Message-ID: <20261118110705.595989-16-t.lamprecht@proxmox.com> (raw)
In-Reply-To: <20261118110705.595989-1-t.lamprecht@proxmox.com>

The web interface ranks the target nodes of a migration by the
resulting cluster load imbalance, and proposes rebalancing migrations
for all guests through the Rebalance Guests bulk action. Describe both
next to the other guest migration topics, and point there from the
CRS section of the HA chapter, which otherwise reads as if the
scheduler were available to HA resources only.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 ha-manager.adoc |  4 ++++
 pvecm.adoc      | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index 95ab799..671aab2 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1464,6 +1464,10 @@ from a fenced node or a new HA affinity rule. See the section
 xref:ha_manager_crs_scheduling_points[CRS Scheduling Points] for a more thorough
 description of which actions the CRS takes for specific changes in the cluster.
 
+The scheduler can also propose migrations on request, for all guests and
+independent of the HA Manager rounds, see
+xref:pvecm_migration_load_balancing[Balancing the Cluster Load].
+
 CRS Scheduling Mode
 ~~~~~~~~~~~~~~~~~~~
 
diff --git a/pvecm.adoc b/pvecm.adoc
index cd5a0fb..6e017f3 100644
--- a/pvecm.adoc
+++ b/pvecm.adoc
@@ -1712,6 +1712,57 @@ migration: secure,network=10.1.2.0/24
 NOTE: The migration type must always be set when the migration network
 is set in `/etc/pve/datacenter.cfg`.
 
+[[pvecm_migration_load_balancing]]
+Balancing the Cluster Load
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The scheduler that the HA stack uses to place its resources, see
+xref:ha_manager_crs[Cluster Resource Scheduling], can also assist with the
+migrations you start yourself. This works for all guests, whether they are
+managed by HA or not, and requires the `VM.Migrate` privilege on them.
+
+The scheduler rates a migration by the cluster imbalance it would result in.
+The imbalance tells how much the load differs between the nodes, from 0% for an
+evenly loaded cluster up to 100%. It is calculated from the average CPU and
+memory usage of the nodes and their running guests. As long as a node did not
+report its usage yet, the configured CPU and memory limits of the guests are
+used instead. The CRS scheduling mode set for HA has no influence on this.
+
+When you migrate a running guest in the web interface, the target node selector
+lists the nodes by the imbalance that a migration to them would result in, and
+preselects the best one. Whether a migration is possible at all is still
+determined by the usual migration checks. Nodes that these checks rule out, for
+example because of an HA rule, are listed last.
+
+To spread the load of the whole cluster, select `Datacenter` -> `Bulk Actions`
+-> `Rebalance Guests` in the web interface. This opens the bulk migration dialog
+with a proposal of up to ten migrations that lower the cluster imbalance. Before
+you start them with `Migrate`, you can change the target node of each guest or
+deselect guests. `Suggest Migrations` requests a new proposal for the selected
+guests, or for all listed guests if none are selected. The same button is
+available in `Datacenter` -> `Bulk Actions` -> `Bulk Migrate`.
+
+A proposal follows these rules:
+
+* Only running guests are proposed, and no guests with a lock, for example from
+  a running backup.
+* Guests managed by HA are only proposed if their HA resource is started, and
+  only for nodes that their HA rules allow. Guests that HA would migrate
+  together with others because of a positive resource affinity are not proposed.
+* Nodes in HA maintenance mode are left out.
+* Migrations that would barely improve the balance are not proposed, as every
+  migration disrupts its guest.
+
+NOTE: Running containers are restarted when they are migrated, see the
+xref:pct_migration[Container Migration Chapter].
+
+The proposals are also available through the API, for example:
+
+----
+# pvesh get /cluster/resource-scheduling/recommend-target-nodes --vmid 100
+# pvesh create /cluster/resource-scheduling/rebalance-plan
+----
+
 
 ifdef::manvolnum[]
 include::pve-copyright.adoc[]
-- 
2.47.3





      parent reply	other threads:[~2026-11-18 11:08 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-18 11:05 [PATCH guest-common,ha-manager,manager,docs 0/15] cluster resource scheduling for all guests Thomas Lamprecht
2026-11-18 11:05 ` [PATCH guest-common 01/15] scheduling: add cluster resource scheduling library Thomas Lamprecht
2026-11-18 11:05 ` [PATCH ha-manager 02/15] helpers: block both locations of a migrating negative affinity partner Thomas Lamprecht
2026-11-18 11:05 ` [PATCH ha-manager 03/15] usage: static: count services per node again for scoring fallback Thomas Lamprecht
2026-11-18 11:05 ` [PATCH ha-manager 04/15] config: allow getting motion info of many resources at once Thomas Lamprecht
2026-11-18 11:05 ` [PATCH ha-manager 05/15] env: pve2: delegate cluster stat gathering to scheduling library Thomas Lamprecht
2026-11-18 11:05 ` [PATCH ha-manager 06/15] usage: share one scheduler base between static and dynamic Thomas Lamprecht
2026-11-18 11:05 ` [PATCH manager 07/15] ui: bulk action: translate error title and CT restart warning Thomas Lamprecht
2026-11-18 11:05 ` [PATCH manager 08/15] ui: bulk migrate: show CT restart warning for cluster-wide migration Thomas Lamprecht
2026-11-18 11:05 ` [PATCH manager 09/15] ui: migrate: recheck preconditions if the target changed meanwhile Thomas Lamprecht
2026-11-18 11:05 ` [PATCH manager 10/15] api: cluster: add resource scheduling endpoints Thomas Lamprecht
2026-11-18 11:05 ` [PATCH manager 11/15] ui: migrate: sort target nodes by scheduler recommendation Thomas Lamprecht
2026-11-18 11:05 ` [PATCH manager 12/15] api: bulk migrate: allow a per-guest target node mapping Thomas Lamprecht
2026-11-18 11:05 ` [PATCH manager 13/15] ui: bulk migrate: support per-guest target nodes Thomas Lamprecht
2026-11-18 11:05 ` [PATCH manager 14/15] ui: dc: add a Rebalance Guests bulk action Thomas Lamprecht
2026-11-18 11:05 ` Thomas Lamprecht [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261118110705.595989-16-t.lamprecht@proxmox.com \
    --to=t.lamprecht@proxmox.com \
    --cc=pve-devel@lists.proxmox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal