[PATCH-SERIES docs/manager v2 00/19] crs docs updates + load balancer ui and docs followup

[PATCH-SERIES docs/manager v2 00/19] crs docs updates + load balancer ui and docs followup

[Daniel Kral]

changes since v1 (thanks @Shannon, @Michael and @Dominik!):
- rebase on master
- fix typos and reword some bits as suggested in the review

I didn't go for the removal of disabled fields out of UX and consistency
and didn't go for adding the pvesh command because of the text flow, see
patches #5 and #7 for more information.



A followup to the static/dynamic load balancer series [0], which
includes the documentation and smaller UI improvements for configuring
the load balancer.

These patches also clean up the already existing CRS section and updates
it according to the other recent changes, such as:

- s/HA service/HA resource/ to avoid mixed usage of both terms in the
  same section
- basic/static-load scheduler mode include non-HA resources as well now
- the dynamic load scheduler is added now
- the dynamic load scheduler mode shares the behavior on
  rebalance-on-start now, moving this to its own section
- there's a section for the load balancer with some motivational text as
  well as some details about the configuration options
- update the crs datacenter gui screenshot accordingly

The UI patches fix some oversights that came up while writing the
documentation:

- add missing 'edit' subject in new crs modal
- s/HA service/HA resource/ to avoid mixed usage of both terms
- s/HA Scheduling/Scheduler Mode/ as it's referred so in the docs
- constrain users to only enable and set load balancer options if either
  'static' or 'dynamic' scheduler mode is set

I've marked the load balancer feature as technology preview now, to
hopefully get enough user feedback (and the according improvements) in
for a stable release for Proxmox VE 9.2. I'll leave this bit at the
discretion of the applying maintainer.

I'd be happy to have some feedback on the changes!

[0] https://lore.proxmox.com/pve-devel/20260402124817.416232-1-d.kral@proxmox.com/


manager:

Daniel Kral (5):
  ui: form/CRSOptions: add missing edit modal title
  ui: form/CRSOptions: rename HA Scheduling to Scheduling Mode
  ui: form/CRSOptions: replace HA service term with HA resource
  ui: form/CRSOptions: use view model for auto rebalancing option
  ui: form/CRSOptions: allow auto rebalancing only for static and
    dynamic mode

 www/manager6/form/CRSOptions.js | 37 +++++++++++++++++++++++----------
 1 file changed, 26 insertions(+), 11 deletions(-)


base-commit: 7ed516c3ebfd23c69603ce28c8c831cb0f97fa9d
prerequisite-patch-id: ac619ca623a091683b3e5137da27671e191184c1
prerequisite-patch-id: 395745226b8c099d6f931b7bc261d0a624efae90
prerequisite-patch-id: 6e78d3f10a15fa0bb6b87941975399dfdbb65500

docs:

Daniel Kral (14):
  ha-manager: crs: replace service term with HA resource
  ha-manager: crs: remove note about manual changes to datacenter config
  ha-manager: crs: improve introduction
  ha-manager: crs: introduce crs scheduling mode section
  ha-manager: crs: generalize the description for basic and static load
    modes
  ha-manager: crs: remove HA group config from scheduling points list
  ha-manager: crs: use impose instead of empose for rules description
  ha-manager: crs: use headings for the scheduling points
  ha-manager: crs: reword the rebalance on start scheduling point
  ha-manager: crs: add more information about rebalance on start in its
    section
  ha-manager: crs: change crs modes to include all active guests
  ha-manager: crs: add dynamic load scheduler section
  screenshots: update crs datacenter options screenshot
  ha-manager: crs: add load balancer section

 ha-manager.adoc                               | 206 ++++++++++++------
 .../screenshot/gui-datacenter-options-crs.png | Bin 16395 -> 34280 bytes
 2 files changed, 134 insertions(+), 72 deletions(-)


Summary over all repositories:
  3 files changed, 160 insertions(+), 83 deletions(-)

-- 
Generated by murpp 0.11.0

[PATCH manager v2 01/19] ui: form/CRSOptions: add missing edit modal title

[Daniel Kral]

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
Tested-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 www/manager6/form/CRSOptions.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/www/manager6/form/CRSOptions.js b/www/manager6/form/CRSOptions.js
index b5476bd5..1b363386 100644
--- a/www/manager6/form/CRSOptions.js
+++ b/www/manager6/form/CRSOptions.js
@@ -3,6 +3,7 @@ Ext.define('PVE.form.CRSOptions', {
     alias: 'widget.pveCRSOptions',
 
     width: 450,
+    subject: gettext('Cluster Resource Scheduling'),
     url: '/api2/extjs/cluster/options',
     onlineHelp: 'ha_manager_crs',
 
-- 
2.47.3

[PATCH manager v2 02/19] ui: form/CRSOptions: rename HA Scheduling to Scheduling Mode

[Daniel Kral]

The existing admin guide documentation refers to this as scheduling mode
without the prefix. The added 'mode' better describes what this option
controls about the cluster resource scheduler.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
Tested-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 www/manager6/form/CRSOptions.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/www/manager6/form/CRSOptions.js b/www/manager6/form/CRSOptions.js
index 1b363386..736256c7 100644
--- a/www/manager6/form/CRSOptions.js
+++ b/www/manager6/form/CRSOptions.js
@@ -33,7 +33,7 @@ Ext.define('PVE.form.CRSOptions', {
                 {
                     xtype: 'proxmoxKVComboBox',
                     name: 'ha',
-                    fieldLabel: gettext('HA Scheduling'),
+                    fieldLabel: gettext('Scheduling Mode'),
                     deleteEmpty: false,
                     value: '__default__',
                     comboItems: [
-- 
2.47.3

[PATCH manager v2 03/19] ui: form/CRSOptions: replace HA service term with HA resource

[Daniel Kral]

We prefer to use the term HA resource in new additions to the codebase.
As the 'Automatic Rebalance' option uses the new term already, rename it
for the already existing 'Rebalance on Start' option as well.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
Tested-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 www/manager6/form/CRSOptions.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/www/manager6/form/CRSOptions.js b/www/manager6/form/CRSOptions.js
index 736256c7..0d23ad39 100644
--- a/www/manager6/form/CRSOptions.js
+++ b/www/manager6/form/CRSOptions.js
@@ -49,7 +49,7 @@ Ext.define('PVE.form.CRSOptions', {
                     name: 'ha-rebalance-on-start',
                     fieldLabel: gettext('Rebalance on Start'),
                     boxLabel: gettext(
-                        'Use CRS to select the least loaded node when starting an HA service',
+                        'Use CRS to select the least loaded node when starting an HA resource',
                     ),
                     value: 0,
                 },
-- 
2.47.3

[PATCH manager v2 04/19] ui: form/CRSOptions: use view model for auto rebalancing option

[Daniel Kral]

This is in preparation to further constrain when auto rebalancing can be
enabled in a following patch.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
Tested-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 www/manager6/form/CRSOptions.js | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/www/manager6/form/CRSOptions.js b/www/manager6/form/CRSOptions.js
index 0d23ad39..3f3b4fea 100644
--- a/www/manager6/form/CRSOptions.js
+++ b/www/manager6/form/CRSOptions.js
@@ -17,7 +17,14 @@ Ext.define('PVE.form.CRSOptions', {
         });
     },
 
-    viewModel: {},
+    viewModel: {
+        data: {
+            autoRebalancing: 0,
+        },
+        formulas: {
+            autoRebalancingDisabled: (get) => !get('autoRebalancing'),
+        },
+    },
 
     items: [
         {
@@ -58,8 +65,9 @@ Ext.define('PVE.form.CRSOptions', {
                     name: 'ha-auto-rebalance',
                     fieldLabel: gettext('Automatic Rebalance'),
                     boxLabel: gettext('Automatically rebalance HA resources'),
-                    value: 0,
-                    reference: 'enableAutoRebalance',
+                    bind: {
+                        value: '{autoRebalancing}',
+                    },
                 },
                 {
                     xtype: 'numberfield',
@@ -69,7 +77,7 @@ Ext.define('PVE.form.CRSOptions', {
                     minValue: 0.0,
                     step: 0.01,
                     bind: {
-                        disabled: '{!enableAutoRebalance.checked}',
+                        disabled: '{autoRebalancingDisabled}',
                     },
                 },
                 {
@@ -85,7 +93,7 @@ Ext.define('PVE.form.CRSOptions', {
                     ],
                     defaultValue: '__default__',
                     bind: {
-                        disabled: '{!enableAutoRebalance.checked}',
+                        disabled: '{autoRebalancingDisabled}',
                     },
                 },
                 {
@@ -96,7 +104,7 @@ Ext.define('PVE.form.CRSOptions', {
                     minValue: 0,
                     step: 1,
                     bind: {
-                        disabled: '{!enableAutoRebalance.checked}',
+                        disabled: '{autoRebalancingDisabled}',
                     },
                 },
                 {
@@ -108,7 +116,7 @@ Ext.define('PVE.form.CRSOptions', {
                     maxValue: 1.0,
                     step: 0.01,
                     bind: {
-                        disabled: '{!enableAutoRebalance.checked}',
+                        disabled: '{autoRebalancingDisabled}',
                     },
                 },
             ],
-- 
2.47.3

[PATCH manager v2 05/19] ui: form/CRSOptions: allow auto rebalancing only for static and dynamic mode

[Daniel Kral]

The HA auto rebalancing system can only be used with the static and
dynamic load usage information, so constrain the web interface
accordingly.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
Tested-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

I stuck with not removing the contents from the disabled fields as we're
not really consistent whether we do this, but most of the time let it
stay in the fields. Also user would be rather frustrated if their
previously set values would be removed if they changed the scheduling
mode from 'static'/'dynamic' to 'basic'. Another idea is to always
preserve these values, even though this doesn't clue in the users what
configuration is valid in the end. But let's see what users think.

 www/manager6/form/CRSOptions.js | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/www/manager6/form/CRSOptions.js b/www/manager6/form/CRSOptions.js
index 3f3b4fea..3b539fda 100644
--- a/www/manager6/form/CRSOptions.js
+++ b/www/manager6/form/CRSOptions.js
@@ -19,10 +19,14 @@ Ext.define('PVE.form.CRSOptions', {
 
     viewModel: {
         data: {
+            crsMode: '__default__',
             autoRebalancing: 0,
         },
         formulas: {
-            autoRebalancingDisabled: (get) => !get('autoRebalancing'),
+            canUseAutoRebalancing: (get) =>
+                get('crsMode') === 'static' || get('crsMode') === 'dynamic',
+            autoRebalancingDisabled: (get) =>
+                !get('autoRebalancing') || !get('canUseAutoRebalancing'),
         },
     },
 
@@ -42,14 +46,15 @@ Ext.define('PVE.form.CRSOptions', {
                     name: 'ha',
                     fieldLabel: gettext('Scheduling Mode'),
                     deleteEmpty: false,
-                    value: '__default__',
                     comboItems: [
                         ['__default__', Proxmox.Utils.defaultText + ' (basic)'],
                         ['basic', gettext('Basic (Resource Count)')],
                         ['static', gettext('Static Load')],
                         ['dynamic', gettext('Dynamic Load')],
                     ],
-                    defaultValue: '__default__',
+                    bind: {
+                        value: '{crsMode}',
+                    },
                 },
                 {
                     xtype: 'proxmoxcheckbox',
@@ -67,6 +72,7 @@ Ext.define('PVE.form.CRSOptions', {
                     boxLabel: gettext('Automatically rebalance HA resources'),
                     bind: {
                         value: '{autoRebalancing}',
+                        disabled: '{!canUseAutoRebalancing}',
                     },
                 },
                 {
-- 
2.47.3

[PATCH docs v2 06/19] ha-manager: crs: replace service term with HA resource

[Daniel Kral]

'HA resource' is the preferred term for the HA-managed guests instead of
'service' and prefixing them with 'HA' makes the distinction between
HA-managed and HA-unmanaged resources clearer.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 ha-manager.adoc | 53 +++++++++++++++++++++++++------------------------
 1 file changed, 27 insertions(+), 26 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index a1b2210..aa2d362 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1426,9 +1426,9 @@ crs: ha=static
 The change will be in effect starting with the next manager round (after a few
 seconds).
 
-For each service that needs to be recovered or migrated, the scheduler
+For each HA resource that needs to be recovered or migrated, the scheduler
 iteratively chooses the best node among the nodes that are available to
-the service according to their HA rules, if any.
+the HA resource according to their HA rules, if any.
 
 NOTE: There are plans to add modes for (static and dynamic) load-balancing in
 the future.
@@ -1436,18 +1436,18 @@ the future.
 Basic Scheduler
 ~~~~~~~~~~~~~~~
 
-The number of active HA services on each node is used to choose a recovery node.
-Non-HA-managed services are currently not counted.
+The number of active HA resources on each node is used to choose a recovery
+node. Non-HA-managed resources are currently not counted.
 
 Static-Load Scheduler
 ~~~~~~~~~~~~~~~~~~~~~
 
 IMPORTANT: The static mode is still a technology preview.
 
-Static usage information from HA services on each node is used to choose a
-recovery node. Usage of non-HA-managed services is currently not considered.
+Static usage information from HA resources on each node is used to choose a
+recovery node. Usage of non-HA-managed resources is currently not considered.
 
-For this selection, each node in turn is considered as if the service was
+For this selection, each node in turn is considered as if the HA resource was
 already running on it, using CPU and memory usage from the associated guest
 configuration. Then for each such alternative, CPU and memory usage of all nodes
 are considered, with memory being weighted much more, because it's a truly
@@ -1456,29 +1456,29 @@ more, as ideally no node should be overcommitted) and average usage of all nodes
 (to still be able to distinguish in case there already is a more highly
 committed node) are considered.
 
-IMPORTANT: The more services the more possible combinations there are, so it's
-currently not recommended to use it if you have thousands of HA managed
-services.
+IMPORTANT: The more HA resources the more possible combinations there are, so
+it's currently not recommended to use it if you have thousands of HA resources.
 
 
 CRS Scheduling Points
 ~~~~~~~~~~~~~~~~~~~~~
 
-The CRS algorithm is not applied for every service in every round, since this
-would mean a large number of constant migrations. Depending on the workload,
-this could put more strain on the cluster than could be avoided by constant
-balancing.
-That's why the {pve} HA manager favors keeping services on their current node.
+The CRS algorithm is not applied for every HA resource in every round, since
+this would mean a large number of constant migrations. Depending on the
+workload, this could put more strain on the cluster than could be avoided by
+constant balancing.
+That's why the {pve} HA manager favors keeping HA resources on their current
+node.
 
 The CRS is currently used at the following scheduling points:
 
-- Service recovery (always active). When a node with active HA services fails,
-  all its services need to be recovered to other nodes. The CRS algorithm will
-  be used here to balance that recovery over the remaining nodes.
+- HA resource recovery (always active). When a node with active HA resources
+  fails, all its HA resources need to be recovered to other nodes. The CRS
+  algorithm will be used here to balance that recovery over the remaining nodes.
 
 - HA group config changes (always active). If a node is removed from a group,
   or its priority is reduced, the HA stack will use the CRS algorithm to find a
-  new target node for the HA services in that group, matching the adapted
+  new target node for the HA resources in that group, matching the adapted
   priority constraints.
 
 - HA rule config changes (always active). If a rule emposes different
@@ -1501,13 +1501,14 @@ The CRS is currently used at the following scheduling points:
    rule, the HA stack will use the CRS algorithm to ensure that these HA
    resources are moved to separate nodes.
 
-- HA service stopped -> start transition (opt-in). Requesting that a stopped
-  service should be started is an good opportunity to check for the best suited
-  node as per the CRS algorithm, as moving stopped services is  cheaper to do
-  than moving them started, especially if their disk volumes reside on shared
-  storage. You can enable this by setting the **`ha-rebalance-on-start`**
-  CRS option in the datacenter config. You can change that option also in the
-  Web UI, under `Datacenter` -> `Options` -> `Cluster Resource Scheduling`.
+- HA resources stopped -> start transition (opt-in). Requesting that a stopped
+  HA resource should be started is an good opportunity to check for the best
+  suited node as per the CRS algorithm, as moving stopped HA resources is
+  cheaper to do than moving them started, especially if their disk volumes
+  reside on shared storage. You can enable this by setting the
+  **`ha-rebalance-on-start`** CRS option in the datacenter config. You can
+  change that option also in the Web UI, under `Datacenter` -> `Options` ->
+  `Cluster Resource Scheduling`.
 
 ifdef::manvolnum[]
 include::pve-copyright.adoc[]
-- 
2.47.3

[PATCH docs v2 07/19] ha-manager: crs: remove note about manual changes to datacenter config

[Daniel Kral]

It is generally discouraged to change the datacenter configuration
manually, so it should not be mentioned in the admin guide.

If there is a CLI utility to change these options in the future it can
be added here.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

I didn't go for adding the pvesh command after all since it hindered
simplifying the paragraph's flow in the following patches, especially
with adding additional text about that the option also controls the
functionality described in other chapters... And as mentioned by
Shannon, users that really want to change it that way probably will
already figure it out through the API viewer documentation.

 ha-manager.adoc | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index aa2d362..07f6958 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1415,11 +1415,7 @@ Cluster Resource Scheduling
 The cluster resource scheduler (CRS) mode controls how HA selects nodes for the
 recovery of a service as well as for migrations that are triggered by a
 shutdown policy. The default mode is `basic`, you can change it in the Web UI
-(`Datacenter` -> `Options`), or directly in `datacenter.cfg`:
-
-----
-crs: ha=static
-----
+(`Datacenter` -> `Options`).
 
 [thumbnail="screenshot/gui-datacenter-options-crs.png"]
 
-- 
2.47.3

[PATCH docs v2 08/19] ha-manager: crs: improve introduction

[Daniel Kral]

Add some lighter introductory paragraphs, which introduce the
responsibilities of the CRS and a general overview of how it operates.

The previous introductory CRS section focuses on only a handful of
scenarios where the CRS takes some action, but there are many more
scenarios, which are already listed in the "CRS Scheduling Points"
section below, so link to the section directly.

Furthermore, the CRS mode paragraph does focus only on the detail that
the mode changes which usage information the HA Manager will work with,
but not how the CRS operates itself.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 ha-manager.adoc | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index 07f6958..7c7b1d5 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1412,19 +1412,25 @@ cluster is in a healthy state before re-arming.
 Cluster Resource Scheduling
 ---------------------------
 
-The cluster resource scheduler (CRS) mode controls how HA selects nodes for the
-recovery of a service as well as for migrations that are triggered by a
-shutdown policy. The default mode is `basic`, you can change it in the Web UI
-(`Datacenter` -> `Options`).
+The Cluster Resource Scheduler (CRS) is responsible for selecting new node
+placements for HA resources and keeping HA resources on their allowed nodes.
+
+In every HA Manager round, the scheduler goes through every HA resource and
+checks whether the HA resource needs any new node placement. This new node
+placement can be caused by different actions, such as recovering HA resources
+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, which actions the CRS takes for specific changes in the
+cluster.
 
 [thumbnail="screenshot/gui-datacenter-options-crs.png"]
 
-The change will be in effect starting with the next manager round (after a few
-seconds).
-
-For each HA resource that needs to be recovered or migrated, the scheduler
-iteratively chooses the best node among the nodes that are available to
-the HA resource according to their HA rules, if any.
+The CRS scheduling mode controls how the CRS will calculate the usage
+information for the cluster. This usage information is used as a basis for the
+scheduling decisions. The CRS mode can be changed in the web interface
+(`Datacenter` -> `Options` -> `Cluster Resource Scheduling`). The default mode
+is `basic`. The change will take effect starting with the next HA Manager
+round, which should take no longer than 10 seconds.
 
 NOTE: There are plans to add modes for (static and dynamic) load-balancing in
 the future.
@@ -1455,18 +1461,12 @@ committed node) are considered.
 IMPORTANT: The more HA resources the more possible combinations there are, so
 it's currently not recommended to use it if you have thousands of HA resources.
 
-
+[[ha_manager_crs_scheduling_points]]
 CRS Scheduling Points
 ~~~~~~~~~~~~~~~~~~~~~
 
-The CRS algorithm is not applied for every HA resource in every round, since
-this would mean a large number of constant migrations. Depending on the
-workload, this could put more strain on the cluster than could be avoided by
-constant balancing.
-That's why the {pve} HA manager favors keeping HA resources on their current
-node.
-
-The CRS is currently used at the following scheduling points:
+In every HA Manager round, the CRS checks whether any HA resources need a new
+node placement, which can be caused by any of the following scheduling points:
 
 - HA resource recovery (always active). When a node with active HA resources
   fails, all its HA resources need to be recovered to other nodes. The CRS
-- 
2.47.3

[PATCH docs v2 09/19] ha-manager: crs: introduce crs scheduling mode section

[Daniel Kral]

Move the existing section regarding the different scheduling modes its
own section so that it is more easily distinguishable from the
introductory paragraphs and the rest of the subchapter's description.

The permalinks for the basic and static-load scheduler headings remains
the same here.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 ha-manager.adoc | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index 7c7b1d5..b7e0d9b 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1423,6 +1423,9 @@ xref:ha_manager_crs_scheduling_points[CRS Scheduling Points] for a more
 thorough description, which actions the CRS takes for specific changes in the
 cluster.
 
+CRS Scheduling Mode
+~~~~~~~~~~~~~~~~~~~
+
 [thumbnail="screenshot/gui-datacenter-options-crs.png"]
 
 The CRS scheduling mode controls how the CRS will calculate the usage
@@ -1436,13 +1439,13 @@ NOTE: There are plans to add modes for (static and dynamic) load-balancing in
 the future.
 
 Basic Scheduler
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 The number of active HA resources on each node is used to choose a recovery
 node. Non-HA-managed resources are currently not counted.
 
 Static-Load Scheduler
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
 
 IMPORTANT: The static mode is still a technology preview.
 
-- 
2.47.3

[PATCH docs v2 10/19] ha-manager: crs: generalize the description for basic and static load modes

[Daniel Kral]

The CRS mode does choose the best-fitting node for HA resources in many
more scenarios than just HA resource recovery. Therefore, make the text
reflect this behavior better.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 ha-manager.adoc | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index b7e0d9b..d7412f2 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1441,16 +1441,19 @@ the future.
 Basic Scheduler
 ^^^^^^^^^^^^^^^
 
-The number of active HA resources on each node is used to choose a recovery
-node. Non-HA-managed resources are currently not counted.
+The number of active HA resources on each node is used to choose the
+best-fitting node for an HA resource. Non-HA-managed resources are currently
+not counted.
 
 Static-Load Scheduler
 ^^^^^^^^^^^^^^^^^^^^^
 
 IMPORTANT: The static mode is still a technology preview.
 
-Static usage information from HA resources on each node is used to choose a
-recovery node. Usage of non-HA-managed resources is currently not considered.
+Static usage information from HA resources on each node is used to choose the
+best-fitting node for an HA resource. This includes the configured CPU and
+memory quotas for the HA resources. Usage of non-HA-managed resources is
+currently not considered.
 
 For this selection, each node in turn is considered as if the HA resource was
 already running on it, using CPU and memory usage from the associated guest
-- 
2.47.3

[PATCH docs v2 11/19] ha-manager: crs: remove HA group config from scheduling points list

[Daniel Kral]

For Proxmox VE 9 and onwards, HA groups are deprecated and automatically
migrated to HA node affinity rules. This is already noted for the still
existing HA group section, such that referencing here is only duplicate
and outdated information.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 ha-manager.adoc | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index d7412f2..716e77e 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1478,11 +1478,6 @@ node placement, which can be caused by any of the following scheduling points:
   fails, all its HA resources need to be recovered to other nodes. The CRS
   algorithm will be used here to balance that recovery over the remaining nodes.
 
-- HA group config changes (always active). If a node is removed from a group,
-  or its priority is reduced, the HA stack will use the CRS algorithm to find a
-  new target node for the HA resources in that group, matching the adapted
-  priority constraints.
-
 - HA rule config changes (always active). If a rule emposes different
   constraints on the HA resources, the HA stack will use the CRS algorithm to
   find a new target node for the HA resources affected by these rules depending
-- 
2.47.3

[PATCH docs v2 12/19] ha-manager: crs: use impose instead of empose for rules description

[Daniel Kral]

Suggested-by: Michael Köppl <m.koeppl@proxmox.com>
Signed-off-by: Daniel Kral <d.kral@proxmox.com>
---
changes v1 -> v2:
- new! as suggested by Michael

 ha-manager.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index 716e77e..5561390 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1478,7 +1478,7 @@ node placement, which can be caused by any of the following scheduling points:
   fails, all its HA resources need to be recovered to other nodes. The CRS
   algorithm will be used here to balance that recovery over the remaining nodes.
 
-- HA rule config changes (always active). If a rule emposes different
+- HA rule config changes (always active). If a rule imposes different
   constraints on the HA resources, the HA stack will use the CRS algorithm to
   find a new target node for the HA resources affected by these rules depending
   on the type of the new rules:
-- 
2.47.3

[PATCH docs v2 13/19] ha-manager: crs: use headings for the scheduling points

[Daniel Kral]

This is in preparation to be able to extend the existing entries with
more information and allows users to make permalinks to the specific
scheduling points.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 ha-manager.adoc | 61 +++++++++++++++++++++++++++----------------------
 1 file changed, 34 insertions(+), 27 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index 5561390..d69d8a0 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1474,38 +1474,45 @@ CRS Scheduling Points
 In every HA Manager round, the CRS checks whether any HA resources need a new
 node placement, which can be caused by any of the following scheduling points:
 
-- HA resource recovery (always active). When a node with active HA resources
-  fails, all its HA resources need to be recovered to other nodes. The CRS
-  algorithm will be used here to balance that recovery over the remaining nodes.
+HA resource recovery (always active)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- HA rule config changes (always active). If a rule imposes different
-  constraints on the HA resources, the HA stack will use the CRS algorithm to
-  find a new target node for the HA resources affected by these rules depending
-  on the type of the new rules:
+When a node with active HA resources fails, all its HA resources need to be
+recovered to other nodes. The CRS algorithm will be used here to balance that
+recovery over the remaining nodes.
 
-** Node affinity rules: If a node affinity rule is created or HA resources/nodes
-   are added to an existing node affinity rule, the HA stack will use the CRS
-   algorithm to ensure that these HA resources are assigned according to their
-   node and priority constraints.
+HA rule config changes (always active)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-** Positive resource affinity rules: If a positive resource affinity rule is
-   created or HA resources are added to an existing positive resource affinity
-   rule, the HA stack will use the CRS algorithm to ensure that these HA
-   resources are moved to a common node.
+If a rule imposes different constraints on the HA resources, the HA stack will
+use the CRS algorithm to find a new target node for the HA resources affected
+by these rules depending on the type of the new rules:
 
-** Negative resource affinity rules: If a negative resource affinity rule is
-   created or HA resources are added to an existing negative resource affinity
-   rule, the HA stack will use the CRS algorithm to ensure that these HA
-   resources are moved to separate nodes.
+- Node affinity rules: If a node affinity rule is created or HA resources/nodes
+  are added to an existing node affinity rule, the HA stack will use the CRS
+  algorithm to ensure that these HA resources are assigned according to their
+  node and priority constraints.
 
-- HA resources stopped -> start transition (opt-in). Requesting that a stopped
-  HA resource should be started is an good opportunity to check for the best
-  suited node as per the CRS algorithm, as moving stopped HA resources is
-  cheaper to do than moving them started, especially if their disk volumes
-  reside on shared storage. You can enable this by setting the
-  **`ha-rebalance-on-start`** CRS option in the datacenter config. You can
-  change that option also in the Web UI, under `Datacenter` -> `Options` ->
-  `Cluster Resource Scheduling`.
+- Positive resource affinity rules: If a positive resource affinity rule is
+  created or HA resources are added to an existing positive resource affinity
+  rule, the HA stack will use the CRS algorithm to ensure that these HA
+  resources are moved to a common node.
+
+- Negative resource affinity rules: If a negative resource affinity rule is
+  created or HA resources are added to an existing negative resource affinity
+  rule, the HA stack will use the CRS algorithm to ensure that these HA
+  resources are moved to separate nodes.
+
+HA resources stopped -> start transition (opt-in)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Requesting that a stopped HA resource should be started is an good opportunity
+to check for the best suited node as per the CRS algorithm, as moving stopped
+HA resources is cheaper to do than moving them started, especially if their
+disk volumes reside on shared storage. You can enable this by setting the
+**`ha-rebalance-on-start`** CRS option in the datacenter config. You can change
+that option also in the Web UI, under `Datacenter` -> `Options` -> `Cluster
+Resource Scheduling`.
 
 ifdef::manvolnum[]
 include::pve-copyright.adoc[]
-- 
2.47.3

[PATCH docs v2 14/19] ha-manager: crs: reword the rebalance on start scheduling point

[Daniel Kral]

Make the action, which the CRS takes in the transition from the stopped
to request_start state, more apparent in the heading as well describe
what it does achieve in its description.

The crs option is not stylized as bold anymore, because it distracts
from the rest of the text and is already highlighted by the different
color as well as the use of a monospaced font.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- s/migrate/migrated/ as suggested by Michael

 ha-manager.adoc | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index d69d8a0..878815d 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1503,16 +1503,15 @@ by these rules depending on the type of the new rules:
   rule, the HA stack will use the CRS algorithm to ensure that these HA
   resources are moved to separate nodes.
 
-HA resources stopped -> start transition (opt-in)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+HA resource rebalance on start (opt-in)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Requesting that a stopped HA resource should be started is an good opportunity
-to check for the best suited node as per the CRS algorithm, as moving stopped
-HA resources is cheaper to do than moving them started, especially if their
-disk volumes reside on shared storage. You can enable this by setting the
-**`ha-rebalance-on-start`** CRS option in the datacenter config. You can change
-that option also in the Web UI, under `Datacenter` -> `Options` -> `Cluster
-Resource Scheduling`.
+When starting an HA resource with rebalance on start enabled, the CRS will
+select the node best suited for the HA resource. If the selected node is not
+the current node, the HA resource will be migrated to the selected node.
+
+This setting can be enabled with the CRS option `ha-rebalance-on-start` in the
+web interface under `Datacenter` -> `Options` -> `Cluster Resource Scheduling`.
 
 ifdef::manvolnum[]
 include::pve-copyright.adoc[]
-- 
2.47.3

[PATCH docs v2 15/19] ha-manager: crs: add more information about rebalance on start in its section

[Daniel Kral]

The information which node is considered as the best suited for an HA
resource was only described in the static-load scheduler section.

To define it both, add the description for the basic load scheduler and
move the description from the static-load scheduler section to the
description of the HA resource rebalance on start section.

The important notice about the technology preview is merged and also
moved to the rebalance-on-start section, as the technology preview only
really applies to this functionality instead of the whole static-load
scheduler mode.

The link macros for the scheduler modes are needed for the references in
the new paragraphs and are the same as the ones, which were previously
auto-generated.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 ha-manager.adoc | 34 ++++++++++++++++++++--------------
 1 file changed, 20 insertions(+), 14 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index 878815d..541b8b0 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1438,6 +1438,7 @@ round, which should take no longer than 10 seconds.
 NOTE: There are plans to add modes for (static and dynamic) load-balancing in
 the future.
 
+[[_basic_scheduler]]
 Basic Scheduler
 ^^^^^^^^^^^^^^^
 
@@ -1445,28 +1446,15 @@ The number of active HA resources on each node is used to choose the
 best-fitting node for an HA resource. Non-HA-managed resources are currently
 not counted.
 
+[[_static_scheduler]]
 Static-Load Scheduler
 ^^^^^^^^^^^^^^^^^^^^^
 
-IMPORTANT: The static mode is still a technology preview.
-
 Static usage information from HA resources on each node is used to choose the
 best-fitting node for an HA resource. This includes the configured CPU and
 memory quotas for the HA resources. Usage of non-HA-managed resources is
 currently not considered.
 
-For this selection, each node in turn is considered as if the HA resource was
-already running on it, using CPU and memory usage from the associated guest
-configuration. Then for each such alternative, CPU and memory usage of all nodes
-are considered, with memory being weighted much more, because it's a truly
-limited resource. For both, CPU and memory, highest usage among nodes (weighted
-more, as ideally no node should be overcommitted) and average usage of all nodes
-(to still be able to distinguish in case there already is a more highly
-committed node) are considered.
-
-IMPORTANT: The more HA resources the more possible combinations there are, so
-it's currently not recommended to use it if you have thousands of HA resources.
-
 [[ha_manager_crs_scheduling_points]]
 CRS Scheduling Points
 ~~~~~~~~~~~~~~~~~~~~~
@@ -1510,9 +1498,27 @@ When starting an HA resource with rebalance on start enabled, the CRS will
 select the node best suited for the HA resource. If the selected node is not
 the current node, the HA resource will be migrated to the selected node.
 
+For the xref:_basic_scheduler[basic scheduler mode], the node with the least
+resources count is considered as the best suited node.
+
+For the xref:_static_scheduler[static-load scheduler mode], each node in turn
+is considered as if the HA resource was already running on it, using CPU and
+memory usage from the associated guest configuration. Then for each such
+alternative, CPU and memory usage of all nodes are considered, with memory
+being weighted much more, because it's a truly limited resource. For both, CPU
+and memory, highest usage among nodes (weighted more, as ideally no node should
+be overcommitted) and average usage of all nodes (to still be able to
+distinguish in case there already is a more highly committed node) are
+considered.
+
 This setting can be enabled with the CRS option `ha-rebalance-on-start` in the
 web interface under `Datacenter` -> `Options` -> `Cluster Resource Scheduling`.
 
+IMPORTANT: For the static-load scheduler mode, this functionality is still in
+technology preview. The more HA resources the more possible combinations there
+are, so it's currently not recommended to use it if you have thousands of HA
+resources.
+
 ifdef::manvolnum[]
 include::pve-copyright.adoc[]
 endif::manvolnum[]
-- 
2.47.3

[PATCH docs v2 16/19] ha-manager: crs: change crs modes to include all active guests

[Daniel Kral]

For pve-ha-manager >= 5.1.2, the HA Manager considers all running guests
in the scheduler's accounting instead of only the HA resources.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 ha-manager.adoc | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index 541b8b0..c5c7f20 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1442,18 +1442,16 @@ the future.
 Basic Scheduler
 ^^^^^^^^^^^^^^^
 
-The number of active HA resources on each node is used to choose the
-best-fitting node for an HA resource. Non-HA-managed resources are currently
-not counted.
+The number of active guests on each node is used to choose the best-fitting
+node for an HA resource.
 
 [[_static_scheduler]]
 Static-Load Scheduler
 ^^^^^^^^^^^^^^^^^^^^^
 
-Static usage information from HA resources on each node is used to choose the
+Static usage information from active guests on each node is used to choose the
 best-fitting node for an HA resource. This includes the configured CPU and
-memory quotas for the HA resources. Usage of non-HA-managed resources is
-currently not considered.
+memory quotas for the active guests.
 
 [[ha_manager_crs_scheduling_points]]
 CRS Scheduling Points
-- 
2.47.3

[PATCH docs v2 17/19] ha-manager: crs: add dynamic load scheduler section

[Daniel Kral]

For pve-ha-manager >= 5.2.0, the HA Manager also has a dynamic-load
scheduler mode.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- add 'section' to the end of the patch subject

 ha-manager.adoc | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index c5c7f20..0421b86 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1453,6 +1453,14 @@ Static usage information from active guests on each node is used to choose the
 best-fitting node for an HA resource. This includes the configured CPU and
 memory quotas for the active guests.
 
+[[_dynamic_scheduler]]
+Dynamic-Load Scheduler
+^^^^^^^^^^^^^^^^^^^^^^
+
+Dynamic usage information from active guests on each node is used to choose the
+best-fitting node for an HA resource. This includes the average CPU and memory
+usage as well as the configured CPU and memory quotas for the active guests.
+
 [[ha_manager_crs_scheduling_points]]
 CRS Scheduling Points
 ~~~~~~~~~~~~~~~~~~~~~
@@ -1499,8 +1507,9 @@ the current node, the HA resource will be migrated to the selected node.
 For the xref:_basic_scheduler[basic scheduler mode], the node with the least
 resources count is considered as the best suited node.
 
-For the xref:_static_scheduler[static-load scheduler mode], each node in turn
-is considered as if the HA resource was already running on it, using CPU and
+For the xref:_static_scheduler[static] and
+xref:_dynamic_scheduler[dynamic-load scheduler mode], each node in turn is
+considered as if the HA resource was already running on it, using CPU and
 memory usage from the associated guest configuration. Then for each such
 alternative, CPU and memory usage of all nodes are considered, with memory
 being weighted much more, because it's a truly limited resource. For both, CPU
@@ -1512,10 +1521,10 @@ considered.
 This setting can be enabled with the CRS option `ha-rebalance-on-start` in the
 web interface under `Datacenter` -> `Options` -> `Cluster Resource Scheduling`.
 
-IMPORTANT: For the static-load scheduler mode, this functionality is still in
-technology preview. The more HA resources the more possible combinations there
-are, so it's currently not recommended to use it if you have thousands of HA
-resources.
+IMPORTANT: For the static-load and dynamic-load scheduler mode, this
+functionality is still in technology preview. The more HA resources the more
+possible combinations there are, so it's currently not recommended to use it if
+you have thousands of HA resources.
 
 ifdef::manvolnum[]
 include::pve-copyright.adoc[]
-- 
2.47.3

[PATCH docs v2 18/19] screenshots: update crs datacenter options screenshot

[Daniel Kral]

Update the screenshot to show the selected Dynamic-Load scheduler mode
with the new automatic rebalancing system options.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
---
changes v1 -> v2:
- none

 .../screenshot/gui-datacenter-options-crs.png | Bin 16395 -> 34280 bytes
 1 file changed, 0 insertions(+), 0 deletions(-)

diff --git a/images/screenshot/gui-datacenter-options-crs.png b/images/screenshot/gui-datacenter-options-crs.png
index 402c1912db028c8966461903ffe2f79d91de154a..15f67a060cd5d21a91ef0a094acc676678875ce8 100644
GIT binary patch
literal 34280
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%0D_om6C
zM2O7rr9M>&kpC}$n|ewtZ+^6LEt2Z!?<Yl>J)oF!b2-6@H#Rp1qu~I*F5o<)l$W3H
z=<J;8IN20N!S`x#4aOt9ySv-iORjC&Dd-eU&icr!=x9<{Ss5@KE-;?h(RbfmVmwBk
zGRWN9-yA@ZS=j1`XuyqG9)K%BZ4$3NKF7Z8hI`@GYaAF@n6In3TKNu+jz(ZJ8Z+{>
z3u$2#Ou);5V?@Wcuy!L_O<{I_Y*@-YK6g9(S}6Tl)eQCQlKWW&S@&TLV8^Ny0n_~h
z7E&zxGKx%FiGdSy-rf620mATSxxYt!eSMs;qj9)b5;vF)l-#$q_&Ij1=-l}9jfizQ
zqwpv92JSMWz>x30XSS6K5Hd;;#gj@=0^K2K*?ToJF`ot1xyA`u#~cr+!<Ro79c^f7
z+3K}i6$}cFBRZtg_1oIku)Vf>QDAIC-9!9PpRn=dJW!1A@wCcNhU1OI{;wl-K$zQz
zCeuG_tgCx9IIH!u6?TQrs4P(+@uPq3?$V#NBF*W|oJfDXu9%TFnFvJ`m{z|BqDH3l
zzmM1I|1}?UPKX2Z`sx$75=ZK*Wi~Q@wR<W1efpJLa1G5k{JSUy`&ap+L%#wQ<mw;;
zj-95(dudSP+hY30BJxT3c@)XezYau-UbS=O%9X>oxXHK0e_wzn0dzQuG=q;vRc>){
zaS6hX6LC|T*^<I0O$1=WLzR**+0)K;CG$A%Ag%!4Wjx#1(7<cb6lOeY3w}jDibeh>
zN-!=gTy~~j^7@o_8*J`e#T4_irBC^HknZV{_?ckV9&?6_Olwq@7%$~y!WFL=nE4;u
z%RI{8zSKy_%ge)$-nOlK&0~*?y3Ey<eerEa|J599@(5B9hLUkHva)8jtyemX9|i#J
zogL8kBDA*twlH?&@JsdV!E(p*dX+BYQL5r8V9-$Ueedwp5vh9~%uGzYhP60TP8EX6
z+_3`ie~F2SLDI%@6D@rEW@2t06c<Mct3)YY@WlD^sVBeiTmQ-p&9;0~T<nUyI9zJY
z8kFlPb@l31Lt9&ASf_jf0`<s>4-O74aL3ahSG5GA0IvINoSmUzEkIkYSdGOeYe5h~
zsFH1ULKYC#vgg$iKt7Na*ID(<%~_}~*-e3d0LcssPb<aSl%JAD#N{hkJ4C)PE2sjF
zML8Z%67(<Xyt%p156*2B#LD`Rbzzamx;aSk5G58ADMT${)Yy<`he;WS%c8z#7>pQL
zk@r)rQE^wiE=IAc!rzOGR5%BNl0QR36P};XRUdr1xxOBkEsGKR7u{82+XT$o&azjj
zIl_0FfSKu?g((Az`?|O|7yIf&z)EDc3q49nRZOe_>VR$B4u}te9OakWj8;aMjd?1v
z>KVCyA~*1s0{3bCDKFdMwvCOAFo>9nUUPGEVk)XOxF;A=lh#OPVNp>5-@SXieSN4I
zDVI(O>KjWyC$7tyMW&#t`m5ICW7Z8+s0AQb?73+*^WjA>JO~bO-QKLkPbrqD)taCC
zPXN&P?yVSt97AohTtQF7+rJLt7Zhyh?tTjVjDl#!CMM|AD<dPLUk{zd@kgHuME)KC
zQ>2fKNB_dU4|e1-i_&v?y_6^CE=Ph4U!QqluVDFSwf*~mBkIG$V4??M1_g!<K@Gq^
zfL(A6_r9;*($RTUSoj2lWJ3d9w1Vb>2<rFf=9XbSP#`H4J^v7&{P@X}kyP%Yt_y(x
z!#H3Km|*=G26LWund=^pvo%mgrHwVd`{f?%EMU890q?1)Uo3FPz`l)8I3^7`pZ)n+
z4x7P_t}a$CF6Bzm!!R@Fd3aP$9>>Yf&hEuXKYsj}lv`0<UA;opmp_gGm~P%#L*s09
zb+xIvxv_<Xw)r~-Nd<+F&bOp?GEPo!Ha?>&{=__@Wv(o%&!0cHnDP@45?X%DI)iKj
zBVzyzyCOMT06ivQZ+{;U!#=`I8Xg=pMlL3CCC(+L=U3shbf&v1C=jO#-OPoy-d^H3
zB{^?zjNsC$p}Iafx9&@T`QF*RJ@5Ht*bj*)U(8d~Um+bevqfj{h1EYoP)|vFdjoS{
zbO7SX4cqvo28Zj~nWRLRBvfXcXsM7+T&kltDocVl&JKhh3V!$7$n(2`R49EdU#B$Z
z*FG$P#el?2L&H_n_vo!HHOjqGU0%Mhxw#29LijuW1!k%l6sDq{y`3F5Y83;E^UN9l
z!a^SShdL|u&6_vt>gxUo4LuKn|NOPb&&mt_BG)M2nV$<=6sDE0bLPyM_i+LiEuEc6
z9-y|CpcVPI74`LLrKF^KM_;R5R*n}OhXsrZ%SJ|YQ6edb#k)ZIuH?!@ftgdkthf+t
z%ia=j@WAJ*Yil`cdr7wwM{^6S+rZ}EdSiNmDm*BL>khxw$1KKq)TtD8#{qwe&IRVW
zQ_%KgF4%@2^vdkc%*>#GgsQ~8M&(1h&u^H^>_#VE*jIyQ>;WA^oXcWsWAkshIXzi7
z&QtwYod}4@sF>ovICW63@VsDdVS(DTJY&D<f~9{L0t?<8HY^?<9t>|Vco@K^6mZSI
zc3h4me7&&eM%G5b4HA;5lM<S0un85?xjL>A=`#WK8yo6NWxeNE?_CN>xOCE>mci5U
zI3g`3V6nu3yeq}tIbJeH{^JYZMB0z@lstX<^j8<|pAHkNCw>=fcza9#nN0IPZ1nxF
zzmB!T=ee+2XNw42GgpgL!C+kSd2DR+H9DWb&`|tjpRKq~)O#EBFt4DXDS#g8@7&$3
zCcd{)uRcIYLQ+4`7z*&`;kqn=16Dxk`t{?WXmh%qz^pd{d@;xbX$W_r#?j!2M@B|+
zyw(laNUyv+B9---!}*ZjylCC;06qxyh(BZa;VCH$I9M!paCkVjf;(Nkb+E`J*C-af
zSx-nWefT)_KZnvU_`EGEYaSh~>TpG#V}Abj=&m#pHU1nv*9O5%p!PMKg_y%A&b>C>
zj<OcvJ8^(u8vAp#cUJ08|4q>VF&!PsutxCye^nOo6{rYBbU|YrLcIxK*ltyM3Q<y0
zg8sY@D+%RoC@CpX2w9zth=@P|cK|ui#8=y6xD-b_OG-*k=CcY2M8R#Lh!@Jp;WNeq
zA%EoSpBX0Q<-#2wJ|OioHZ~@^hWc*(E2T<t$D;aM__GSPC90mDo?CbBtb@crhh)G8
zD6a?wb!%(ygV;q91K6C8j}M)_fu}^L@SvMNytq_|om7S8H>COFarfvbN;g!$dGioz
zY6&a^hBKxd%{GXU3wo8$q#hg{pPjv?udg5BGEiucY0;JBz5d}6C<c_^BI1tifPuV`
z+kftgXNj(vlB(*p6t$J5vM;^aH(62NCx9k=a_+PnsdAtOQriZc*QVrAQXuNRnW>V9
zx=UY|muC<aeE~DH*2Y=*`rfKBDyafUYHe%di2M>nNc|et0oV$-e-dJ1>AQEc1b?oK
z*P}L>sE{b#ZnRSUK-3+JPJWQ}ctpaA0+`$e)gZjN+hch$0bo&2D8RlqcB3NTi@$3e
zdx8}4v*ct|Nl6?)x4Wf77BQ;nxGB}u;y?gVR4g*m(syCuX17zo>RVb0mrg+m=>Y5?
z$wJedot$35)`H*ly)jeN)zw{DS*iWqWe}8Ln_edXRVr{V_+<XLFu-&ZL&N)-nVEtj
zj+zCTV9M@!dK#OX%N6QZIXF2@!1|s0_6?OGfR_n;^ymZ`85vGvj1iD{7`Vf9b(FKp
z!onglyoklB?El#0<L9qyZ&!?WM}{Vh!XMZhrVJejgH0r&qCzGa9oN7ufhtDL5j&G5
z3_cec5aEr-iMlOPczSw*R{`h#y<^QIr<oO{)E1dEqr@ygJ=8oOgbQ(>=;g}{vF(S_
zeujb&;MnJiZAV4&$(*ko^qeZr;o{=Lx=)(-Ov0RZb8w&+5+Vgy1d)OA@J~JrKu27e
z+Iz0o|B>&5<x+d%3;=c+cV*JmBch^Gqx>EmCA=RX+EP*?D84fl#rP!|W+!wG_8okL
z|86%u4hrnS#Lj`1kDlGs@bCWDsL`oQ_G1_Ls!-sQu%)Xj_JG^wMV`v)>Z(Zc<irFj
zxBrJA6>J^cmDOfC^4tH_<mEysm+#O0Z8PjO5)zV)%}sd)g}T<(6ZZiYVaDO9QJY9u
zN%He1#>Q!5RXn+%;SRn}o(4$*D-^Xg6BZVJR@w33*y-1A-!_emU@Aj-j!UC9TcCc3
zQLaPA=JFRhKR-WI`xG0i9X+$HVIRZC%li`ap3O*kQHNEJ#ruEFXzr>aP_1;DK1t4_
z&&0_Y3Q7W$voiSImX40ADQYi&DLiv9Pg659ue5SqW4by!<#PK`nl?Bw^we8R!?L|s
z<XNInRs?GA08@!Nq;G%mV`XJMcKY;b+AE$7tx>G4zf(X#@J1vg=z<f^w)y<#2!NS+
zXM%iv5aI0_U!Uxy<G}VP&8y<p8NBhv$fr+h?;pZ-u^O3jx{Q02fS!RN1uWFUrFK-s
zg~B87a96%uIZ|TtITGjt^+AR$f{Kez%5GL)$b>n>J9>2OTVV|<z5>?f6%uOf>x+Wj
zhTdV2s=+Z2#sFN5X=4Z}?BnY?V@*v#z(B8^rWLZA=YWg`ORdR49C8RP1JV?MmqBfC
zl~_{Y()T<(7@}HHWz3zoHYhm+L@~eJh%id3&);3JWMX0>qNVLbT|puu&Y;>6bmRyS
zDrhtK`no4fR)Il{im|b=E4dy~AitO|>vv&X+y}(7R|tRgR#1NtOOIibmX=oVE>^mG
zmo4}dO>Z_<ugs1HZs--<fNbv<j0Xv@EuG)qd(b&M>IQhg(r<b@sZ}`^^Vq;wW1fNA
z2-U^J#m7e`CF$Gz00%ZXKJJgw9MHFthaC^BQ_N0#TiYzE3Viu282!5yR#=O`b5Mq_
zE@jd0;eOxUB_Ebj%h#G*UN)HC0g-@tc8-Py)nT);UW?zF>p723kl)=6pchO3^PDcx
zB1?#haCdt-6V#$+Qu43sHZ>h3CnrZoJg94@^9%v(WbkviD=XtN*wJ^|qm5_rQiw4a
z3@mdNdV0xtG9se;rKPUX5;Dh8CT|hygFiQSxBABdCkza@AI!!Zf6#W~ecJrs*lb+C
zeIkTSc8XT41w=cLln0A_w7-J5coEDfFcqf|PCorJZP`jG{D76NsO01>__ITEKtL5^
zDq3;PtU25B>wa0_R=zGQD8Pv4ykkR}j0?aA-2BhQ^=vF5mx`l|K$TK&Z*K^VzC6ks
zUKQJ<8Hb^bXf@TX@l8Y>I7dg*i;hlCPFjA-qeS(3wY4~ObaVh)&8YD}TiYujK%@z7
z-M;O3u;(EyBUAMD?F<N6@BPhzzw)sUWP(qj<SE!N?9nC%dpjHReaCoscr0;7{wa%;
zl-9JYWb?0bQH#LEBJP5<#1S3hk9%xlcD5P7BP8qq1#L8HI4aJg9s@Tsl*Ze6YNlXl
z@^nf=02~3>k{!ST6zEnkrV|nnn1YH&XNOi+ZSX|t9{<&X0KF*zHoqzehFh3>eBfCu
zz+N{rH}@6jiGqdZtdeCC5s42B!~<H8`Kyw=bjQ=}qAhkFpPYXl_>ghyw!m|O93(I@
zGD0c~nE{tMwWFub9Y4Eq-;->)8NFILNk1B|4!{Vt5CBs_NPV%PuaAV9n%c(J*0TGh
zf9Hd)DzEJf{VGoo7)_696t7;zb98i+lnO@iHe*9WNe2hs&dyGB)&}bb9_ktx0Z@5$
zLqk-kCx}5cfux!m5ljjasW&rKdfwXJK_O#cR3J^6+<w&ZC^|*#!D37)ZN8RbvbYZ@
z;0AED+S&ue#|Ye9T^sA`Q!8tJy^V)Lv-fsWM~BjncX|FUbacX>1_vq9)#U-q?+dEX
zfoD~Skg{7^Tue)OfLd**E5^?CrsIRA45JYxW21=v3eSp4MlC)!e^FOUl5%S=PMSE{
zLYkv>{rYuRaw(!fzw+5J>y6c-uTH<4o%Qxc0;?nz6oKIsad%WBN`UQf2z9DN?WLL)
zIM2Omfhj~Du|E=Le0*G3L?q^N#+S()t1HsekFK%8GN(mJbYKowzP`u(-J@OL_q$2R
z<p=&IsqOTA_3Shl_Fo~Z=UzBqPU(4hp8{H=9);ue!MBTyk9c~L4u8zlQ#HE7C<zmD
z$!_G{*gGBASZu+wzSjVPwJ+KXN_u;X0WZ%!I4#b$#UPK5kB`!dfwfoH*XuhwAA^QA
zvan!HM_si+WTyd}^_GC(<8zw2e$jRa6~(wNd^7@EM?pa`hnM+A?1QIH$=&xz54N|P
zbiYJ;J^t8f+U_*@sM)G_DB{R3HsJ5!<L#YxjsDL!Z~J>7N9I3!?syfTR8dhj)|L$Y
zs?|CFSI$)+`NQAIS9pIWSqcBoUg7lL{91OL?qU56WE-WGU*W(!=VG0X|9YXgg^>}%
zua}1h#{YNMzM&O>!HA)P*<UXtuXfnj*g*XeQ`np@fejQRp*zOpIAe6tV`pfAyAA(Z
z3TtX;=$S9u#oR)P=vC&5p5D^=TDUJYIC=&KP!s2I&<m)NP?wwhy&6&AEOvBsb>#X-
zLzBE(NrqhP1jgZ`hYm6S`dzcat|6(5jT!9gtB(>A&gJFhT_w5z<Rq@8rDbYip^f^I
zXZcGT_YcO0(BC4)eHf;b;dBtv#xA6n?awPAL06%xKRUc7eUt6%UBUPT?jSIHPg!bS
z{!nF$^VcoxurlenE%#3^nX(wGp9IE1Q+@3TElODdxIm#e#aQm=FJ5SGZ{Z`?I3j?L
zYVJ_!!hnI_ywa0Lk3b{`30QQZ{+?<zzWWPf$Iz$~Zgu3yxi1YdACXd3Rh{XGt4D3|
zQCRofxpOToEnjDo{aE<;iaK03v7;|gw^Jopx%Ev=869Q@e*3PVK6mrBQ<2F|>5k$n
zdO%b2#I`m$Dt={s&Xd5tU^j29uy7zVclb-GuiQyWiN_$QuUKoluZG@Z@#h631t>by
z{Yn<UDU9*~JPL3&$cv|^#lPc#ghq7&W%dTH%eZI(96q>I!X3U87U%Vq0oS*(b&aG4
zvtZQd=XsWHieQTWK(w6u^i8K*-hw%mp#}{CCjwC<=S!LWml?2PD9#P$0=@M}J-cCS
zjP^dKcEQuAsGFbjm~yoXQG!0$fnTz!f59y_JS5~5fF)+VQ}knj-V4++<7=(IMTI>q
zxdX=^m7GNvwN{d=PM60%lX)!H-v9hU2DZA3lQ6n`m})*P_S^fqgH9%knWB~Jrmo~Q
zx4M{!ni?DB{VdGPkZY8dJ`CHtacnFJFpWK2E|pz-^R6Y*6(BYmQ)GgLy*OBHVsUWr
z%;m32X>46UIV_x7d2Eqb*zPE401yo27KkomQg3RZ!Es6AHeY-f7clea+PeB1!2|-;
z)T-h*LFEEg6JI)u3t>|o5*vSzZ*n<wEv-I+Z$M2qK(aKyF>80h9!|!1adv{K05RWN
zgK8<)_xASg?Jku$Iys?is1qbCuR)tIetX(J?R~H_3zn=eSDUBOZK(~el{CPORK)z{
zcxs{-Np}`8&r5WzI0@6b=-l2k-!gdOc~NfgMNPRqn-@!!9I!%&(mUtbQ|#>QsE8Rx
zz_L=88_6uQg1&))SX8S2;~W`TP;4wY4vHGUT8F8SU#Fp=3C*hqLK7&iDbyMn8Tli`
zb9EsXW<+0uZ{BLLBjmJ|oB59s#UH!TQDu|GI}^1sEFPcNWtT<vti6PJCX~koD$aZF
z+2yP4ZY|9Z6w)cAt6O-6l5qjkdFSjcE-s>Kf(nQ6!{pq$^z`)i3u_K4uUDp}F==o_
zZ(L?%l(x!6+px`TH6r97oXcbFgB@9rQ{^WCR^hc}=f(GT*zfu$^E4P4G0m20nQd<r
zo`Q)N5fSMH0yLg&HT7G*Vq#(f-2eUKPSuZvT(l^kKc|R{it^YVb^l!D<sRVz+ZM#c
ztDd{43<)JzxG#@&8IuDl?wwz%iIA3i93+dY>rf;p2{`sBk*_`IquKJNsa+E(O(4B?
zYUAw6c^0>l)PiU!W+$JwNuO~yWr7G8L`Cl`NL7NLOWZLxH%H5Q+LP?{1(0TdZtq-{
z#}XG8ZQ#aQ!YBno(u&K<P*HRcAvHMhpu$3)QtO&~T_tc2n5>f8DZOpVWy|(ghqyn!
z?Pg`U600{5`Pnyp>hY6HlW#tIUXG}!`o`-xTt%KUsgyl=CL<$bVsUX#gEBBE$Z6pt
zJF4(hQ91SL(<js#%x<(2l+o(QML`aZllJ!Zb#-+)-lO2bE~rm)9uHW_E4@V`??auM
zY0x7vGTLBM;Qdu&Q4AkH)Z%Bs4e)1TVq!U762BOv$f{$G1dta-H4hyL!rdBLDbeTU
zJid%5MM5##UkyMmtXltQxZDF>?n10F*bQ9v4f<`_1=qF1ZT)v|w3wx5unQ4UQBs1>
zLs1gx8x<85Ow7zirc6|@)b1S&U8ahB8WAkQQ&SnbCf(NAM_kyJDzns^tjSY4z$U4$
zPYW0}H5*E^&s3rN7@X6|MuBB#Citd2_G6L4q!G$V<pLKbeh$4eITvU||HrH1T;WK)
zyeVo2QYyRV8z#GWCyu<ry&-w1)o*hvH9{-CReAR2r%iQ(v8xTc^msUig^UxzUHmvW
zVlqUBaZY{spoE=b!1;P>M9<vKJ}|jJ0taWsp7!%>m3#WLXU-XvhjHAxMl}_B#JY51
zWcw-$s7$gx<vjCsm!iPAZ_g)C`l-bBh28fFl3c7Zi!u%l4zr8wEf-TG7c&tPCo}jT
z9DZK@i?BnucrR=4@rm&Ai|}3M<mDCN<<+K-{P0g7u(da}H23)X53u-fIKl_m{?7+o
zEN#u4U5soU{{AzLckv70GnD8vnl6?u&Nyn8_sndZ)y$k^%<RwwT+E#2d-~tPAK}Q$
Ls$4CQHVpV*gNUvT

literal 16395
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
N$w?_omO_jJ{s%?Mh<X43

-- 
2.47.3

[PATCH docs v2 19/19] ha-manager: crs: add load balancer section

[Daniel Kral]

For pve-ha-manager >= 5.2.0, the HA Manager features an automatic
rebalancing system, which is available for the static and dynamic-load
scheduler mode.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
Reviewed-by: Michael Köppl <m.koeppl@proxmox.com>
Reviewed-by: Dominik Rusovac <d.rusovac@proxmox.com>
---
changes v1 -> v2:
- depending *on* where
- controls the sensitivity of the load balancer

 ha-manager.adoc | 51 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index 0421b86..2e13c46 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -1435,9 +1435,6 @@ scheduling decisions. The CRS mode can be changed in the web interface
 is `basic`. The change will take effect starting with the next HA Manager
 round, which should take no longer than 10 seconds.
 
-NOTE: There are plans to add modes for (static and dynamic) load-balancing in
-the future.
-
 [[_basic_scheduler]]
 Basic Scheduler
 ^^^^^^^^^^^^^^^
@@ -1526,6 +1523,54 @@ functionality is still in technology preview. The more HA resources the more
 possible combinations there are, so it's currently not recommended to use it if
 you have thousands of HA resources.
 
+CRS Load Balancer
+~~~~~~~~~~~~~~~~~
+
+IMPORTANT: This feature is still in technology preview.
+
+The utilization of individual cluster nodes can vary greatly depending on where
+guests are currently running and how much load these exert at any moment. This
+can cause the node utilizations to become imbalanced over time, where HA
+resources on one node become bottlenecked due to resource contention, while
+another node is barely utilized.
+
+The HA Manager's automatic load balancer can lower the overall cluster
+imbalance by automatically issuing rebalancing migrations. Currently, these
+migrations are issued only for HA resources and executed sequentially.
+Furthermore, these migrations always obey the current HA affinity rules.
+
+The automatic load balancing system can be enabled and configured in the web
+interface under `Datacenter` -> `Options` -> `Cluster Resource Scheduling`.
+This allows fine-tuning the various parameters as described in the next
+paragraph for different cluster setups and requirements. The load balancer
+requires either the xref:_static_scheduler[static] or
+xref:_dynamic_scheduler[dynamic-load scheduler mode] to be in use.
+
+In every HA Manager round, where each lasts around 10 seconds, the automatic
+load balancer checks whether the cluster imbalance exceeds the _imbalance
+threshold_. If exceeding the imbalance threshold is sustained for at least as
+many consecutive HA Manager rounds as given by the _hold duration_, then the
+load balancer will select the rebalancing migration for an HA resource, which
+lowers the overall cluster imbalance the most. The method used to select the
+best rebalancing migration can be set with the _rebalancing method_ option. At
+last, if the selected migration reduces the current cluster imbalance by at
+least the percentage given by the _imbalance improvement_ option, the load
+balancer issues the selected migration.
+
+The cluster imbalance is calculated as the ratio between the standard deviation
+and mean of the individual node loads. Therefore, the _imbalance threshold_
+controls the sensitivity of the load balancer. If the _imbalance threshold_ is
+set to a value of `0.0`, it will try to select a rebalancing migration every
+time the _hold duration_ is exceeded. The _imbalance improvement_ percentage
+filters what constitutes as an acceptable rebalancing migration. If it is set
+to `0.0`, then it will always commit to a migration even though the expected
+imbalance does not change at all. However, the value can never be negative,
+therefore it will never commit to a migration with an expected imbalance worse
+than the current one.
+
+NOTE: It is planned that load balancing will also include non-HA resources in
+the future.
+
 ifdef::manvolnum[]
 include::pve-copyright.adoc[]
 endif::manvolnum[]
-- 
2.47.3