Add Storage TSG: storage pool capacity threshold warning (fixed vs thin volumes)

[AlBurns-MSFT]

What

Adds a Storage TSG explaining the Storage Spaces Direct (S2D) storage pool capacity threshold warning and the supported remediation paths, gated on volume provisioning type (fixed vs thin).

The warning is not a false alarm — S2D needs free pool capacity in reserve so repair jobs can rebuild resiliency after a drive/node loss — but it is frequently misunderstood on clusters using fixed-provisioned volumes, where the pool can sit above the threshold even when the volume's file system is mostly empty.

Highlights

• Step 1 decision gate on ProvisioningType (Fixed vs Thin) to prevent running the thin reclamation procedure on fixed volumes, where it is a no-op.
• Path A (Fixed): add disks, convert to thin, shrink/remove, suppress alert, or raise threshold — each risk-labeled.
• Path B (Thin): Optimize-Volume -SlabConsolidate + ReFS unmap reclamation (no -ReTrim on ReFS), with VM-suspend and CSV owner-node guidance.
• Clarifies the two distinct threshold controls and the reserve-capacity rationale (repair headroom after drive/node loss).

Files

• TSG/Storage/Troubleshoot-Storage-StoragePoolCapacityThreshold.md — new TSG
• TSG/Storage/README.md — registers the TSG in the Storage index

[Copilot]

Pull request overview

Adds a new Storage troubleshooting guide (TSG) to explain and remediate the S2D storage pool capacity threshold warning, with remediation explicitly gated on volume provisioning type (Fixed vs Thin) to avoid ineffective thin-reclamation steps on fixed volumes.

Changes:

• Introduces a new TSG covering why the warning exists, how to determine provisioning type, and safe remediation options for Fixed vs Thin volumes.
• Documents thin-volume reclamation guidance including VM workload handling, CSV owner-node execution guidance, and ReFS-specific notes.
• Registers the new TSG in the Storage README index.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
TSG/Storage/Troubleshoot-Storage-StoragePoolCapacityThreshold.md	New TSG describing the warning, decision gate on provisioning type, remediation paths, and verification steps.
TSG/Storage/README.md	Adds the new TSG link to the Storage index.

[Karl-WE]

Great addition!

[AlBurns-MSFT]

Thanks for the review — addressed all three points in e25447e:

1. Overview/Path B consistency — reworded the overview so reclamation is Optimize-Volume -SlabConsolidate + the ReFS background unmap that frees the slabs; Optimize-StoragePool is described only as the optional rebalance (matching Path B), and aligned the summary-table row.
2. A4 alert scope — called out that the toggle is set at the storage subsystem level, so it suppresses the threshold alert cluster-wide (all pools), not just one pool/volume.
3. Verify cmdlet — swapped Debug-StorageSubSystem for the lightweight Get-HealthFault, consistent with the other Storage TSGs.

[1008covingtonlane]

Reviewed for technical accuracy against Microsoft Learn — high-quality TSG, and the Fixed-vs-Thin decision gate (don't run Optimize-Volume -SlabConsolidate on a fixed volume) is exactly the right framing; it's a frequent real-world misread.

Verified correct against Learn:

• 70% default thin-provisioning alert threshold.
• ~15-minute ReFS background-unmap reclamation wait after -SlabConsolidate.
• Cmdlets: Set-StoragePool -ThinProvisioningAlertThresholds, Set-VirtualDisk -ProvisioningType Thin, Get-VirtualDisk … ProvisioningType.
• -SlabConsolidate (not -ReTrim) on ReFS; Arc-VM stop-from-Azure rather than host Suspend-VM; CSV owner-node / by-path handling; Optimize-StoragePool as rebalance, not the slab-free mechanism.
• Every remediation carries a risk label; A4's subsystem-wide alert scope is clearly warned.

One substantive question inline on Option A2's "23H2 (build 2311.2) or later" conversion requirement — it appears to contradict the 22H2 conversion doc this TSG links. Everything else looks accurate and well-organized. Nice addition.

[1008covingtonlane]

Thanks for the careful Fixed-vs-Thin gating throughout — this is a genuinely useful TSG.

One question on this build requirement: I couldn't find a 2311.2 floor for in-place fixed→thin conversion in either Learn doc this TSG links. The conversion doc cited here (Convert fixed to thin provisioned volumes) documents the in-place Set-VirtualDisk -ProvisioningType Thin + remount flow on Azure Stack HCI 22H2, and the current Storage thin provisioning in Azure Local, version 23H2 doc says conversion is supported with no build gate.

If there's a known regression/issue that makes 2311.2 the real floor, it would be great to cite it here. Otherwise the "on earlier releases, do not attempt the conversion" guidance may send engineers down an unnecessary new-volume-and-migrate path when in-place conversion is documented as supported on 22H2. Happy to be corrected if you've hit a specific build issue.

[AlBurns-MSFT]

Thanks — removing the unvalidated 2311.2 claim.

[1008covingtonlane]

Verified — the revised note is accurate: the Set-VirtualDisk -ProvisioningType Thin + remount procedure is archived under /previous-versions/ due to the Azure Stack HCI → Azure Local rename (not a feature removal), and there's no documented minimum build. The "confirm on the current build, otherwise create-new-and-migrate" caveat is a sensible call. Thanks for the quick turnaround!

[1008covingtonlane]

Approving. Verified the technical content against Microsoft Learn — the 70% default thin-provisioning alert threshold, the ~15-minute ReFS background-unmap reclamation wait, -SlabConsolidate (not -ReTrim) on ReFS, Arc-VM stop-from-Azure, and the CSV owner-node / by-path handling are all accurate. The Copilot bot's three points and the fixed-to-thin build-floor claim are now resolved. Clear, well-structured TSG and a genuinely useful one for the storage-pool capacity threshold misread.

[Karl-WE]

@AlBurns-MSFT @1008covingtonlane is it possible to transfer the technical essence to Windows Server 2025 > Storage > Storage Spaces Docs, too? I believe these Thin Prov. and Slab details are not documented.

[Karl-WE]

@AlBurns-MSFT @1008covingtonlane

next to my request from last week, after internal MVP discussions, I would like to ask you to add these bits to the TSG or AzL documentation.

Admin teams must instantly restrict the provisioning of new virtual disks, freeze automated thin-disk expansion, or prepare to expand the pool.
Avoid using "pause VM".

Reasons:

This can quickly eat up considerable space on a CSV. It adds with all the guidance and warning Patrick outlined in his guidance e.g. audit snapshots or purging stale VHDX.
If VMs deployed, I believe the default stop action is still Save-VM, so a stop-cluster might also initiate this. Then hitting the wall of a full CSV or worse, full pool capacity - reserve.

If the threshold warning is triggered and save state executed, inexperienced or not focused admins might be looking into extending the thin provisioned CSV size for make free space on the CS, not looking at disk and pool utilization. Then a cascade of unfortunate events can or will happen.

Best regards,
Karl Wester-Ebbinghaus

Microsoft MVP Azure Hybrid and Migration /
Windows Server

Message from Patrick, approved for re-used in public for TSG, AzL and S2D documentation.
Below is the guidance I provide.

70% is a "design limit only". The 80% being from the native Storage Spaces Direct Health Service monitoring engine. Microsoft’s health stream automatically flags the pools operational status as Warning at 80%

Capacity Warning (80% Consumption): Triggered automatically when the physical pool consumption hits 80%. This status generates an informational infrastructure log indicating that storage utilisation is approaching design parameters. Operations teams should audit snapshots and identify stale .vhdx files for pruning.

Capacity Critical (90% Consumption): Triggered when physical consumption crosses 90%. This state generates an immediate P2 infrastructure alert. Admin teams must instantly restrict the provisioning of new virtual disks, freeze automated thin-disk expansion, or prepare to expand the pool.

Capacity Block (95% Consumption): The absolute hard threshold. To protect the underlying metadata and file system from corrupting due to zero-byte write capability, the S2D engine places the storage pool into a read-only state, gracefully pausing running guest operating systems to preserve data integrity.

Kind Regards
Patrick Lownds
Solution Architect | HPE Services | Advisory & Professional Services

[AlBurns-MSFT]

Thanks @Karl-WE, and thanks to Patrick for the detailed write-up. The operational intent is spot on: a pool marching toward full is one of the more dangerous states an S2D cluster can be in, and escalating watch-points with defined actions (stop new provisioning, freeze thin growth, expand the pool) are exactly the right runbook. The "don't reach for save/pause when you're already tight on space" point is a great catch and I've built it in.

I opened #312 with these additions. One clarification I worked through so the TSG stays precise about mechanism vs. practice: the in-box Health Service doesn't implement an automatic 80 -> 90 -> 95 pool ladder or a capacity-based read-only. I checked against the Storage Spaces states doc, the Azure Local Health Service settings doc, and the product fault model. What's actually built in:

• 70% is the real, configurable pool capacity alert (PoolCapacityThresholdExceeded, Warning; Set-StoragePool -ThinProvisioningAlertThresholds), plus the reserve-capacity fault. Both advisory.
• The 80 and 90 numbers are the per-volume capacity health settings (System.Storage.Volume.CapacityThreshold.Warning/.Critical), not pool thresholds.
• A pool goes read-only only from quorum loss or an admin policy setting, never from a capacity percentage.
• The VM pause is real, but it's Hyper-V: at actual exhaustion guests go paused-critical (Event 16060) on disk-full, not an S2D 95% block.

So in #312 I captured the 80/90/95 model as a recommended operational runbook (tiered watch-points + admin actions) rather than automatic S2D behavior, so the field doesn't wait for an auto-block that won't come. If you or Patrick have a source for a built-in 95% pool read-only (an HPE monitoring pack, an Azure Monitor rule set, or in-box docs), send it over and I'll fold it in and attribute it correctly.

Separately, on porting the essence to the Windows Server / Azure Local product docs: good idea, that lives in the MicrosoftDocs repos rather than here, so I'll track it as a follow-up.