Muokkaa

Jaa

Deploy Azure Local, version 23H2 via Azure Resource Manager deployment template

  • Artikkeli

Applies to: Azure Local, version 23H2

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, version 23H2 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 version 23H2 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 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 machines are running the same version of OS.
    • All the machines 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 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:

  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.

    Screenshot showing Register an application for service principal creation.

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

    Screenshot showing search results for the service principal created.

  4. Under properties, copy the Application (client) ID and the Object ID for this service principal.

    Screenshot showing Application (client) ID and the object ID for the service principal created.

    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

  1. Go to the application registration that you created and browse to Certificates & secrets > Client secrets.

  2. Select + New client secret.

    Screenshot showing creation of a new client secret.

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

    Screenshot showing Add a client secret blade.

  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.

    Screenshot showing client secret value.

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

Get the object ID for Azure Local Resource Provider

This object ID for the Azure Local 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.

    Screenshot showing the search for the Azure Local Resource Provider service principal.

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

    Screenshot showing the object ID for the Azure Local Resource Provider service principal.

    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.

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

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

    Screenshot showing the template deployment (deploy using custom template).

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

    Screenshot showing the quickstart template selected.

  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.

    Screenshot showing template selected.

  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.

    Screenshot showing Custom deployment page on the Basics tab.

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

    Screenshot showing parameters filled out for the template.

  8. Select the appropriate resource group for your environment.

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

  10. Select Review + create.

    Screenshot showing Review + Create selected on Basics tab.

  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.

    Screenshot showing Create selected on Review + Create tab.

  12. Once validation is complete, select Redeploy.

    Screenshot showing Redeploy selected.

  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.

    Screenshot showing deploy selected for deployment mode.

  15. Verify that all the fields for the Resource Manager 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. 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.

    Screenshot showing the status of environment checker validation.

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

  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 Local, version 23H2 instance using Bicep.

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

    Screenshot showing the selection of error details.

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

    Screenshot showing the summary in the Errors blade.

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.

Screenshot showing the role assignment exists message in the Errors blade.

Workaround: Although these errors can be disregarded and deployment can proceed via the ARM template, we strongly recommend that you don't interchange deployment modes between the portal and ARM 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.

Screenshot showing the tenant ID, application ID, principal ID, and scope can't be updated message in the Errors blade.

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.

Screenshot showing the identity not found message in the Errors blade.

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.

Next steps