Skip to content

Hyper V Cluster Shared Volumes PR Review

Ed Mozley edited this page Nov 15, 2026 · 1 revision

Cluster Shared Volumes on Assets β†’ Servers - PR review

PR #351 by Dr4inder Β· Closes #296 Β· Follows #199 Β· Verdict: merge, with fixes Β· 5.4.0

The Hyper-V collector reported every VM's disks, but a VM's VHDX sizes say nothing about how big the shared cluster storage under them is, or how full - and Assets β†’ Servers said Storage (Cluster Shared Volumes) is not collected yet. The collector (now version 1.1.0) has a new -IncludeStorage switch, off by default. With it, it reads Get-ClusterSharedVolume once per cluster and sends every partition - name, path, filesystem, state, coordinator node, total / free / used bytes - as an optional storage_volumes section, with its own completeness and error per cluster. Servers shows the volumes grouped by connection and cluster, and GET /virtual-estate/{id} returns them. On top, at my request, a collector that stops reporting is no longer silent: Servers says so in words, and an hourly job tells the people who manage Hyper-V in the bell. User page: Hyper-V and Failover Clusters. Internals: Hyper-V discovery - Developer Guide Β§8 and Β§9.

Dr4inder agreed the scope on #296 before writing a line, with seven correctness cases set out in advance - identity, counting once per cluster, null versus zero, a failed read, per-cluster completeness, old collectors and redaction. Every one of them is in the code and in the tests. That is the part that usually goes wrong, and it did not.

What was checked

Question Result
Is a volume recognised by its name? No - by the cluster, the CSV resource id and the partition name (sha256 of the three), so a rename or a new coordinator node is the same row
Is shared storage counted once? Yes - one read per cluster, not per node, and never summed from VM disk sizes
Unknown capacity Stays null; 0 free is a real value; free greater than total is dropped to null; used is worked out only from a valid total and free pair
A failed CSV read Keeps the last good figures, marked not confirmed, with the read's own error. It never empties the inventory and never touches the VMs read in the same report - storage errors are kept out of the report's top-level unreadable list on purpose
One cluster failing beside another reading Each cluster has its own savepoint; a good cluster's volumes are applied, the bad one's kept
An older report under a different scope Turned away per cluster by storage_last_attempted_at, which moves on failed reads too, so it cannot bring back older facts
An old collector, or a run without -IncludeStorage No storage section - stored storage is left exactly as it was
An upgraded install before Database Verification Not safe as submitted: storage was read and written with no check that the table existed. Fixed (fix 1)
Redaction -Redact covers the new names, ids, coordinator nodes and paths
A collector that goes quiet Nothing told anyone. Built on merge (fixes 3 and 4)

On the test install: tests/virtual-estate-storage.php (Dr4inder's, extended on merge with the retention, Database-Verification and watch cases) and tests/virtual-estate-storage-browser.php (the Servers page in headless Chrome - light and dark, a 360px phone, a keyboard-scrollable table, escaped text, the empty, unknown and failed states); the existing tests/virtual-estate.php still passes. Dr4inder also checked Database Verification on a copy of an existing database (one table and three columns added, nothing removed) and parsed the collector in Windows PowerShell 5.1 and PowerShell 7.

What was changed on merge

  1. Nothing reads or writes storage before Database Verification. An upgraded install runs the new code before anyone runs it. VirtualEstateService::storageReady() now guards every storage query: Servers says Storage not collected, the REST read gives 0 and [], retention leaves storage alone, and a report's storage section alone fails - 207, Run Database Verification to accept storage - while its VMs still apply.
  2. Storage volumes follow the VMs' retention rule (decided below). A volume not seen for longer than the connection's Remove VMs not seen for setting is removed, and so are the volumes of a cluster that is itself being removed. A cluster is now kept only while it still has volumes - as submitted, a cluster with volumes was kept for ever.
  3. An Overdue connection, and storage that keeps failing, are said in words on Servers: No report for N hours - check the collector's scheduled task., and on a cluster Storage could not be read in the last N reports, since ... (new storage_failing_since and storage_failed_runs). A pill alone was easy to miss.
  4. The collector alert. A new hourly background job, Hyper-V collector watch (virt_watch, cron/virt_watch.php, started by the built-in scheduler while any connection is switched on), puts one notification in the bell of everyone with Assets, the Hyper-V capability and the connection's company when a connection goes Overdue, or a cluster's storage fails two reports in a row. Not repeated until it recovers (virt_connections.stale_alerted_at, virt_clusters.storage_alerted_at), then cleared, so the next failure tells them again. New notification type hyperv.collector, on by default, switchable in Preferences, opening Assets β†’ Servers.
  5. A silent collector can never clean anything up. Retention only ever runs inside a report that is neither stale nor a replay, so no report, or an old one, removes nothing. Tested.
  6. -IncludeStorage in the script's help, saying to switch it on only after upgrading and running Database Verification.
  7. A refused Get-ClusterSharedVolume is logged once, not twice.
  8. A cluster with no name shows its id on Servers and in the alert, rather than a blank.
  9. Deleting a connection deletes its storage explicitly, so it never depends on Database Verification having added the foreign key.
  10. The unused storage_limit string (not collected yet) is gone from every locale.
  11. The browser test kills Chrome's whole process tree on Windows, so a run cannot leave headless Chrome behind.
  12. Changelog ids #2939 (the feature) and #2940 (the merge fixes and the alert); this write-up, the user page, the developer guide, the in-app help, Feature Bingo cards and Dr4inder's entry on the Contributors page.

Merged with git merge --no-ff under the contributor's name; the fixes are in the merge commit (21fdd2177).

Decided

  • Approved as scoped on #296: storage objects in the shared virtual-estate model, not Hyper-V-only tables and not dressed up as VMs; identity from resource and partition ids; failures per cluster; old collectors leave storage alone (Ed, 2026-11-14).
  • Storage volumes follow the connection's retention rule, like VMs (Ed, 2026-11-15).
  • An alert when the collector has a problem (Ed, 2026-11-15): a warning on Assets β†’ Servers, and one notification to the analysts with Assets and the Hyper-V capability in that company when a connection goes overdue or a cluster's storage fails two reports in a row - one failed read can be a blip. Cleared on recovery. A stale or old report never cleans anything up.

Worth knowing

  • Run Database Verification after upgrading, then add -IncludeStorage. Verification adds virt_storage_volumes, six storage columns on virt_clusters and stale_alerted_at on virt_connections. A collector that sends storage first gets a 207 for that section only.
  • Storage is not dependencies. Nothing links a VM to the CSV its disks sit on, and impact analysis is unchanged - VM-to-CSV dependencies, Storage Spaces Direct, SAN and SMB topology were left out of scope on purpose.
  • A connection that has never reported is not alerted. It is usually one still being set up; System β†’ Background jobs shows it as Never seen.
  • The alert is not a monitor. It tells the people who manage the collector that the collector needs attention. It never raises a ticket or touches a status page.
  • Still not run on a real estate. Like the rest of the collector, -IncludeStorage was reviewed and syntax-parsed, not executed - the property names it reads (SharedVolumeInfo, Partition.Name, Size, FreeSpace) are Microsoft's documented ones. The warning at the top of the user page still stands.

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally