Hyper-V: Deploying a Two-Node Failover Cluster on a Budget

<#
.SYNOPSIS
    Builds a two-node Storage Spaces Direct Hyper-V cluster with a cloud witness and nested two-way mirror volumes.
.DESCRIPTION
    Checks that both nodes run Datacenter edition and have the same number (four or more) and media types
    of poolable drives, validates with the Storage Spaces Direct test set, creates the cluster without storage,
    configures a cloud witness, enables S2D and creates nested two-way mirror CSV volumes. Prints the
    resulting virtual disks and quorum configuration.
.PARAMETER NodeNames
    The two cluster nodes.
.PARAMETER ClusterName
    NetBIOS name for the cluster, 15 characters or fewer.
.PARAMETER ClusterIPAddress
    Static IPv4 address for the cluster name.
.PARAMETER WitnessAccountName
    Azure storage account (Standard general-purpose v2) for the cloud witness.
.PARAMETER WitnessAccessKey
    Primary access key for that storage account.
.PARAMETER CapacityMediaType
    Media type of the capacity drives: SSD or HDD.
.PARAMETER VolumeNames
    Names of the nested two-way mirror volumes to create.
.PARAMETER VolumeSize
    Size of each volume.
.EXAMPLE
    .\New-TwoNodeS2DCluster.ps1 -NodeNames 'hv-node01', 'hv-node02' -ClusterName 'hv-clu01' -ClusterIPAddress '10.10.10.50' -WitnessAccountName '<storageaccount>' -WitnessAccessKey '<access-key>'
.NOTES
    Author  : Thomas Lasswell (https://www.techcolumnist.com)
    Version : 1.0 (2026-06-03)
    Requires: Windows Server 2019+ Datacenter nodes, FailoverClusters and Storage modules, WinRM
#>

[CmdletBinding()]
param (
    [Parameter(Mandatory = $true)]
    [ValidateCount(2, 2)]
    [string[]]$NodeNames,

    [Parameter(Mandatory = $true)]
    [ValidateLength(1, 15)]
    [string]$ClusterName,

    [Parameter(Mandatory = $true)]
    [string]$ClusterIPAddress,

    [Parameter(Mandatory = $true)]
    [string]$WitnessAccountName,

    [Parameter(Mandatory = $true)]
    [string]$WitnessAccessKey,

    [Parameter(Mandatory = $false)]
    [ValidateSet('SSD', 'HDD')]
    [string]$CapacityMediaType = 'SSD',

    [Parameter(Mandatory = $false)]
    [string[]]$VolumeNames = @('Volume01'),

    [Parameter(Mandatory = $false)]
    [UInt64]$VolumeSize = 1TB
)

$ErrorActionPreference = 'Stop'
$firstNode = $NodeNames[0]

# Pre-flight: edition and drive symmetry.
$inventory = Invoke-Command -ComputerName $NodeNames -ScriptBlock {
    $operatingSystem = Get-CimInstance -ClassName Win32_OperatingSystem
    $poolable = @(Get-PhysicalDisk -CanPool $true)

    [PSCustomObject]@{
        Node          = $env:COMPUTERNAME
        Edition       = $operatingSystem.Caption
        PoolableDisks = $poolable.Count
        MediaTypes    = ($poolable | Group-Object -Property MediaType | Sort-Object -Property Name | ForEach-Object { "$($_.Name) x$($_.Count)" }) -join ', '
    }
}

$inventory | Format-Table -Property Node, Edition, PoolableDisks, MediaTypes -AutoSize

if ($inventory | Where-Object { $_.Edition -notmatch 'Datacenter' }) {
    throw 'Storage Spaces Direct requires Windows Server Datacenter edition on every node.'
}

if (@($inventory.MediaTypes | Sort-Object -Unique).Count -ne 1) {
    throw 'The nodes have different numbers or types of poolable drives. S2D expects the same number and type in every server.'
}

if ($inventory | Where-Object { $_.PoolableDisks -lt 4 }) {
    throw 'Fewer than four poolable drives on a node. Windows Server needs at least four capacity drives per server.'
}

# Validate with the S2D test set, as the Microsoft deployment guide does.
$report = Test-Cluster -Node $NodeNames -Include 'Storage Spaces Direct', 'Inventory', 'Network', 'System Configuration'
Write-Output "Validation report: $(($report | Where-Object { $_ -is [System.IO.FileInfo] }).FullName)"

# Create the cluster without storage, then the witness, then S2D.
if (-not (Get-Cluster -Name $firstNode -ErrorAction SilentlyContinue)) {
    New-Cluster -Name $ClusterName -Node $NodeNames -StaticAddress $ClusterIPAddress -NoStorage | Out-Null
}

Set-ClusterQuorum -Cluster $firstNode -CloudWitness -AccountName $WitnessAccountName -AccessKey $WitnessAccessKey | Out-Null

if (-not (Get-StoragePool -CimSession $firstNode -IsPrimordial $false -ErrorAction SilentlyContinue)) {
    Enable-ClusterStorageSpacesDirect -CimSession $firstNode -Confirm:$false | Out-Null
}

# Nested two-way mirror tier template (required on Windows Server 2019, harmless if already present).
$mirrorTier = "NestedMirrorOn$CapacityMediaType"

if (-not (Get-StorageTier -CimSession $firstNode -FriendlyName $mirrorTier -ErrorAction SilentlyContinue)) {
    New-StorageTier -CimSession $firstNode -StoragePoolFriendlyName 'S2D*' -FriendlyName $mirrorTier -ResiliencySettingName Mirror -MediaType $CapacityMediaType -NumberOfDataCopies 4 | Out-Null
}

# With HDD capacity (storage bus cache), stop caching writes once a node has been down for 30 minutes.
if ($CapacityMediaType -eq 'HDD') {
    Get-StorageSubSystem -CimSession $firstNode -FriendlyName 'Cluster*' |
        Set-StorageHealthSetting -Name 'System.Storage.NestedResiliency.DisableWriteCacheOnNodeDown.Enabled' -Value 'True'
}

# New-Volume on S2D creates the virtual disk, formats it and adds it to Cluster Shared Volumes.
foreach ($volumeName in $VolumeNames) {
    if (-not (Get-VirtualDisk -CimSession $firstNode -FriendlyName $volumeName -ErrorAction SilentlyContinue)) {
        New-Volume -CimSession $firstNode -StoragePoolFriendlyName 'S2D*' -FriendlyName $volumeName -FileSystem CSVFS_ReFS -StorageTierFriendlyNames $mirrorTier -StorageTierSizes $VolumeSize | Out-Null
    }
}

Get-VirtualDisk -CimSession $firstNode |
    Format-Table -Property FriendlyName, ResiliencySettingName, OperationalStatus, HealthStatus, Size -AutoSize

Get-ClusterQuorum -Cluster $firstNode | Format-List -Property Cluster, QuorumResource

<#
.SYNOPSIS
    Times a planned drain or an unplanned node loss on a two-node S2D cluster, then times the storage resync.
.DESCRIPTION
    Refuses to start unless every virtual disk is Healthy. In planned mode it drains the target node,
    restarts it and resumes it with immediate failback; on Windows Server 2019 it puts the node's disks in
    storage maintenance mode before the restart and takes them out before the resume (2022 and later do this
    automatically). In unplanned mode the clock starts when the operator presses Enter, just before pulling
    power on the target node. It records how long until every clustered role is online on a surviving node,
    then how long until Get-StorageJob reports no repair jobs and every virtual disk is Healthy again.
.PARAMETER ClusterName
    The cluster to test.
.PARAMETER NodeName
    The node to take down.
.PARAMETER Unplanned
    Wait for the operator to cut power instead of draining and restarting the node.
.PARAMETER TimeoutMinutes
    How long to wait for each phase before giving up.
.EXAMPLE
    .\Test-TwoNodeFailover.ps1 -ClusterName 'hv-clu01' -NodeName 'hv-node02' -Unplanned
.NOTES
    Author  : Thomas Lasswell (https://www.techcolumnist.com)
    Version : 1.0 (2026-06-03)
    Requires: FailoverClusters and Storage modules; run from a machine that is not in the cluster
#>

[CmdletBinding()]
param (
    [Parameter(Mandatory = $true)]
    [string]$ClusterName,

    [Parameter(Mandatory = $true)]
    [string]$NodeName,

    [switch]$Unplanned,

    [Parameter(Mandatory = $false)]
    [int]$TimeoutMinutes = 60
)

$ErrorActionPreference = 'Stop'
$survivor = (Get-ClusterNode -Cluster $ClusterName | Where-Object { $_.Name -ne $NodeName }).Name

$unhealthy = Get-VirtualDisk -CimSession $survivor | Where-Object { $_.HealthStatus -ne 'Healthy' }

if ($unhealthy) {
    throw "Not safe to take a node down: $($unhealthy.FriendlyName -join ', ') not Healthy."
}

# Windows Server 2019 (build 17763) needs storage maintenance mode set by hand; 2022 (build 20348) and later do it on drain.
$manualStorageMaintenance = [int](Get-CimInstance -ClassName Win32_OperatingSystem -ComputerName $NodeName).BuildNumber -lt 20348

$roles = Get-ClusterGroup -Cluster $survivor | Where-Object { $_.Name -notin 'Cluster Group', 'Available Storage' }
Write-Output "Testing $($roles.Count) clustered roles; $NodeName goes down, $survivor survives"

$clock = [System.Diagnostics.Stopwatch]::StartNew()

if ($Unplanned) {
    Read-Host "Press Enter, then pull power on $NodeName immediately"
    $clock.Restart()
} else {
    Suspend-ClusterNode -Cluster $survivor -Name $NodeName -Drain -Wait | Out-Null
    Write-Output "Drain finished after $([int]$clock.Elapsed.TotalSeconds)s"

    if ($manualStorageMaintenance) {
        Get-StorageScaleUnit -CimSession $survivor -FriendlyName $NodeName | Enable-StorageMaintenanceMode
    }

    Restart-Computer -ComputerName $NodeName -Force
}

# Phase 1: every role online on the survivor.
do {
    Start-Sleep -Seconds 5
    $pending = Get-ClusterGroup -Cluster $survivor |
        Where-Object { $_.Name -notin 'Cluster Group', 'Available Storage' } |
        Where-Object { $_.State -ne 'Online' -or $_.OwnerNode.Name -ne $survivor }
} while ($pending -and $clock.Elapsed.TotalMinutes -lt $TimeoutMinutes)

Write-Output "Roles online on $survivor after $([int]$clock.Elapsed.TotalSeconds)s; still pending: $(@($pending).Count)"

# Wait for the node to come back before measuring resync.
Read-Host "Press Enter once $NodeName is powered on and shows Up or Paused in Get-ClusterNode"

if (-not $Unplanned) {
    if ($manualStorageMaintenance) {
        Get-StorageScaleUnit -CimSession $survivor -FriendlyName $NodeName | Disable-StorageMaintenanceMode
    }

    Resume-ClusterNode -Cluster $survivor -Name $NodeName -Failback Immediate | Out-Null
}

# Phase 2: storage resync.
$clock.Restart()

do {
    Start-Sleep -Seconds 30
    $jobs = @(Get-StorageJob -CimSession $survivor | Where-Object { $_.JobState -eq 'Running' })
    $degraded = @(Get-VirtualDisk -CimSession $survivor | Where-Object { $_.HealthStatus -ne 'Healthy' })
    Write-Verbose "$($jobs.Count) repair job(s) running, $($degraded.Count) volume(s) not Healthy"
} while (($jobs.Count -gt 0 -or $degraded.Count -gt 0) -and $clock.Elapsed.TotalMinutes -lt $TimeoutMinutes)

Write-Output "Storage resync finished after $([int]$clock.Elapsed.TotalMinutes) minutes"