Upgrade Azure Stack HCI OS via PowerShell

This article describes how to upgrade the Azure Stack HCI operating system (OS) from version 20349.xxxx (22H2) to version 25398.xxxx (23H2), via PowerShell. This is the first step in the upgrade process, which upgrades only the OS.

Upgrade via PowerShell is the recommended method. There are other methods to upgrade the OS to version 25398.xxxx (23H2) that include using Windows Admin Center and the Server Configuration tool (SConfig). For more information about these methods, see Upgrade the Azure Stack HCI OS, version 22H2 OS via Windows Admin Center and Upgrade Azure Local to new OS using other methods.

This article describes how to upgrade the Azure Stack HCI operating system (OS) to version 26100.xxxx (24H2), via PowerShell. There are two upgrade paths available:

• Upgrade from version 20349.xxxx (22H2) to version 26100.xxxx (24H2).
• Upgrade from version 25398.xxxx (23H2) to version 26100.xxxx (24H2). This includes the 25398.xxxx (23H2) clusters that were upgraded from version 20349.xxxx (22H2) and the solution upgrade is not yet applied.

With the 2505 release, a direct upgrade path from version 20349.xxxx (22H2) to version 26100.xxxx (24H2) is available. Skipping the upgrade to the version 26100.xxxx is one less upgrade hop and helps reduce reboots and maintenance planning prior to the solution upgrade.

• Make sure to consult with your hardware vendor to determine if version 26100.xxxx OS is supported before performing the upgrade.
• After the OS upgrade, you can wait for the solution upgrade to become available.
• There is an exception to the preceding recommendation if you are using stretch clusters. Stretch clusters should wait to directly move to version 26100.xxxx (24H2).

For more information about the various upgrade paths, see the blog post on Upgrade Azure Local to new OS version.

About End of Support (EOS) for version 22H2

Azure Stack HCI OS version 22H2 is already out of support.

• Monthly security and quality updates have stopped.
• Your system continues to work, including registration and repair.
• Billing has continued.
• Microsoft Support is available only for upgrade assistance.

To continue receiving updates, we recommend upgrading your operating system based on guidance provided in this article.

If you're running an Azure Stack HCI, version 22H2 stretch cluster or managing the cluster via System Center Virtual Machine Manager, review the Supported workloads and configurations table for update timelines.

About End of Support (EOS) for version 23H2

The Azure Stack HCI operating system update is available via the Windows Update and via the media that you can download from the Azure portal.

To upgrade the OS on your system, follow these high-level steps:

1. Complete the prerequisites.
2. Update registry keys.
3. Connect to Azure Local, version 22H2.Check for the available updates using PowerShell.
4. Install new OS using PowerShell.
5. Check the status of the updates.
6. After the OS is upgraded, perform post-OS upgrade steps.

The Azure Stack HCI OS update is available only via the Azure portal.

To upgrade the OS on your system, follow these high-level steps:

1. Complete the prerequisites.
2. Update registry keys.
3. Install new OS using PowerShell.
4. Check the status of the updates.
5. After the OS is upgraded, perform post-OS upgrade steps.

Before you begin, make sure that:

• You have access to an Azure Local instance running version 22H2, and it's registered in Azure.

• All the machines in your Azure Local, version 22H2 instance are healthy and show as Online.

• You have shut down virtual machines (VMs). We recommend that you shut down VMs before performing the OS upgrade to prevent unexpected outages and damages to databases.

• You have access to the Azure Stack HCI, version 23H2 OS software update for Azure Local. This update is available via Windows Update or as a downloadable media. The media must be version 2503 ISO file that you can download from the Azure portal.

• You have access to a client that can connect to your Azure Local instance. This client should be running PowerShell 5.0 or later.

• You run the RepairRegistration cmdlet only if both of the following conditions apply:

  • The identity property is either missing or doesn’t contain type = "SystemAssigned".
    • Check this in the Resource JSON in the Azure portal
    • Or run the Get-AzResource -Name <cluster_name> PowerShell cmdlet
  • The Cloud Management cluster group is not present. Check it by running the Get-ClusterGroup PowerShell cmdlet.

  If both these conditions are met, run the RepairRegistration cmdlet:

  Register-AzStackHCI -TenantId "<tenant_ID>" -SubscriptionId "<subscription_ID>" -ComputerName "<computer_name>" -RepairRegistration
  

• (Recommended) You enable Secure Boot on Azure Local machines before you upgrade the OS. To enable Secure Boot, follow these steps:

  1. Drain the cluster node.
  2. Restart the OS.
  3. Enter the BIOS/UEFI menu.
  4. Review the Boot or Security section of the UEFI configuration options Locate the Secure Boot option.
  5. Set the option to Enabled or On.
  6. Save the changes and restart your computer.

  Consult with your hardware vendor for assistance if required.

• Make sure your Azure Local system is running either OS version 20349.3692 or OS version greater than 25398.1611.

• Make sure the system is registered in Azure and all the machines in the system are healthy and online.

• Make sure to shut down virtual machines (VMs). We recommend shutting down VMs before performing the OS upgrade to prevent unexpected outages and damages to databases.

• Confirm that you have access to the Azure Local 2505 ISO file, which you can download from the Azure portal.

• Consult your hardware OEM to verify driver compatibility. Confirm that all drivers compatible with Windows Server 2025 or Azure Stack HCI OS, 26100.xxxx are installed before the upgrade.

• Make sure the Network Interface Card (NIC) driver currently installed on your system is newer than the version included by default (inbox) with Azure Stack HCI OS, version 26100.xxxx. The following table compares the current and recommended versions of NIC drivers for two manufacturers:

  NIC manufacturer	Inbox driver version	Recommended latest compatible driver
  Intel	1.15.121.0	1.17.73.0
  NVIDIA	24.4.26429.0	25.4.50020

• Ensure the instance is properly registered. If the identity property is missing or doesn’t contain type = "SystemAssigned", run the following command to repair the registration:

  Register-AzStackHCI -TenantId "<tenant_ID>" -SubscriptionId "<subscription_ID>" -ComputerName "<computer_name>" -RepairRegistration
  

  You can verify the identity property in the Azure portal in resource's JSON or by running the following cmdlet:

  Get-AzResource -Name <cluster_name> -ResourceGroupName <name of the resource group> -ResourceType "Microsoft.AzureStackHCI/clusters" -ExpandProperties
  

• (Recommended) Enable Secure Boot on Azure Local machines before you upgrade the OS. To enable Secure Boot, follow these steps:

  1. Drain the cluster node.
  2. Restart the OS.
  3. Enter the BIOS/UEFI menu.
  4. Review the Boot or Security section of the UEFI configuration options Locate the Secure Boot option.
  5. Set the option to Enabled or On.
  6. Save the changes and restart your computer.

  Consult with your hardware vendor for assistance if required.

• Clean the Cloud Management cluster group:

  # Check to make sure the Cloud Management group is present and its online.
  Get-ClusterGroup -Name "Cloud Management"
  
  # Stop the Cloud Management group
  Stop-ClusterGroup -Name "Cloud Management"
  
  # Remove all resources in the Cloud Management group
  Get-ClusterGroup -Name "Cloud Management" | Get-ClusterResource | Remove-ClusterResource -Force
  
  # Start the Cloud Management group
  Start-ClusterGroup -Name "Cloud Management"
  
  
  

To ensure Resilient File System (ReFS) and live migrations function properly during and after OS upgrade, follow these steps on each machine in the system to update registry keys. Reboot each machine for the changes to take effect.

1. Set RefsEnableMetadataValidation to 0:

   Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "RefsEnableMetadataValidation" -Value 0 -Type DWord  -ErrorAction Stop
   

2. Create the parameters key if it doesn't exist. If it already exists, the command may fail with an error, which is expected.

   New-Item -Path HKLM:\SYSTEM\CurrentControlSet\Services\Vid\Parameters
   

3. Set SkipSmallLocalAllocations to 0:

   New-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\Vid\Parameters -Name SkipSmallLocalAllocations -Value 0 -PropertyType DWord
   

4. Restart the machine for the changes to take effect. On machine restart, if the RefsEnableMetadataValidation key gets overridden and ReFS volumes fail to come online, toggle the key by first setting RefsEnableMetadataValidation to 1 and then back to 0 again.

5. Update and verify that the registry keys have been applied on each machine in the system before moving to the next step.

To ensure Resilient File System (ReFS) functions properly during and after OS upgrade, follow these steps on each machine in the system to update registry keys. Reboot each machine for the changes to take effect.

1. Set RefsEnableMetadataValidation to 0:

   Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "RefsEnableMetadataValidation" -Value 0 -Type DWord  -ErrorAction Stop
   

2. Restart the machine to apply changes. If ReFS volumes fail to come online after reboot and the RefsEnableMetadataValidation key is reset, toggle the key. Set RefsEnableMetadataValidation to 1 and then back to 0. To check volume status, run the Get-ClusterSharedVolumeState command.

3. Update and verify that the registry keys have been applied on each machine in the system before moving to the next step.

To install the new OS using PowerShell, follow these steps:

1. Run the following cmdlets on every machine in the system.

   Set-WSManQuickConfig
   Enable-PSRemoting
   

2. To test whether the system is properly set up to apply software updates using Cluster-Aware Updating (CAU), run the Test-CauSetup cmdlet, which notifies you of any warnings or errors:

   Test-CauSetup -ClusterName <System name>
   

3. Validate the hardware and settings by running the Test-Cluster cmdlet on one of the machines in the system. If any of the condition checks fail, resolve them before proceeding to the next step.

   Test-Cluster
   

4. Check for the available updates:

   Invoke-CauScan -ClusterName <SystemName> -CauPluginName "Microsoft.RollingUpgradePlugin" -CauPluginArguments @{'WuConnected'='true';} -Verbose | fl *
   

   Inspect the output of the above cmdlet and verify that each machine is offered the same Feature Update, which should be the case.

5. You need a separate machine or VM outside the system to run the Invoke-CauRun cmdlet from. A separate machine ensures that orchestration isn't interrupted when the machines are rebooted.

   Important

   The system on which you run Invoke-CauRun must be running Windows Server 2022.

   Invoke-CauRun -ClusterName <SystemName> -CauPluginName "Microsoft.RollingUpgradePlugin" -CauPluginArguments @{'WuConnected'='true';} -Verbose -EnableFirewallRules -Force
   

6. If the system isn't connected to Windows Update and the Azure Local install media is available on a local share, CAU can also be used to upgrade the system. Be sure to update the 'PathToSetupMedia' parameter with the share path to the ISO image.

   Invoke-CauRun –ClusterName <SystemName> -CauPluginName Microsoft.RollingUpgradePlugin -CauPluginArguments @{ 'WuConnected'='false';'PathToSetupMedia'='\some\path\'; 'UpdateClusterFunctionalLevel'='true'; } -Force
   

7. Check for any further updates and install them.

Wait for the update to complete and check the status of the update.

To install the new OS using PowerShell, follow these steps:

1. Run the following cmdlets on every machine in the system.

   Set-WSManQuickConfig
   Enable-PSRemoting
   

2. To test whether the system is properly set up to apply software updates using Cluster-Aware Updating (CAU), run the Test-CauSetup cmdlet, which notifies you of any warnings or errors:

   Test-CauSetup -ClusterName <System name>
   

3. Validate the hardware and settings by running the Test-Cluster cmdlet on one of the machines in the system. If any of the condition checks fail, resolve them before proceeding to the next step.

   Test-Cluster
   

4. Extract the contents of the ISO image and copy them to the local system drive on each machine. Ensure that the local path is the same on each machine. Then, update the PathToSetupMedia parameter with the local path to the ISO image.

   # Define ISO and destination paths 
   $isoFilePath = "C:\SetupFiles\WindowsServer\ISOs\example.iso" 
   $destinationPath = "C:\SetupFiles\WindowsServer\Files" 
   # Mount the ISO file 
   $iso = Mount-DiskImage -ImagePath $isoFilePath 
   # Get the drive letter 
   $driveLetter = ($iso | Get-Volume).DriveLetter 
   # Create the destination directory 
   New-Item -ItemType Directory -Path $destinationPath 
   # Copy contents to the local directory 
   Copy-Item -Path "${driveLetter}:\*" -Destination $destinationPath –Recurse 
   # Dismount the ISO file 
   Dismount-DiskImage -ImagePath $isoFilePath
   

5. Upgrade the system.

   Invoke-CauRun –ClusterName <SystemName> -CauPluginName Microsoft.RollingUpgradePlugin  -EnableFirewallRules -CauPluginArguments @{ 'WuConnected'='false';'PathToSetupMedia'='\some\path\'; 'UpdateClusterFunctionalLevel'='true'; } -ForceSelfUpdate -Force 
   

6. Wait for the update to complete and check the status of the update.