|
| 1 | +--- |
| 2 | +title: Upgrade Azure Stack HCI OS to version 26100.xxxx using PowerShell |
| 3 | +description: Learn how to use PowerShell to upgrade Azure Stack HCI OS to version 26100.xxxx. |
| 4 | +author: alkohli |
| 5 | +ms.topic: how-to |
| 6 | +ms.date: 06/05/2025 |
| 7 | +ms.author: alkohli |
| 8 | +ms.reviewer: alkohli |
| 9 | +ms.service: azure-local |
| 10 | +--- |
| 11 | + |
| 12 | +# Upgrade Azure Stack HCI OS to version 26100.xxxx using PowerShell |
| 13 | + |
| 14 | +[!INCLUDE [end-of-service-22H2](../includes/end-of-service-22h2.md)] |
| 15 | + |
| 16 | +This article describes how to upgrade the Azure Stack HCI operating system (OS) via PowerShell. Supported upgrade paths include: |
| 17 | + |
| 18 | +- From OS version 20349.xxxx to 26100.xxxx. |
| 19 | + |
| 20 | +- From OS version 25398.xxxx to 26100.xxxx. |
| 21 | + |
| 22 | +> [!IMPORTANT] |
| 23 | +> This article covers OS upgrades only. Do not proceed if solution upgrade is complete or Azure Local 2311.2 or later is deployed. |
| 24 | +> To check if your system is already running the solution, run the `Get-StampInformation` cmdlet. If it returns output, your system is already running the solution, and you should skip these steps. |
| 25 | +
|
| 26 | +## High-level workflow for the OS upgrade |
| 27 | + |
| 28 | +The Azure Stack HCI OS update is available only via the Azure portal. |
| 29 | + |
| 30 | +To upgrade the OS on your system, follow these high-level steps: |
| 31 | + |
| 32 | +1. [Complete the prerequisites.](#complete-prerequisites) |
| 33 | +1. [Update registry keys.](#update-registry-keys) |
| 34 | +1. [Install new OS using PowerShell.](#install-new-os-using-powershell) |
| 35 | +1. [Check the status of the updates.](#check-the-status-of-an-update) |
| 36 | +1. [After the OS is upgraded, perform post-OS upgrade steps.](#next-steps) |
| 37 | + |
| 38 | +## Complete prerequisites |
| 39 | + |
| 40 | +- Make sure your Azure Local system is running either OS version 20349.3692 or OS version greater than 25398.1611. |
| 41 | +- Make sure the system is registered in Azure and all the machines in the system are healthy and online. |
| 42 | +- 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. |
| 43 | +- Confirm that you have access to the Azure Local **2505** ISO file, which you can download from the [Azure portal](https://portal.azure.com/#view/Microsoft_Azure_ArcCenterUX/ArcCenterMenuBlade/~/hciGetStarted). |
| 44 | +- 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. |
| 45 | +- 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: |
| 46 | + |
| 47 | + | NIC manufacturer | Inbox driver version | Recommended latest compatible driver | |
| 48 | + |--|--|--| |
| 49 | + | Intel | 1.15.121.0 | 1.17.73.0 | |
| 50 | + | NVIDIA | 24.4.26429.0 | 25.4.50020 | |
| 51 | + |
| 52 | +- 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: |
| 53 | + |
| 54 | + ```powershell |
| 55 | + Register-AzStackHCI -TenantId "<tenant_ID>" -SubscriptionId "<subscription_ID>" -ComputerName "<computer_name>" -RepairRegistration |
| 56 | + ``` |
| 57 | + You can verify the *identity* property in the Azure portal in resource's JSON or by running the following cmdlet: |
| 58 | + |
| 59 | + ```powershell |
| 60 | + Get-AzResource -Name <cluster_name> -ResourceGroupName <name of the resource group> -ResourceType "Microsoft.AzureStackHCI/clusters" -ExpandProperties |
| 61 | + ``` |
| 62 | +- (Recommended) Enable [Secure Boot](/windows-hardware/design/device-experiences/oem-secure-boot) on Azure Local machines before you upgrade the OS. To enable Secure Boot, follow these steps: |
| 63 | + 1. Drain the cluster node. |
| 64 | + 1. Restart the OS. |
| 65 | + 1. Enter the BIOS/UEFI menu. |
| 66 | + 1. Review the **Boot** or **Security** section of the UEFI configuration options Locate the Secure Boot option. |
| 67 | + 1. Set the option to **Enabled** or **On**. |
| 68 | + 1. Save the changes and restart your computer. |
| 69 | + |
| 70 | + Consult with your hardware vendor for assistance if required. |
| 71 | + |
| 72 | +## Update registry keys |
| 73 | + |
| 74 | +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. |
| 75 | + |
| 76 | +1. Set `RefsEnableMetadataValidation` to `0`: |
| 77 | + |
| 78 | + ```powershell |
| 79 | + Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "RefsEnableMetadataValidation" -Value 0 -Type DWord -ErrorAction Stop |
| 80 | + ``` |
| 81 | + |
| 82 | +1. Create the parameters key if it doesn't exist. If it already exists, the command may fail with an error, which is expected. |
| 83 | + |
| 84 | + ```powershell |
| 85 | + New-Item -Path HKLM:\SYSTEM\CurrentControlSet\Services\Vid\Parameters |
| 86 | + ``` |
| 87 | + |
| 88 | +1. 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. |
| 89 | + |
| 90 | +1. Update and verify that the registry keys have been applied on each machine in the system before moving to the next step. |
| 91 | + |
| 92 | +## Install new OS using PowerShell |
| 93 | + |
| 94 | +To install the new OS using PowerShell, follow these steps: |
| 95 | + |
| 96 | +> [!NOTE] |
| 97 | +> The following steps require the Cluster-Aware Updating (CAU) role to be installed and enabled on the system. For information on how to install and enable this feature on your Azure Local, see [Cluster-Aware Updating overview](/windows-server/failover-clustering/cluster-aware-updating#installing-cluster-aware-updating). |
| 98 | +
|
| 99 | +1. Run the following cmdlets on every machine in the system. |
| 100 | + |
| 101 | + ```PowerShell |
| 102 | + Set-WSManQuickConfig |
| 103 | + Enable-PSRemoting |
| 104 | + ``` |
| 105 | + |
| 106 | +1. 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: |
| 107 | + |
| 108 | + ```PowerShell |
| 109 | + Test-CauSetup -ClusterName <System name> |
| 110 | + ``` |
| 111 | + |
| 112 | +1. 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. <!--ASK--> |
| 113 | + |
| 114 | + ```PowerShell |
| 115 | + Test-Cluster |
| 116 | + ``` |
| 117 | + |
| 118 | +1. 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. |
| 119 | + |
| 120 | + ```powershell |
| 121 | + # Define ISO and destination paths |
| 122 | + $isoFilePath = "C:\SetupFiles\WindowsServer\ISOs\example.iso" |
| 123 | + $destinationPath = "C:\SetupFiles\WindowsServer\Files" |
| 124 | + # Mount the ISO file |
| 125 | + $iso = Mount-DiskImage -ImagePath $isoFilePath |
| 126 | + # Get the drive letter |
| 127 | + $driveLetter = ($iso | Get-Volume).DriveLetter |
| 128 | + # Create the destination directory |
| 129 | + New-Item -ItemType Directory -Path $destinationPath |
| 130 | + # Copy contents to the local directory |
| 131 | + Copy-Item -Path "${driveLetter}:\*" -Destination $destinationPath –Recurse |
| 132 | + # Dismount the ISO file |
| 133 | + Dismount-DiskImage -ImagePath $isoFilePath |
| 134 | + ``` |
| 135 | + |
| 136 | +1. Upgrade the system. |
| 137 | + |
| 138 | + ```powershell |
| 139 | + Invoke-CauRun –ClusterName <SystemName> -CauPluginName Microsoft.RollingUpgradePlugin -EnableFirewallRules -CauPluginArguments @{ 'WuConnected'='false';'PathToSetupMedia'='\some\path\'; 'UpdateClusterFunctionalLevel'='true'; } -ForceSelfUpdate -Force |
| 140 | + ``` |
| 141 | + |
| 142 | +1. Wait for the update to complete and check the status of the update. |
| 143 | + |
| 144 | +## Check the status of an update |
| 145 | + |
| 146 | +[!INCLUDE [verify-update](../includes/azure-local-verify-update.md)] |
| 147 | + |
| 148 | +## Known issues |
| 149 | + |
| 150 | +If the system is configured with Network ATC prior to performing the OS upgrade, the Network ATC management intent may fail with error `PhysicalAdapterNotFound` after upgrading the OS. For detailed steps on how to resolve this issue, see the [Troubleshooting guide](https://github.com/Azure/AzureLocal-Supportability/blob/main/TSG/Upgrade/Known%252Dissue-%252D-Network-ATC-management-intent-fails-with-%E2%80%98PhysicalAdapterNotFound%E2%80%99-after-upgrading-OS-from-22H2-to-23H2.md). |
| 151 | + |
| 152 | + |
| 153 | +## Next steps |
| 154 | + |
| 155 | +- [Learn how to perform the post-OS upgrade steps for your Azure Local.](./post-upgrade-steps.md) |
0 commit comments