Deploy Azure Local via Azure Resource Manager deployment template

Article
2025-05-01

Applies to: Azure Local 2311.2 and later

This article details how to use an Azure Resource Manager template in the Azure portal to deploy an Azure Local in your environment. The article also contains the prerequisites and the preparation steps required to begin the deployment.

Important

Azure Resource Manager template deployment of Azure Local systems is targeted for deployments-at-scale. The intended audience for this deployment is IT administrators who have experience deploying Azure Local instances. We recommend that you deploy a system via the Azure portal first, and then perform subsequent deployments via the Resource Manager template.

Prerequisites

Completion of Register your machines with Azure Arc and assign deployment permissions. Make sure that:
- All machines are running the same version of OS.
- All the machines have the same network adapter configuration.
For Azure Local 2411.3 and earlier versions, make sure to select the create-cluster-2411.3 template for deployment.

Step 1: Prepare Azure resources

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

Get the object ID for Azure Local Resource Provider

This object ID for the Azure Local Resource Provide (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"
```
You use the Object ID against the hciResourceProviderObjectID parameter in the Resource Manager template.

Step 2: Deploy using Azure Resource Manager template

A Resource Manager template creates and assigns all the resource permissions required for deployment.

With all the prerequisite and preparation steps complete, you're ready to deploy using a known good and tested Resource Manager deployment template and corresponding parameters JSON file. Use the parameters contained in the JSON file to fill out all values, including the values generated previously.

Important

In this release, make sure that all the parameters contained in the JSON value are filled out including the ones that have a null value. If there are null values, then those need to be populated or the validation fails.

In the Azure portal, go to Home and select + Create a resource.
Select Create under Template deployment (deploy using custom templates).
Near the bottom of the page, find Start with a quickstart template or template spec section. Select Quickstart template option.
Use the Quickstart template (disclaimer) field to filter for the appropriate template. Type azurestackhci/create-cluster for the filter.
When finished, Select template.

Note

For Azure Local 2411.3 and earlier versions, make sure to select the create-cluster-2411.3 template for deployment.
On the Basics tab, you see the Custom deployment page. You can select the various parameters through the dropdown list or select Edit parameters.
Edit parameters such as network intent or storage network intent. Once the parameters are all filled out, Save the parameters file.
Select the appropriate resource group for your environment.
Scroll to the bottom, and confirm that Deployment Mode = Validate.
Select Review + create.
On the Review + Create tab, select Create. This creates the remaining prerequisite resources and validates the deployment. 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.
At the bottom of the workspace, change the final value in the JSON from Validate to Deploy, where Deployment Mode = Deploy.
Verify that all the fields for the Resource Manager deployment template are filled in by the Parameters JSON.
Select the appropriate resource group for your environment.
Scroll to the bottom, and confirm that Deployment Mode = Deploy.
Select Review + create.
Select Create. The deployment begins, using the existing prerequisite resources that were created during the Validate step.

The Deployment screen cycles on the cluster resource during deployment.

Once deployment initiates, there's a limited Environment Checker run, a full Environment Checker run, and cloud deployment starts. After a few minutes, you can monitor deployment 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.
The step in deployment that takes the longest is Deploy Moc and ARB Stack. This step takes 40-45 minutes.

Once complete, the task at the top updates with status and end time.

You can also check out this community sourced template to Deploy an Azure Local instance using Bicep.

Troubleshoot deployment issues

If the deployment fails, you should see an error message on the deployments page.

On the Deployment details, select the error details.
Copy the error message from the Errors blade. You can provide this error message to Microsoft support for further assistance.

Known issues for ARM template deployment

This section contains known issues and workarounds for ARM template deployment.

Role assignment already exists

Issue: In this release, you may see Role assignment already exists error. This error occurs if the Azure Local instance deployment was attempted from the portal first and the same resource group was used for ARM template deployment. You see this error on the Overview > Deployment details page for the applicable resource. This error indicates that an equivalent role assignment was already done by another identity for the same resource group scope and the ARM template deployment is unable to perform role assignment.

Workaround: The failed resource on the Deployment details page specifies the role assignment name. If the resource name is AzureStackHCIDeviceManagementRole-RoleAssignment then role assignment failed for the Azure Stack HCI Device Management Role. Note this role name and go to Resource Group > Access Control (IAM) > Role Assignments. Search for the corresponding name and delete the existing role assignments there. Redeploy your template.

Tenant ID, application ID, principal ID, and scope aren't allowed to be updated

Issue: Role assignment fails with error Tenant ID, application ID, principal ID, and scope aren't allowed to be updated. You see this error on the Overview > Deployment details page for the applicable resource. This error could show up when there are zombie role assignments in the same resource group. For example, when a prior deployment was performed and the resources corresponding to that deployment were deleted but the role assignment resources were left around.

Workaround: To identify the zombie role assignments, go to Access control (IAM) > Role assignments > Type : Unknown tab. These assignments are listed as Identity not found. Unable to find identity. Delete such role assignments and then retry ARM template deployment.

License sync issue

Issue: In this release, you may encounter license sync issue when using ARM template deployment.

Workaround: After the system completes the validation stage, we recommend that you don't initiate another ARM template deployment in Validate mode if your system is in Deployment failed state. Starting another deployment resets the system properties, which could result in license sync issues.

Share via