Add a soft host-tag VM placement preference (affinity processor)

[nagaboinaramgopal]

Description

Adds a new affinity group processor for a soft host-tag placement preference. A group of type "host tag affinity" uses the group name as a host tag, and when a member VM deploys, hosts carrying that tag get a higher deployment priority within the cluster the planner selects. It does not change which cluster is chosen, so it is a within-cluster preference, the same way the existing non-strict host affinity works. It is only a preference: no host is excluded, deployment still works when no tagged host is free, and check() never fails a destination. The group is admin-controlled, so only an admin can create one and a regular user cannot name a group after a host tag. This is the soft counterpart to the existing strict host tag on service and disk offerings. The raised priority is a planner hint and is not used by automatic DRS.

Types of changes

• Breaking change (fix or feature that would cause existing functionality to change)
• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Enhancement (improves an existing feature and functionality)
• Cleanup (Code refactoring and cleanup, that may add test cases)
• Build/CI
• Test (unit or integration test code)

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

• Major
• Minor

Bug Severity

• BLOCKER
• Critical
• Major
• Minor
• Trivial

Screenshots (if appropriate):

N/A

How Has This Been Tested?

Unit tests cover the three paths: tagged hosts get a higher priority, no matching tag is a no-op, and check() returns true.

Also on a live lab with three KVM hosts in one zone: tagged a single host, created a "host tag affinity" group named after the tag, and deployed. All the VMs in the group landed on the tagged host, and a VM outside the group landed on an untagged host.

How did you try to break this feature and the system with this change?

Deployed with no host carrying the tag: the processor does nothing and the VM still deploys. Ran a VM outside the group to confirm the untagged host was a valid target, so the tag preference is what steered placement, not a lack of options. Since it only raises priority and never excludes a host, a full or missing tagged host cannot block a deployment.

[DaanHoogland]

@weizhouapache how does this fit in functionally with hard - and soft affinity and -anti-affinity?

[codecov]

Codecov Report

❌ Patch coverage is 73.52941% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 19.91%. Comparing base (d87c804) to head (f1f1fa9).
⚠️ Report is 56 commits behind head on main.

Files with missing lines	Patch %	Lines
.../cloudstack/affinity/HostTagAffinityProcessor.java	73.52%	5 Missing and 4 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #14083      +/-   ##
============================================
+ Coverage     19.78%   19.91%   +0.13%     
- Complexity    19995    20209     +214     
============================================
  Files          6371     6374       +3     
  Lines        575909   577264    +1355     
  Branches      70509    70703     +194     
============================================
+ Hits         113950   114987    +1037     
- Misses       449526   449702     +176     
- Partials      12433    12575     +142     

Flag	Coverage Δ
uitests	3.71% <ø> (+0.18%)	⬆️
unittests	21.19% <73.52%> (+0.12%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nagaboinaramgopal]

@weizhouapache how does this fit in functionally with hard - and soft affinity and -anti-affinity?

@DaanHoogland . This is meant as the soft counterpart of host tags on service offerings, not as another VM-to-VM affinity. A group of this type points its VMs at the hosts carrying the matching tag and raises their deployment priority. No host is excluded, so a deployment still succeeds when the tagged hosts are full.

With the existing types, it uses the same host priority adjustment as the non-strict affinity and anti-affinity processors, so a VM that belongs to both kinds of group gets the combined adjustment. The strict processors still filter hosts through the avoid list before any priority is applied, so they always take precedence. It is implemented as a separate processor module and does not change the existing ones.

If you or @weizhouapache think this fits better as an option on host tags than as a new affinity group type, I am happy to rework it that way.

[DaanHoogland]

your code looks good @nagaboinaramgopal , but I still have some functional doubts (due to lack of understanding probably)
A tag on a host is set by an operator. An (anti-)affinity group is created by a user. How is that going to work in practice? Will the user have to ask the operator to set a tag on the host after giving the affinity group a name?

[nagaboinaramgopal]

Right, this is operator-driven by design: the group name is the host tag, and tagging hosts is the operator's job, same as the existing host tag on offerings. The group is just how you pin that preference onto a set of VMs.

That said, the gap you're pointing at is real. I left it inheriting isAdminControlledGroup() == false, so a normal user could name a group after any tag and bias their VMs onto those hosts. It should be admin-controlled, like ExplicitDedication. I'll flip that and add a test.

[Copilot]

Copilot review overview

🟡 Changes recommended

Host priority is applied only after cluster selection, so the zone-wide preference fails across clusters.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Apply host-tag priority when ordering clusters · New
• Place host-tag-affinity in alphabetical module order · New

What changed in this PR

Adds a soft host-tag affinity processor that prioritizes tagged hosts without excluding alternatives.

Changes:

• Adds host-tag affinity processing and Spring registration.
• Integrates the plugin into Maven and client packaging.
• Adds unit tests for priority, fallback, and administration behavior.

File	Description
plugins/​pom.xml	Registers the plugin module.
client/​pom.xml	Packages the plugin with the client.
plugins/​affinity-group-processors/​host-tag-affinity/​pom.xml	Defines the Maven module.
.../​HostTagAffinityProcessor.java	Implements host-tag priority adjustment.
.../​HostTagAffinityProcessorTest.java	Tests processor behavior.
.../​spring-host-tag-affinity-context.xml	Registers the processor bean and type.
.../​module.properties	Defines plugin module metadata.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[DaanHoogland]

Right, this is operator-driven by design: the group name is the host tag, and tagging hosts is the operator's job, same as the existing host tag on offerings. The group is just how you pin that preference onto a set of VMs.

That said, the gap you're pointing at is real. I left it inheriting isAdminControlledGroup() == false, so a normal user could name a group after any tag and bias their VMs onto those hosts. It should be admin-controlled, like ExplicitDedication. I'll flip that and add a test.

@nagaboinaramgopal , I think it would be better to have a pattern that such tags must be adhering to and forbid the user to create any group adhering to that pattern. Though I think the functionality might be useful, I fear it leaves a bit to much opportunity for abuse.

[Damans227]

what happens if the tagged host is in a different cluster than the first one the planner tries? looks like the higher priority only reorders hosts inside one cluster, so the vm could still land somewhere else

[nagaboinaramgopal]

Yeah, you're right. The priority bump only reorders hosts inside whichever cluster the planner ends up choosing, so if the tagged host sits in a cluster the planner reaches later, an untagged host in an earlier cluster can still win. I can keep this scoped as a within-cluster preference and fix the wording so it doesn't claim more than it does, or make it bias cluster ordering too so it holds across the whole zone (that one's a bigger change to how clusters get picked). Do you have a preference?

[Damans227]

keeping it inside one cluster and fixing the wording sounds good to me, thats how the existing non-strict host affinity works too. changing how clusters get picked feels like its own pr

[nagaboinaramgopal]

Perfect, thanks. I've scoped it as a within-cluster preference and fixed the wording in both the code and the description so it doesn't imply anything zone-wide. Cluster ordering can be its own PR later if we decide we want it.

[nagaboinaramgopal]

Thanks @DaanHoogland. With the admin-controlled change it's now only an admin who can create one of these groups, so a regular user can't point one at an arbitrary tag anymore, which I think closes the main abuse path. If you'd still like a naming pattern the tags must follow on top of that (so it can only target tags meant for this, not operational ones), I'm happy to add a configurable prefix and enforce it at creation. Would admin-controlled be enough, or do you want the pattern as well?

[DaanHoogland]

Thanks @DaanHoogland. With the admin-controlled change it's now only an admin who can create one of these groups, so a regular user can't point one at an arbitrary tag anymore, which I think closes the main abuse path. If you'd still like a naming pattern the tags must follow on top of that (so it can only target tags meant for this, not operational ones), I'm happy to add a configurable prefix and enforce it at creation. Would admin-controlled be enough, or do you want the pattern as well?

if we can guarantee normal users cannot create groups named after these tags, I'm fine. the prefix would then only be a nice operational feature.

[nagaboinaramgopal]

Thanks @DaanHoogland. Confirmed on the guarantee: createAffinityGroup throws PermissionDeniedException for a non-root-admin on an admin-controlled group, and the type isn't even listed to non-admins, so a regular user can't create one of these. I'll leave the tag prefix out for now and we can add it later as the operational nicety you mentioned.