PowerShell: Hyper-V – Automate VM Checkpoints Before Patch Tuesday

.\New-PrePatchCheckpoint.ps1 -Verbose

.\New-PrePatchCheckpoint.ps1 -ClusterName 'hv-clu01' -VMName 'app-svr01', 'app-svr02', 'sql-svr01' -RetentionDays 2

VM         Host       Action   Checkpoint              CheckpointType
--         ----       ------   ----------              --------------
app-svr01  HV-NODE01  Removed  PatchTuesday-2025-09-09 Production
app-svr01  HV-NODE01  Created  PatchTuesday-2025-10-15 Production
app-svr02  HV-NODE02  Created  PatchTuesday-2025-10-15 Production
sql-svr01  HV-NODE02  Failed   PatchTuesday-2025-10-15 ProductionOnly

.\New-PrePatchCheckpoint.ps1 -ClusterName 'hv-clu01' -WhatIf

$parameters = @{
    ClusterName           = 'hv-clu01'
    CauPluginName         = 'Microsoft.WindowsUpdatePlugin'
    PreUpdateScript       = 'C:\ClusterStorage\Volume1\Scripts\New-PrePatchCheckpoint.ps1'
    MaxFailedNodes        = 1
    MaxRetriesPerNode     = 3
    RequireAllNodesOnline = $true
    Force                 = $true
}
Invoke-CauRun @parameters

<#
.SYNOPSIS
    Creates a dated pre-patch checkpoint on running Hyper-V VMs and prunes the ones earlier runs created.
.DESCRIPTION
    Finds the target VMs (every running VM on the local host, on a list of hosts, or on every Up node of a
    failover cluster, optionally filtered by name), removes this script's own checkpoints older than the
    retention window, then takes a checkpoint named <prefix>-<yyyy-MM-dd> using each VM's configured
    checkpoint type. Returns one object per action. A failure on one VM is reported and the run continues,
    so the script is safe to use as a Cluster-Aware Updating pre-update script.
.PARAMETER VMName
    Names of VMs to checkpoint. Defaults to every running VM on the target hosts.
.PARAMETER ComputerName
    Hyper-V hosts to target. Defaults to the local computer. Ignored when ClusterName is set.
.PARAMETER ClusterName
    Failover cluster whose nodes (those that are Up) are all targeted.
.PARAMETER RetentionDays
    Checkpoints created by this script and older than this many days are removed before new ones are taken.
.PARAMETER CheckpointPrefix
    Prefix used to name and identify this script's checkpoints.
.PARAMETER RequirePatchWeek
    Exit unless today falls in the seven days starting on this month's second Tuesday.
.EXAMPLE
    .\New-PrePatchCheckpoint.ps1 -ClusterName 'hv-clu01' -VMName 'app-svr01', 'app-svr02' -RetentionDays 2
.NOTES
    Author  : Thomas Lasswell (https://www.techcolumnist.com)
    Version : 1.0 (2025-10-15)
    Requires: Hyper-V PowerShell module; FailoverClusters module for -ClusterName
#>

[CmdletBinding(SupportsShouldProcess = $true)]
param (
    [Parameter(Mandatory = $false)]
    [string[]]$VMName,

    [Parameter(Mandatory = $false)]
    [string[]]$ComputerName = $env:COMPUTERNAME,

    [Parameter(Mandatory = $false)]
    [string]$ClusterName,

    [Parameter(Mandatory = $false)]
    [ValidateRange(0, 365)]
    [int]$RetentionDays = 7,

    [Parameter(Mandatory = $false)]
    [string]$CheckpointPrefix = 'PatchTuesday',

    [switch]$RequirePatchWeek
)

function Get-PatchTuesday {
    param (
        [datetime]$Date
    )

    # Second Tuesday of the month: find the first Tuesday, then add a week.
    $firstOfMonth = [datetime]::new($Date.Year, $Date.Month, 1)
    $daysToTuesday = ([int][System.DayOfWeek]::Tuesday - [int]$firstOfMonth.DayOfWeek + 7) % 7

    return $firstOfMonth.AddDays($daysToTuesday + 7)
}

$now = Get-Date

if ($RequirePatchWeek) {
    $patchTuesday = Get-PatchTuesday -Date $now

    if ($now.Date -lt $patchTuesday -or $now.Date -ge $patchTuesday.AddDays(7)) {
        Write-Verbose "Today is outside the patch week that starts $($patchTuesday.ToString('yyyy-MM-dd')); nothing to do"
        return
    }
}

# Work out which hosts to query.
$targetHosts = if ($ClusterName) {
    (Get-ClusterNode -Cluster $ClusterName | Where-Object { $_.State -eq 'Up' }).Name
} else {
    $ComputerName
}

# Get-VM with no host falls back to the local computer, so stop rather than checkpoint the wrong machine.
if ($ClusterName -and -not $targetHosts) {
    throw "No nodes of cluster $ClusterName are Up."
}

$allVMs = Get-VM -ComputerName $targetHosts

$targetVMs = if ($VMName) {
    $allVMs | Where-Object { $VMName -contains $_.Name }
} else {
    $allVMs | Where-Object { $_.State -eq 'Running' }
}

foreach ($name in $VMName) {
    if ($targetVMs.Name -notcontains $name) {
        Write-Warning "VM '$name' was not found on $($targetHosts -join ', ')"
    }
}

$checkpointName = '{0}-{1:yyyy-MM-dd}' -f $CheckpointPrefix, $now
$cutoffDate = $now.AddDays(-$RetentionDays)

foreach ($vm in $targetVMs) {
    if ("$($vm.CheckpointType)" -eq 'Disabled') {
        Write-Warning "Checkpoints are disabled on $($vm.Name), skipping"
        continue
    }

    if ("$($vm.CheckpointType)" -eq 'Standard') {
        Write-Warning "$($vm.Name) uses standard checkpoints, which capture memory state and are not application consistent"
    }

    # Remove this script's own expired checkpoints before creating a new one.
    $oldCheckpoints = Get-VMSnapshot -VM $vm |
        Where-Object { $_.Name -like "$CheckpointPrefix-*" -and $_.CreationTime -lt $cutoffDate }

    foreach ($old in $oldCheckpoints) {
        if ($PSCmdlet.ShouldProcess("$($vm.Name) on $($vm.ComputerName)", "Remove checkpoint '$($old.Name)'")) {
            Write-Verbose "Removing expired checkpoint '$($old.Name)' on $($vm.Name)"
            $removeAction = 'Removed'

            try {
                Remove-VMSnapshot -VMSnapshot $old -ErrorAction Stop
            } catch {
                Write-Warning "Removing checkpoint '$($old.Name)' from $($vm.Name) failed: $($_.Exception.Message)"
                $removeAction = 'Failed'
            }

            [PSCustomObject]@{
                VM             = $vm.Name
                Host           = $vm.ComputerName
                Action         = $removeAction
                Checkpoint     = $old.Name
                CheckpointType = "$($vm.CheckpointType)"
            }
        }
    }

    $existing = Get-VMSnapshot -VM $vm -Name $checkpointName -ErrorAction SilentlyContinue

    if ($existing) {
        Write-Verbose "Checkpoint '$checkpointName' already exists on $($vm.Name), skipping"
        continue
    }

    if ($PSCmdlet.ShouldProcess("$($vm.Name) on $($vm.ComputerName)", "Create checkpoint '$checkpointName'")) {
        Write-Verbose "Creating checkpoint '$checkpointName' on $($vm.Name)"
        $action = 'Created'

        try {
            Checkpoint-VM -VM $vm -SnapshotName $checkpointName -ErrorAction Stop
        } catch {
            Write-Warning "Checkpoint of $($vm.Name) failed: $($_.Exception.Message)"
            $action = 'Failed'
        }

        [PSCustomObject]@{
            VM             = $vm.Name
            Host           = $vm.ComputerName
            Action         = $action
            Checkpoint     = $checkpointName
            CheckpointType = "$($vm.CheckpointType)"
        }
    }
}