Deploy an Azure Stack HCI, version 23H2 via Azure Resource Manager deployment template

Applies to: Azure Stack HCI, version 23H2

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

Important

ARM template deployment of Azure Stack HCI, version 23H2 systems is targeted for deployments-at-scale. The intended audience for this deployment are IT Administrators who have experience deploying Azure Stack HCI clusters. We recommend that you deploy a version 23H2 system via the Azure portal first and then perform subsequent deployments via the ARM template.

Prerequisites

• Completion of Register your servers with Azure Arc and assign deployment permissions. Make sure that:
  • All the mandatory extensions are installed successfully. The mandatory extensions include: Azure Edge Lifecycle Manager, Azure Edge Device Management, Telemetry and Diagnostics, and Azure Edge Remote Support.
  • All servers are running the same version of OS.
  • All the servers have the same network adapter configuration.

Step 1: Prepare Azure resources

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

Create a service principal and client secret

To authenticate your cluster, 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:

1. 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.

2. Provide a Name for the application, select a Supported account type, and then select Register.

   

3. Once the service principal is created, go to the Enterprise applications page. Search for the SPN you created and select the SPN.

   

4. 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 ARM template.

Create a client secret for ARB service principal

1. Go to the service principal that you created and browse to Certificates & secrets > Client secrets.

2. Select + New client secret.

   

3. Add a Description for the client secret and provide a timeframe when it Expires. Select Add.

   

4. Copy the client secret value as you use it later.

   Note

   For the application client ID, you will need it's 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 Stack HCI Resource Provider

This object ID for the Azure Stack HCI RP is unique per Azure tenant.

1. In the Azure portal, search for and go to Microsoft Entra ID.

2. Go to the Overview tab and search for Microsoft.AzureStackHCI Resource Provider.

   

3. Select the SPN that is listed and copy the Object ID.

   

   Alternatively, you can use PowerShell to get the object ID of the Azure Stack HCI 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 ARM template.

   Step 2: Deploy using ARM template

   ARM 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 ARM 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.

   1. In Azure portal, go to Home and select + Create a resource.

   2. Select Create under Template deployment (deploy using custom templates).

      

   3. Near the bottom of the page, find Start with a quickstart template or template spec section. Select Quickstart template option.

      

   4. Use the Quickstart template (disclaimer) field to filter for the appropriate template. Type azurestackhci/create-cluster for the filter.

   5. When finished, Select template.

      

   6. On the Basics tab, you see the Custom deployment page. You can select the various parameters through the dropdown list or select Edit parameters.

      

   7. Edit parameters such as network intent or storage network intent. Once the parameters are all filled out, Save the parameters file.

      

      Tip

      Download a sample parameters file to understand the format in which you must provide the inputs.

   8. Select the appropriate resource group for your environment.

   9. Scroll to the bottom, and confirm that Deployment Mode = Validate.

   10. Select Review + create.

       

   11. On the Review + Create tab, select Create. This creates the remaining prerequisite resources and validates the deployment. Validation takes about 10 minutes to complete.

       

   12. Once validation is complete, select Redeploy.

       

   13. On the Custom deployment screen, select Edit parameters. Load up the previously saved parameters and select Save.

   14. At the bottom of the workspace, change the final value in the JSON from Validate to Deploy, where Deployment Mode = Deploy.

       

   15. Verify that all the fields for the ARM deployment template are filled in by the Parameters JSON.

   16. Select the appropriate resource group for your environment.

   17. Scroll to the bottom, and confirm that Deployment Mode = Deploy.

   18. Select Review + create.

   19. Select Create. This begins deployment, 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.

       

   20. In a new browser window, navigate to the resource group for your environment. Select the cluster resource.

   21. Select Deployments.

   22. Refresh and watch the deployment progress from the first server (also known as the seed server and is the first server where you deployed the cluster). Deployment takes between 2.5 and 3 hours. Several steps take 40-50 minutes or more.

   23. 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 Stack HCI, version 23H2 cluster using Bicep.

   Troubleshooting deployment issues

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

   1. On the Deployment details, select the error details.

      

   2. Copy the error message from the Errors blade. You can provide this error message to Microsoft support for further assistance.

      

   Next steps

   Learn more:

   • About Arc VM management
   • About how to Deploy Azure Arc VMs on Azure Stack HCI.