Affinity Manager Plugin: Tag-Based VM placement and grouping control

johnnezero

Affinity Manager Plugin

WHAT: In keeping with my previous project (Tag-Automation Plugin, found here), I am releasing the Affinity Manager Plugin, which is a fully tag-driven plugin for Xen Orchestra. It serves as a replicacement for VMware's DRS (which is a core-critical feature set currently missing in XO), to ensure continuous uptime and optimal resource allocation of crucial VMs and services.

PROGRAM FEATURES

Host Affinity (RunOn) Run VMs on specific host group (e.g. a particular data center or set of hosts)
Host Anti-Affinity (NotOn) Keep VMs off of specific host group
VM Keep-Together (KeepTogether) Keep named group of VMs on the same host (follows Leader VM)
VM Separation (KeepApart) Spread named group of VMs across unique hosts (best-effort)

REAL-WORLD EXAMPLES

Core-Critical Service Protection (AM-RunOn)

Example #1: Run core-critical services in sepparate Data Centers
Goal: Ensure crucial VMs (i.e. MS AD, DNS, etc.) are protected from possible DC outage
VM Tag: AM-RunOn_P1-DC1-HOST (applied to "Primary" crucial service VM)
VM Tag: AM-RunOn_P1-DC2-HOST (applied to "Secondary" crucial service VM)
Host Tag: P1-DC1-HOST (applied to each POOL-1/Data Center 1 host)
Host Tag: P1-DC2-HOST (applied to each POOL-1/Data Center 2 host)
Result: The primary service VMs (i.e. MS AD Controller) will run on DC1 host(s), and the secondary service VMs will run on DC2 host(s)

Database High Availability (KeepApart)

Example #2: Run database servers on different physical hosts
Goal: Protect critical DB servers from possible host outage
VM Tag: AM-KeepApart_DBCluster1 (applied to both DB VMs)
VM Tag: AM-RunOn_P1-DC2-HOST (applied to "Secondary" crucial service VM)
Result: Ensures DB servers run on different hosts

Note: Tag rules are soft-enforced. For example, if a data center outage occurs all VMs will automatically run any available hosts.

VM TAG SYNTAX

Apply tags to VMs in the XO UI:

VM TAG / RULE	EXAMPLE	MEANING
AM-RunOn_{HostGrpName}	`AM-RunOn_P1-DC2-HOST`	VM should run on hosts tagged `P1-DC2-HOST`
AM-NotOn_{HostGrpName}	`AM-NotOn_P2-DC1-HOST`	VM should NOT run on hosts tagged `P2-DC1-HOST`
AM-KeepTogether_{GrpName}	`AM-KeepTogether_AppStack1`	Keep all group VMs on same host (follows Leader VM)
AM-KeepApart_{GrpName}	`AM-KeepApart_DBCluster1`	Spread group VMs across unique hosts (best effort)

Note: Multiple rules can be combined on a single VM. For example, a VM can have both
AM-RunOn_P1-DC1-HOST and AM-KeepTogether_WebCluster simultaneously.

HOST TAG SYNTAX

Apply tags to hosts in the XO UI (i.e. to define host groups):

EXAMPLE HOST TAG	POOL	LOCATION
P1-DC2-HOST	POOL-1	Data Center 2
P2-DC1-HOST	POOL-2	Data Center 1

INSTALLATION

Note: "Airgap" in the tar.gz file below, simply means the bundle includes all required dependencies for both an offline or online installation.

Download the latest airgap release tarball from GitHub:
https://github.com/johnezero/xo-affinity-manager/releases

SCP the tarball to your XOA:

scp xo-affinity-manager-airgap-vX.X.X.tar.gz <xoa-user>@<xoa-ip>:/tmp/

Create the plugin folder:

sudo mkdir -p /usr/local/lib/node_modules/xo-server-affinity-manager

Extract directly into the plugin directory:

sudo tar -xzvf /tmp/xo-affinity-manager-airgap-vX.X.X.tar.gz -C /usr/local/lib/node_modules/xo-server-affinity-manager/ --strip-components=1

Restart xo-server:
```
sudo systemctl restart xo-server
```
Verify registration:
```
sudo journalctl -u xo-server -n 100 --no-pager | grep -A3 "affinity-manager"
```
You should see:
[INFO] xo-affinity-manager: Plugin factory called -- xo context: YES
[INFO] xo-affinity-manager: Plugin loaded -- waiting for core started.
xo:plugin INFO successfully register affinity-manager
Enable and configure the plugin in XO:
Settings -> Plugins -> affinity-manager -> Enable

CONFIGURATION

(XO > Settings > Plugins)

Enforcement Schedule — Run every 15 minutes, hourly, or daily (configurable)
Dry Run Mode — Logs all intended actions without migrating anything (default: ON)
Log Path — Configurable path to the log (Created automatically if it does not exist).
Pool Safety — Cross-pool migration is always blocked (i.e. Plugin only migrates VMs within the same pool)
Log Rotatate — Rotate/compress log files at 10 MB (keeping 3 archives)

LINKS

GitHub: https://github.com/johnezero/xo-affinity-manager

STANDARD DISCLAIMER HERE

This software is provided AS-IS without any express or implied warranty.
While this plugin is being used in a production environment managing live VMs,
you should always review the code and test it in a non-production environment
before full deployment.
Note: The plugin is designed to ONLY take action on VMs with specific predefined tags assigned -- all other VMs are never touched.
Use Dry-Run mode to preview all changes before applying them.
That said, as always - your mileage may vary...

poddingue

Second plugin in a couple of months, you're tireless.

I don't want to dampen your enthusiasm, but... there's something you'll probably want to know: XO's load-balancer already covers part of this, affinity tags were merged upstream back in November 2025, and there's an open pull request adding VM-to-host affinity right now, which looks (to me, at least) like your AM-RunOn and AM-NotOn: https://github.com/vatesfr/xen-orchestra/pull/10207.

What's already there is written up at https://docs.xen-orchestra.com/xo5/load_balancing#vm-affinity, and XCP-ng has its own anti-affinity at https://docs.xcp-ng.org/management/vm-load-balancing#vm-anti-affinity.

I'm not saying that makes yours redundant, and I might be misreading how much of it really overlaps, but AM-KeepApart and the dry-run default look like they go past what's in either of those.