HA rules: node-affinity (PVE 9) · Proxmox VE

Why this matters in production

HA without rules places VMs on whatever node has capacity. In production, you usually want fine-grained control: keep this VM on this node, avoid that node, keep two VMs together. HA rules provide that control.

HA Groups were deprecated in PVE 9

In Proxmox VE 9.0, HA Groups were deprecated in favour of HA Node Affinity rules. HA Groups defined node lists with priorities; HA Rules are a more flexible, declarative model.

flowchart LR
  subgraph OLD[Old: HA Groups]
    G[Group: web-tier]
    N[Nodes pve-01:2, pve-02:1]
  end
  subgraph NEW[New: HA Rules]
    R[Rule: node-affinity]
    NL[Resources + nodes + priorities]
  end

Rule types

Two kinds of HA rules exist:

Type	Purpose
`node-affinity`	Where resources can or must run
`resource-affinity`	Whether resources must be co-located or separated

Node-affinity rules

A node-affinity rule constrains where a resource can run.

CLI:

ha-manager rules add node-affinity ha-vm100 --resources vm:100 --nodes pve-01

By default, the rule is non-strict: if the listed nodes are unavailable, the resource may run elsewhere. To make it strict:

ha-manager rules set node-affinity ha-vm100 --strict 1

To express priorities (preferred nodes):

ha-manager rules add node-affinity ha-web --resources vm:100,vm:101 --nodes "pve-01:2,pve-02:1,pve-03:1"

The CRM prefers pve-01; falls back to pve-02 or pve-03 equally; uses no others.

To express negative affinity (avoid a node):

ha-manager rules add node-affinity ha-avoid3 --affinity negative --resources vm:200,vm:300 --nodes pve-03

Resource-affinity rules

Resource affinity rules control whether resources are kept together or apart.

Keep together (positive):

ha-manager rules add resource-affinity keep-together --affinity positive --resources vm:100,vm:200

Keep apart (negative):

ha-manager rules add resource-affinity keep-separate --affinity negative --resources vm:200,ct:300

Strict and non-strict are a choice between two failure modes, not a strength setting

“Strict” sounds like a stronger version of the same rule. It is not. The two settings produce different failures, and choosing between them is choosing which failure you would rather have at 03:00.

Non-strict is a preference. The CRM places the resource on the listed nodes when it can, and somewhere else when it cannot. The failure mode is a guest that is up in the wrong place - running on hardware without the GPU it needs, on the node whose licence does not cover it, on the wrong side of a tenancy boundary. It is running, so monitoring is green, and nobody finds out until someone notices the workload is wrong rather than absent.

Strict is a constraint. If no listed node can take the resource, it goes to error and stays stopped. The failure mode is a guest that is down and obvious.

So the question is never “how confident am I in this rule”. It is: if this constraint cannot be met, is running in the wrong place better or worse than not running?

Constraint	Choose	Because
Needs a GPU or a passed-through device	strict	It cannot do its job without the hardware
Licensed per socket on specific hosts	strict	Running elsewhere is a compliance event
Tenant isolation boundary	strict	The boundary is the requirement
Prefers the faster nodes	non-strict	Slower is better than stopped
Prefers the node nearest its data	non-strict	Latency is a preference, not a rule

The commonest mistake is a strict rule written for a preference - and its symptom is a guest that could have run and did not, during an incident where everything was already going badly.

Verifying rules

Read-only / Safewhat rules apply to a resource, and are they satisfiable— Read-only. Run it after every rule change and before every planned node removal - a rule that was satisfiable with four nodes may not be with three.

set -euo pipefail
VMID=100

ha-manager rules config
ha-manager rules config --resource "vm:$VMID"
ha-manager config

# Do the nodes a strict rule names still exist and are they online?
ha-manager rules config --resource "vm:$VMID" | grep -i nodes
pvecm nodes

Read-only / Safea rule the cluster cannot satisfy shows up here

# ha-manager status

quorum OK
master pve-01 (active, Wed Aug 12 11:02:41 2026)
lrm pve-01 (active, Wed Aug 12 11:02:44 2026)
lrm pve-02 (active, Wed Aug 12 11:02:43 2026)
service vm:100 (pve-01, started)
service vm:140 (pve-03, error)

Illustrative output

Rule conflicts

The HA stack checks rules for feasibility, and the constraints are structural:

A resource may appear in only one node-affinity rule.
A negative node-affinity rule cannot list every cluster node - that would leave the resource nowhere to run.
A resource-affinity rule must have at least two resources.
A negative resource-affinity rule cannot cover more resources than there are nodes, since each must land somewhere different.

Conflicts are reported in ha-manager status.

The rule that was satisfiable until a node was removed

The symptom. A cluster is reduced from four nodes to three during a planned decommission. Everything is verified and healthy. Two weeks later a node fails and three guests that should have recovered sit in error.

What happened. A negative resource-affinity rule kept four guests apart - one per node - which was satisfiable with four nodes and exactly satisfiable with none to spare. With three nodes it was already impossible, and with two survivors it was impossible twice over. The rule was written when it was true and nothing re-evaluated it.

Why nothing warned anyone. Feasibility is checked when a rule is created or edited, and the rule was not edited. Removing a node is a change to the other side of the constraint, and the decommission checklist had no line for it.

The check to add to every node-removal procedure:

ha-manager rules config
pvecm nodes | tail -n +2 | wc -l

For each negative resource-affinity rule, count its resources; if that count exceeds the node count you will have after the removal - and after one further node failure - the rule is already broken. Same for any strict node-affinity rule whose node list is about to shrink.

The general principle: HA rules encode assumptions about cluster size. Changing the cluster size invalidates them silently, and the invalidation surfaces during recovery, which is the worst available moment.

What happens to your HA Groups when you upgrade from PVE 8?

They are migrated automatically to node-affinity rules, and the result is usually right - but “usually” is doing work, and this is a ten-minute check that belongs in every PVE 8 to 9 upgrade plan.

HA Groups carried a restricted flag and a nofailback flag alongside their node list and priorities. Those map onto the new model:

HA Group property	Becomes
Node list with priorities	`--nodes 'pve-01:2,pve-02:1'` on a node-affinity rule
`restricted`	`--strict 1`
`nofailback`	`failback 0` on the resource

Two things to verify afterwards, because they are where the translation is easiest to misread:

ha-manager rules config
ha-manager config

Every rule that should be strict is strict. A group that was restricted and became a non-strict rule is a guest that will now run anywhere - and, per the section above, run wrongly rather than fail visibly.
Failback intent survived. nofailback was a group property and failback is a resource property, so the migration has to distribute one setting across several resources. Check the resources, not just the rules.

Do this while the cluster is healthy. A misread rule behaves identically to a correct one until the day placement actually matters.

Production considerations

Common mistakes

Strict rules that cannot be satisfied (cluster enters error state).
Resource-affinity with too many resources for the cluster size.
Forgetting to verify rules after editing.

Key takeaways

HA Groups are deprecated in PVE 9; use HA Node Affinity rules.
Node-affinity controls which nodes a resource can run on.
Resource-affinity controls co-location / separation.

Knowledge check

Why this matters

HA rules are the mechanism by which the cluster’s placement decisions stop being arbitrary, and they have a property that makes them unusually easy to get wrong: they are invisible from the guest.

Nothing in a VM’s configuration says why it lives where it does. qm config shows storage, network and hardware; the constraint that keeps the guest on two particular nodes is in a separate object, under a name someone chose, with no back-reference. So a rule written for a good reason in March is, by September, a fact about the cluster that nobody can explain - and the first instinct on meeting an unexplained constraint during an incident is to remove it.

Two habits make that survivable. Put the reason in the rule’s comment, since that is the only field that travels with it. And re-evaluate rule feasibility whenever the cluster changes size, because a rule that encodes “one guest per node” is a statement about node count that stops being true the moment you decommission something, silently, with the consequence deferred until the next node failure.