Add ability to filter by version for listHosts and listMgmtServers APIs #12472

nvazquez · 2026-01-20T14:22:34Z

Description

This PR allows filtering hosts and management servers by version through their listing APIs

(localcloud) 🐱 > list hosts version=4.20.3.0-SNAPSHOT filter=id,name,state,version type=routing
{
  "count": 2,
  "host": [
    {
      "id": "4a7b573c-8b7d-4da9-be86-20f4a4640c91",
      "name": "ref-trl-10590-k-Mr8-nicolas-vazquez-kvm1",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    },
    {
      "id": "24b4a589-8df5-453a-a882-a87fc6949356",
      "name": "ref-trl-10590-k-Mr8-nicolas-vazquez-kvm2",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    }
  ]
}

(localcloud) 🐱 > list managementservers version=4.20.3.0-SNAPSHOT filter=id,state,osdistribution,version
{
  "count": 1,
  "managementserver": [
    {
      "id": "a44c9027-3909-441c-a792-b63d5799ac00",
      "osdistribution": "Rocky Linux 8.4 (Green Obsidian)",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    }
  ]
}

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

Screenshots (if appropriate):

How Has This Been Tested?

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

codecov · 2026-01-20T14:30:33Z

Codecov Report

❌ Patch coverage is 0% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 16.24%. Comparing base (8db7cab) to head (e2fd343).
⚠️ Report is 8 commits behind head on 4.20.

Files with missing lines	Patch %	Lines
...ain/java/com/cloud/api/query/QueryManagerImpl.java	0.00%	7 Missing ⚠️
...loudstack/api/command/admin/host/ListHostsCmd.java	0.00%	3 Missing ⚠️
...ack/api/command/admin/management/ListMgmtsCmd.java	0.00%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               4.20   #12472      +/-   ##
============================================
- Coverage     16.24%   16.24%   -0.01%     
+ Complexity    13393    13390       -3     
============================================
  Files          5657     5657              
  Lines        499107   499120      +13     
  Branches      60574    60576       +2     
============================================
  Hits          81069    81069              
- Misses       409001   409014      +13     
  Partials       9037     9037

Flag	Coverage Δ
uitests	`4.03% <ø> (ø)`
unittests	`17.09% <0.00%> (-0.01%)`	⬇️

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

☔ View full report in Codecov by Sentry.
📢 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.

sureshanaparti

clgtm

sureshanaparti · 2026-01-20T14:49:33Z

@blueorangutan package

blueorangutan · 2026-01-20T14:50:36Z

@sureshanaparti a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-01-20T15:50:59Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 16451

nvazquez · 2026-01-21T02:02:37Z

@blueorangutan test

blueorangutan · 2026-01-21T02:04:34Z

@nvazquez a [SL] Trillian-Jenkins test job (ol8 mgmt + kvm-ol8) has been kicked to run smoke tests

DaanHoogland

clgtm

blueorangutan · 2026-01-21T16:19:13Z

[SF] Trillian test result (tid-15226)
Environment: kvm-ol8 (x2), zone: Advanced Networking with Mgmt server ol8
Total time taken: 48432 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr12472-t15226-kvm-ol8.zip
Smoke tests completed. 141 look OK, 0 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File

harikrishna-patnala · 2026-01-22T10:53:53Z

server/src/main/java/com/cloud/api/query/QueryManagerImpl.java

            sc.addAnd("name", SearchCriteria.Op.EQ, name);
        }
+        if (version != null) {
+            sc.addAnd("version", SearchCriteria.Op.EQ, version);


shall we use "LIKE" for better usage like simply searching for 4.20.3 without "-snapshot".

also for searching 4.20 or 22.0

RosiKyu

LGTM

Key Findings

Version filter is case-insensitive (TC7)
Partial versions don't match - uses EQ operator for exact match only (TC6, TC12)
Filter combines correctly with other parameters (TC3, TC4, TC10)
Backward compatible - APIs return all results when version parameter is omitted (TC5, TC11)

Note on review comments: As suggested by @harikrishna-patnala and @DaanHoogland, using LIKE instead of EQ would allow more flexible searches (e.g., version=4.20 to match all 4.20.x versions). Current implementation requires exact version string.

Test Case Summary

TC	Description	Path	Result
TC1	listHosts - Filter by exact version	API	PASSED
TC2	listHosts - Filter by non-existent version	API	PASSED
TC3	listHosts - Combine version + state filter	API	PASSED
TC4	listHosts - Combine version + zoneid filter	API	PASSED
TC5	listHosts - No version parameter (baseline)	API	PASSED
TC6	listHosts - Partial version (EQ behavior)	API	PASSED
TC7	listHosts - Case sensitivity check	API	PASSED
TC8	listMgmtServers - Filter by exact version	API	PASSED
TC9	listMgmtServers - Filter by non-existent version	API	PASSED
TC10	listMgmtServers - Combine version + id filter	API	PASSED
TC11	listMgmtServers - No version parameter (baseline)	API	PASSED
TC12	listMgmtServers - Partial version (EQ behavior)	API	PASSED

Detailed Test Execution Results:

TC1: listHosts - Filter by exact version

Objective: Verify version filter returns hosts matching exact version string

Expected Result: Returns both KVM hosts (count: 2)

Actual Result:

(localcloud) 🐱 > list hosts version=4.20.3.0-SNAPSHOT type=routing filter=id,name,state,version
{
  "count": 2,
  "host": [
    {
      "id": "7e760736-6211-4fc7-9fec-e0203994d859",
      "name": "ref-trl-10697-k-Mol9-rositsa-kyuchukova-kvm1",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    },
    {
      "id": "f60b9127-0823-4049-90bc-7f0b1079aac7",
      "name": "ref-trl-10697-k-Mol9-rositsa-kyuchukova-kvm2",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    }
  ]
}

TC2: listHosts - Filter by non-existent version

Objective: Verify filter returns empty when version doesn't exist

Expected Result: Empty result

Actual Result:

(localcloud) 🐱 > list hosts version=9.99.99.0 type=routing filter=id,name,state,version
(no output - empty result)

TC3: listHosts - Combine version + state filter

Objective: Verify version filter works combined with state filter

Expected Result: Returns both KVM hosts

Actual Result:

(localcloud) 🐱 > list hosts version=4.20.3.0-SNAPSHOT state=Up type=routing filter=id,name,state,version
{
  "count": 2,
  "host": [
    {
      "id": "7e760736-6211-4fc7-9fec-e0203994d859",
      "name": "ref-trl-10697-k-Mol9-rositsa-kyuchukova-kvm1",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    },
    {
      "id": "f60b9127-0823-4049-90bc-7f0b1079aac7",
      "name": "ref-trl-10697-k-Mol9-rositsa-kyuchukova-kvm2",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    }
  ]
}

TC4: listHosts - Combine version + zoneid filter

Objective: Verify version filter works combined with zoneid filter

Expected Result: Returns both KVM hosts

Actual Result:

(localcloud) 🐱 > list hosts version=4.20.3.0-SNAPSHOT zoneid=de53c48f-9137-4de9-84aa-931ce6eb3999 type=routing filter=id,name,state,version
{
  "count": 2,
  "host": [
    {
      "id": "7e760736-6211-4fc7-9fec-e0203994d859",
      "name": "ref-trl-10697-k-Mol9-rositsa-kyuchukova-kvm1",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    },
    {
      "id": "f60b9127-0823-4049-90bc-7f0b1079aac7",
      "name": "ref-trl-10697-k-Mol9-rositsa-kyuchukova-kvm2",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    }
  ]
}

TC5: listHosts - No version parameter (baseline)

Objective: Verify existing behavior unchanged without version parameter

Expected Result: Returns both hosts

Actual Result:

(localcloud) 🐱 > list hosts type=routing filter=id,name,version
{
  "count": 2,
  "host": [
    {
      "id": "7e760736-6211-4fc7-9fec-e0203994d859",
      "name": "ref-trl-10697-k-Mol9-rositsa-kyuchukova-kvm1",
      "version": "4.20.3.0-SNAPSHOT"
    },
    {
      "id": "f60b9127-0823-4049-90bc-7f0b1079aac7",
      "name": "ref-trl-10697-k-Mol9-rositsa-kyuchukova-kvm2",
      "version": "4.20.3.0-SNAPSHOT"
    }
  ]
}

TC6: listHosts - Partial version (EQ behavior)

Objective: Verify partial version doesn't match (EQ operator)

Expected Result: Empty result

Actual Result:

(localcloud) 🐱 > list hosts version=4.20.3 type=routing filter=id,name,version
(no output - empty result)

TC7: listHosts - Case sensitivity check

Objective: Test if version filter is case-sensitive

Expected Result: Test behavior

Actual Result:

(localcloud) 🐱 > list hosts version=4.20.3.0-snapshot type=routing filter=id,name,version
{
  "count": 2,
  "host": [
    {
      "id": "7e760736-6211-4fc7-9fec-e0203994d859",
      "name": "ref-trl-10697-k-Mol9-rositsa-kyuchukova-kvm1",
      "version": "4.20.3.0-SNAPSHOT"
    },
    {
      "id": "f60b9127-0823-4049-90bc-7f0b1079aac7",
      "name": "ref-trl-10697-k-Mol9-rositsa-kyuchukova-kvm2",
      "version": "4.20.3.0-SNAPSHOT"
    }
  ]
}

Note: Filter is case-insensitive

TC8: listMgmtServers - Filter by exact version

Objective: Verify version filter returns management servers matching exact version

Expected Result: Returns 1 management server

Actual Result:

(localcloud) 🐱 > list managementservers version=4.20.3.0-SNAPSHOT filter=id,name,state,version
{
  "count": 1,
  "managementserver": [
    {
      "id": "ae59e241-6c54-46de-9391-b75aebd1578c",
      "name": "ref-trl-10697-k-mol9-rositsa-kyuchukova-mgmt1.sofia.shapeblue.com",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    }
  ]
}

TC9: listMgmtServers - Filter by non-existent version

Objective: Verify filter returns empty when version doesn't exist

Expected Result: Empty result

Actual Result:

(localcloud) 🐱 > list managementservers version=9.99.99.0 filter=id,name,state,version
(no output - empty result)

TC10: listMgmtServers - Combine version + id filter

Objective: Verify version filter works combined with id filter

Expected Result: Returns the management server

Actual Result:

(localcloud) 🐱 > list managementservers version=4.20.3.0-SNAPSHOT id=ae59e241-6c54-46de-9391-b75aebd1578c filter=id,name,state,version
{
  "count": 1,
  "managementserver": [
    {
      "id": "ae59e241-6c54-46de-9391-b75aebd1578c",
      "name": "ref-trl-10697-k-mol9-rositsa-kyuchukova-mgmt1.sofia.shapeblue.com",
      "state": "Up",
      "version": "4.20.3.0-SNAPSHOT"
    }
  ]
}

TC11: listMgmtServers - No version parameter (baseline)

Objective: Verify existing behavior unchanged without version parameter

Expected Result: Returns 1 management server

Actual Result:

(localcloud) 🐱 > list managementservers filter=id,name,version
{
  "count": 1,
  "managementserver": [
    {
      "id": "ae59e241-6c54-46de-9391-b75aebd1578c",
      "name": "ref-trl-10697-k-mol9-rositsa-kyuchukova-mgmt1.sofia.shapeblue.com",
      "version": "4.20.3.0-SNAPSHOT"
    }
  ]
}

TC12: listMgmtServers - Partial version (EQ behavior)

Objective: Verify partial version doesn't match (EQ operator)

Expected Result: Empty result

Actual Result:

(localcloud) 🐱 > list managementservers version=4.20 filter=id,name,version
(no output - empty result)

Add ability to filter by version for listHosts and listMgmtServers APIs

e2fd343

nvazquez added this to the 4.20.3 milestone Jan 20, 2026

nvazquez requested review from DaanHoogland, abh1sar, kiranchavala, shwstppr, vishesh92 and weizhouapache January 20, 2026 14:22

nvazquez added type:enhancement component:api labels Jan 20, 2026

sureshanaparti approved these changes Jan 20, 2026

View reviewed changes

sureshanaparti added the status:needs-testing label Jan 20, 2026

DaanHoogland approved these changes Jan 21, 2026

View reviewed changes

harikrishna-patnala reviewed Jan 22, 2026

View reviewed changes

RosiKyu self-assigned this Jan 22, 2026

RosiKyu approved these changes Jan 23, 2026

View reviewed changes

RosiKyu added status:testing and removed status:needs-testing labels Jan 23, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add ability to filter by version for listHosts and listMgmtServers APIs #12472

Add ability to filter by version for listHosts and listMgmtServers APIs #12472

Uh oh!

nvazquez commented Jan 20, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 20, 2026 •

edited

Loading

Uh oh!

sureshanaparti left a comment

Uh oh!

sureshanaparti commented Jan 20, 2026

Uh oh!

blueorangutan commented Jan 20, 2026

Uh oh!

blueorangutan commented Jan 20, 2026

Uh oh!

nvazquez commented Jan 21, 2026

Uh oh!

blueorangutan commented Jan 21, 2026

Uh oh!

DaanHoogland left a comment

Uh oh!

blueorangutan commented Jan 21, 2026

Uh oh!

harikrishna-patnala Jan 22, 2026

Uh oh!

DaanHoogland Jan 22, 2026

Uh oh!

RosiKyu left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Add ability to filter by version for listHosts and listMgmtServers APIs #12472

Are you sure you want to change the base?

Add ability to filter by version for listHosts and listMgmtServers APIs #12472

Uh oh!

Conversation

nvazquez commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Types of changes

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Bug Severity

Screenshots (if appropriate):

How Has This Been Tested?

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

Uh oh!

codecov bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

sureshanaparti left a comment

Choose a reason for hiding this comment

Uh oh!

sureshanaparti commented Jan 20, 2026

Uh oh!

blueorangutan commented Jan 20, 2026

Uh oh!

blueorangutan commented Jan 20, 2026

Uh oh!

nvazquez commented Jan 21, 2026

Uh oh!

blueorangutan commented Jan 21, 2026

Uh oh!

DaanHoogland left a comment

Choose a reason for hiding this comment

Uh oh!

blueorangutan commented Jan 21, 2026

Uh oh!

harikrishna-patnala Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

DaanHoogland Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

RosiKyu left a comment

Choose a reason for hiding this comment

LGTM

Key Findings

Test Case Summary

Detailed Test Execution Results:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

nvazquez commented Jan 20, 2026 •

edited

Loading

codecov bot commented Jan 20, 2026 •

edited

Loading