Install solution upgrade on Azure Local using Azure Resource Manager template

Applies to: Azure Local 2311.2 and later

This article describes how to install the solution upgrade on your Azure Local instance using Azure Resource Manager (ARM) template, after upgrading the operating system (OS) build from 20349.xxxx (22H2) to 25398.xxxx (23H2).

Important

While the OS upgrade is generally available, the solution upgrade is rolled out in phases. Additionally, the solution upgrade isn't available to customers in Azure China.
Installing solution upgrade using ARM template is targeted for at-scale upgrades. This method is intended for IT administrators who have experience managing Azure Local instances. We recommend that you upgrade a system via the Azure portal first, and then use ARM template for subsequent upgrades. To install the solution upgrade via the Azure portal, see Install solution upgrade on Azure Local.

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 to a newer version via PowerShell.

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.

Prerequisites

Before you install the solution upgrade, make sure that you:

Validate the system using the Environment Checker as per the instructions in Assess solution upgrade readiness.
Have failover cluster name between 3 to 15 characters.
Create an Active Directory Lifecycle Manager (LCM) user account that's a member of the local Administrator group. For instructions, see Prepare Active Directory for Azure Local deployment.
Have IPv4 network range that matches your host IP address subnet with six, contiguous IP addresses available for new Azure Arc services. Work with your network administrator to ensure that the IP addresses aren't in use and meet the outbound connectivity requirement.
Have Azure subscription permissions for Azure Stack HCI Administrator and Reader.

For Azure Local 2411.3 and earlier versions, make sure to select the upgrade-cluster-2411.3 template for upgrade.

For Azure Local 2503 and later versions, make sure to select the upgrade-cluster template for upgrade.

Before you begin

There are a few things to consider before you begin the solution upgrade process:

Microsoft supports upgrade applied from Azure Local resource page or by using an ARM template. Use of third-party tools to install upgrades isn't supported.
We recommend you perform the solution upgrade during a maintenance window. After the upgrade, host machine might reboot and the workloads will be live migrated, causing brief disconnections.

By installing the solution upgrade, existing unmanaged VMs won't automatically become Azure Arc VMs. For more information about VMs on Azure Local, see Types of VMs on Azure Local.

Step 1: Prepare Azure resources

Follow these steps to prepare the Azure resources you need for the upgrade:

Create a service principal and client secret

To authenticate your system, you need to create a service principal and a corresponding Client secret for Arc Resource Bridge (ARB).

Create a service principal for ARB

Follow the steps in Create a Microsoft Entra application and service principal that can access resources via Azure portal to create the service principal and assign the roles. Alternatively, use the PowerShell procedure to Create an Azure service principal with Azure PowerShell.

The steps are also summarized here:

Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator. Browse to Identity > Applications > App registrations then select New registration.
Provide a Name for the application, select a Supported account type, and then select Register.
Once the service principal is created, go to the Enterprise applications page. Search for and select the SPN you created.
Under properties, copy the Application (client) ID and the Object ID for this service principal.

You use the Application (client) ID against the arbDeploymentAppID parameter and the Object ID against the arbDeploymentSPNObjectID parameter in the Resource Manager template.

Create a client secret for ARB service principal

Go to the application registration that you created and browse to Certificates & secrets > Client secrets.
Select + New client secret.
Add a Description for the client secret and provide a timeframe when it Expires. Select Add.
Copy the client secret value as you use it later.

Note

For the application client ID, you will need its secret value. Client secret values can't be viewed except for immediately after creation. Be sure to save this value when created before leaving the page.

You use the client secret value against the arbDeploymentAppSecret parameter in the ARM template.

Get the object ID for Azure Local Resource Provider

This object ID for the Azure Local Resource Provider (RP) is unique per Azure tenant.

In the Azure portal, search for and go to Microsoft Entra ID.
Go to the Overview tab and search for Microsoft.AzureStackHCI Resource Provider.
Select the Service Principal Name that is listed and copy the Object ID.

Alternatively, you can use PowerShell to get the object ID of the Azure Local RP service principal. Run the following command in PowerShell:
```
Get-AzADServicePrincipal -DisplayName "Microsoft.AzureStackHCI Resource Provider"
```

Step 2: Install the solution upgrade using Azure Resource Manager template

An ARM template creates and assigns all the resource permissions required for the upgrade. With all the prerequisite and preparation steps complete, you're ready to upgrade using a known good and tested ARM template and corresponding parameters JSON file. Use the parameters contained in the JSON file to fill out all values, including the values generated previously. For an example of a parameter JSON file, see azuredeploy.parameters.json. For detailed descriptions of the parameters defined in this file, see ARM template parameters reference.

Important

Ensure that all parameters in the JSON file are filled out, including placeholders that appear as [“”], which indicate that the parameter expects an array structure. Replace these with actual values based on your deployment environment, or validation will fail.

Follow these steps to install the solution upgrade:

In the Azure portal, go to Home and select + Create a resource.
Select Create under Template deployment (deploy using custom templates).
From the Start with a quickstart template or template spec section, select Quickstart template option.

From the Quickstart template (disclaimer) dropdown list, select the azurestackhci/upgrade-cluster-2411.3 template.
When finished, select the Select template button.
On the Basics tab, you see the Custom deployment page. You can select the various parameters through the dropdown lists or select Edit parameters.

Note

For an example parameter file that shows the format of various inputs, such as ArcNodeResourceId, see azuredeploy.parameters.json.

From the Quickstart template (disclaimer) dropdown list, select the azurestackhci/upgrade-cluster template.
When finished, select the Select template button.
On the Basics tab, you see the Custom deployment page. You can select the various parameters through the dropdown lists or select Edit parameters.

Note

For an example parameter file that shows the format of various inputs, such as ArcNodeResourceId, see azuredeploy.parameters.json.

Edit parameters. Once the parameters are all filled out, Save the parameters file.
Select the appropriate resource group for your environment.
Confirm that Deployment Mode = Validate.
Select Review + create.
On the Review + Create tab, select Create. This creates the remaining prerequisite resources and validates the upgrade. Validation takes about 10 minutes to complete.
Once validation is complete, select Redeploy.
On the Custom deployment screen, select Edit parameters. Load up the previously saved parameters and select Save.
Change the final value in the JSON from Validate to Deploy, where Deployment Mode = Deploy.
Verify that all the fields for the ARM template are filled in by the parameters JSON.
Select the appropriate resource group for your environment.
Confirm that Deployment Mode = Deploy.
Select Review + create.
Select Create. The upgrade begins, using the existing prerequisite resources that were created during the Validate step.

The Deployment screen cycles on the cluster resource during upgrade.

Once the upgrade initiates, there's a limited Environment Checker run, a full Environment Checker run, and cloud upgrade starts. After a few minutes, you can monitor upgrade in the portal.
In a new browser window, navigate to the resource group for your environment. Select the cluster resource.
Select Deployments.
Refresh and watch the deployment progress from the first machine (also known as the seed machine and is the first machine where you deployed the cluster). Deployment takes between 2.5 and 3 hours. Several steps take 40-50 minutes or more.

ARM template parameters reference

The following table describes the parameters that you define in the ARM template's parameters file:

Parameter	Description
deploymentMode	Determines if the upgrade process should only validate or proceed with full upgrade: - Validate: Validates your system's readiness to upgrade. - Deploy: Performs the actual upgrade after successful validation.
keyVaultName	Name of the Azure Key Vault to be used for storing secrets. For naming conventions, see Microsoft.KeyVault in the Naming rules and restrictions for Azure resources article.
createNewKeyVault	Specifies whether the template should create a new Key Vault or use an existing one. Set this value as false if you are reusing an existing Key Vault.
softDeleteRetentionDays	Number of days that deleted items (such as secrets, keys, or certificates) are retained in an Azure Key Vault before they are permanently deleted. Specify a value between 7 and 90 days. You can’t change the retention period later.
diagnosticStorageAccountName	Name of the Azure Storage Account used to store key vault audit logs. This account is a locally redundant storage (LRS) account with a lock. For more information, see Azure Storage Account. For naming conventions, see Azure Storage account names.
logsRetentionInDays	Number of days that logs are retained. If you don't want to apply any retention policy and retain data forever, specify 0.
storageAccountType	Type of the Azure Storage Account to be used in the deployment. For example, Standard_LRS.
clusterName	Name of the Azure Local instance being deployed. This is the name that represents your cluster on cloud. It must be different from any of the node names.
failoverClusterName
location	Deployment location, typically derived from the resource group. For a list of supported Azure regions, see Azure requirements.
tenantId	Azure subscription tenant ID. For more information, see Find your Microsoft Entra tenant.
AzureStackLCMAdminUsername	Username for the LCM admin. For more information, see Review deployment prerequisites for Azure Local.
AzureStackLCMAdminPasssword	Password for the LCM admin. For more information, see Review deployment prerequisites for Azure Local.
arcNodeResourceIds	Array of resource IDs of the Azure Arc-enabled servers that are part of this Azure Local cluster.
domainFqdn	Fully qualified domain name (FQDN) for the Active Directory Domain Services prepared for deployment.
subnetMask	The subnet mask for the management network used by the Azure Local deployment.
defaultGateway	The default gateway for deploying an Azure Local cluster.
startingIPAddress	The first IP address in a contiguous block of at least six static IP addresses on your management network's subnet, omitting addresses already used by the machines. These IPs are used by Azure Local and internal infrastructure (Arc Resource Bridge) that's required for Arc VM management and AKS Hybrid.
endingIPAddress	The last IP address in a contiguous block of at least six static IP addresses on your management network's subnet, omitting addresses already used by the machines. These IPs are used by Azure Local and internal infrastructure (Arc Resource Bridge) that's required for Arc VM management and AKS Hybrid.
dnsServers	List of DNS server IPs.
physicalNodesSettings	Array of physical nodes with their IP addresses.
customLocation	Custom location for deployment.

Next steps

If you run into issues during the upgrade process, see Troubleshoot solution upgrade on Azure Local.

Feedback

Was this page helpful?

Last updated on 2025-10-16