[PATCH docs 0/2] add requirements for HA-managed resources

[PATCH docs 0/2] add requirements for HA-managed resources

[Daniel Kral]

The first patch cleans up the previous introduction for HA resources a
bit and removes some outdated comparison to rgmanager, while the second
patch adds a list of requirements with some accompanying text what to do
if these requirements are not met.


Daniel Kral (2):
  ha-manager: reword ha resources section
  ha-manager: add requirements for ha-managed vms and containers

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

-- 
2.47.3

[PATCH docs 1/2] ha-manager: reword ha resources section

[Daniel Kral]

Focus on the introduction of the HA resource concept first and what an
HA resource represents in the broader Proxmox VE context, while
introducing the service ID only in a later chapter.

Remove the comparison with `rgmanager` as it's quite dated already and
seemingly unused as it seems to be replaced by pacemaker in newer
versions of RHEL.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
---
 ha-manager.adoc | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index a1b2210..6bf4e69 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -126,18 +126,14 @@ the linux kernel software watchdog (`softdog`).
 Resources
 ---------
 
-We call the primary management unit handled by `ha-manager` a
-resource. A resource (also called ``service'') is uniquely
-identified by a service ID (SID), which consists of the resource type
-and a type specific ID, for example `vm:100`. That example would be a
-resource of type `vm` (virtual machine) with the ID 100.
-
-For now we have two important resources types - virtual machines and
-containers. One basic idea here is that we can bundle related software
-into such a VM or container, so there is no need to compose one big
-service from other services, as was done with `rgmanager`. In
-general, a HA managed resource should not depend on other resources.
+The HA Manager's primary management unit is called an HA resource (or
+``HA service''). Currently, an HA resource can be either a Virtual
+Machine (VM) or Linux Containers (CT).
 
+Each HA resource is uniquely identified by a service ID (`sid`), which
+consists of the resource type and a type-specific ID, which is the VMID
+for VMs and containers. For example, for the VM with VMID `100`, the
+service ID is `vm:100`.
 
 Management Tasks
 ----------------
-- 
2.47.3

[PATCH docs 2/2] ha-manager: add requirements for ha-managed vms and containers

[Daniel Kral]

The HA Manager implicitly requires certain conditions that VMs and
containers need to fulfill to be handled correctly by the HA Manager.

Make the most important conditions explicit by writing them out in the
HA resources section and add a paragraph what role HA rules play here to
accomodate for HA resources, which do not meet all of these
requirements.

Signed-off-by: Daniel Kral <d.kral@proxmox.com>
---
 ha-manager.adoc | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/ha-manager.adoc b/ha-manager.adoc
index 6bf4e69..599622a 100644
--- a/ha-manager.adoc
+++ b/ha-manager.adoc
@@ -135,6 +135,26 @@ consists of the resource type and a type-specific ID, which is the VMID
 for VMs and containers. For example, for the VM with VMID `100`, the
 service ID is `vm:100`.
 
+In general, HA resources need to be setup in such a way, so that they are
+able to run on any cluster node. Therefore, a VM or container should meet
+the following requirements before it is added as an HA resource:
+
+* use options, which are compatible on all nodes
+
+* only use shared storage, which are available on all nodes
+
+* only use network interfaces, which are available on all nodes
+
+* only use device passthroughs, which are available on all nodes
+
+If a VM or container cannot fully meet these requirements, it can still
+be possible to configure them as HA resources by encoding the deviations
+from these requirements as xref:ha_manager_rules[HA rules]. For example,
+if the device passthrough for an HA resource is only available to some
+of the cluster nodes, then the HA resource must be constrained to these
+cluster nodes by a strict
+xref:ha_manager_node_affinity_rules[node affinity rule].
+
 Management Tasks
 ----------------
 
-- 
2.47.3

applied: [PATCH docs 0/2] add requirements for HA-managed resources

[Thomas Lamprecht]

On Mon, 04 May 2026 13:11:53 +0200, Daniel Kral wrote:
> The first patch cleans up the previous introduction for HA resources a
> bit and removes some outdated comparison to rgmanager, while the second
> patch adds a list of requirements with some accompanying text what to do
> if these requirements are not met.
> 
> 
> Daniel Kral (2):
>   ha-manager: reword ha resources section
>   ha-manager: add requirements for ha-managed vms and containers
> 
> [...]

Applied, with some wording improvement squashed in, thanks!

Also adapted this slightly to avoid conveying that always all nodes need to
support all HA resources, as with node affinity that's not a requirement. I
initially thought about doing that adaption as follow-up, but it was not that
much change while touching basically quite a few lines due to diff churn, so I
figured it's better squashed in to keep the commit whole, hope that's OK (I
did add a notice to the commit message to describe my changes though for
transparency).

[1/2] ha-manager: reword ha resources section
      commit: 6e40229424611ea216733259489d605556bb4a32
[2/2] ha-manager: add requirements for ha-managed vms and containers
      commit: 8fbf4ab3b38790f6b7219a5e709803ec152055df

Re: applied: [PATCH docs 0/2] add requirements for HA-managed resources

[Daniel Kral]

On Mon May 4, 2026 at 8:40 PM CEST, Thomas Lamprecht wrote:
> On Mon, 04 May 2026 13:11:53 +0200, Daniel Kral wrote:
>> The first patch cleans up the previous introduction for HA resources a
>> bit and removes some outdated comparison to rgmanager, while the second
>> patch adds a list of requirements with some accompanying text what to do
>> if these requirements are not met.
>> 
>> 
>> Daniel Kral (2):
>>   ha-manager: reword ha resources section
>>   ha-manager: add requirements for ha-managed vms and containers
>> 
>> [...]
>
> Applied, with some wording improvement squashed in, thanks!
>
> Also adapted this slightly to avoid conveying that always all nodes need to
> support all HA resources, as with node affinity that's not a requirement. I
> initially thought about doing that adaption as follow-up, but it was not that
> much change while touching basically quite a few lines due to diff churn, so I
> figured it's better squashed in to keep the commit whole, hope that's OK (I
> did add a notice to the commit message to describe my changes though for
> transparency).

That looks good, the reframing helps in conveying the message that it's
not that these HA resources cannot be added at all, but that admins need
to encode the proper dependencies if they are different from the usual
assumptions. Thanks!

>
> [1/2] ha-manager: reword ha resources section
>       commit: 6e40229424611ea216733259489d605556bb4a32
> [2/2] ha-manager: add requirements for ha-managed vms and containers
>       commit: 8fbf4ab3b38790f6b7219a5e709803ec152055df