Merge pull request #17863 from ManikaDhiman/md-arm-deployment

ARM deployment updates

Author: JillGrant615

azure-local/deploy/deploy-via-portal.md

@@ -3,29 +3,30 @@ title: Deploy an Azure Local instance using the Azure portal
 description: Learn how to deploy an Azure Local instance from the Azure portal
 author: alkohli
 ms.topic: how-to
-ms.date: 05/01/2025
+ms.date: 05/07/2025
 ms.author: alkohli
 ms.service: azure-local
 #CustomerIntent: As an IT Pro, I want to deploy an Azure Local instance of 1-16 machines via the Azure portal so that I can host VM and container-based workloads on it.
 ---
 
 # Deploy Azure Local using the Azure portal
 
-> Applies to: Azure Local 2503 and later
-
 This article helps you deploy an Azure Local instance using the Azure portal.
 
-> [!IMPORTANT]
-> The Azure portal will block deployments of Azure Local for versions 2411.3 or earlier. To deploy these versions, use an Azure Resource Manager (ARM) template. For more information, see [Deploy Azure Local via Azure Resource Manager deployment template](./deployment-azure-resource-manager-template.md).
-
 ## Prerequisites
 
 - Completion of [Register your machines with Azure Arc and assign deployment permissions](./deployment-arc-register-server-permissions.md).
 <!-- Cristian to confirm * For three-node systems, the network adapters that carry the in-cluster storage traffic must be connected to a network switch. Deploying three-node systems with storage network adapters that are directly connected to each machine without a switch isn't supported in this preview.-->
 
+::: moniker range="<=azloc-24113"
+
+- To deply Azure Local 2411.3 and earlier, use the alternative version of the [Azure portal](https://aka.ms/dfc-2411deploycluster). Use this version only for deployment, don't use it for any other purpose.
+
+::: moniker-end
+
 ## Start the wizard and fill out the basics
 
-1. Open a web browser and navigate to [**Azure portal**](https://portal.azure.com). Search for and select **Azure Local**. On the **Azure Arc|Azure Local**, go to the **Get started** tab. On the **Deploy Azure Local** tile, select **Create instance**.
+1. Go to the Azure portal. Search for and select **Azure Local**. On the **Azure Arc|Azure Local**, go to the **Get started** tab. On the **Deploy Azure Local** tile, select **Create instance**.
 
    :::image type="content" source="./media/deploy-via-portal/get-started-1.png" alt-text="Screenshot of the Get started tab in deployment via Azure portal." lightbox="./media/deploy-via-portal/get-started-1.png":::
 

azure-local/deploy/deployment-arc-register-server-permissions.md

@@ -187,6 +187,13 @@ This section describes how to assign Azure permissions for deployment from the A
 
 1. In the right pane, go to **Role assignments**. Verify that the deployment user has all the configured roles.
 
+1. In the Azure portal, go to **Microsoft Entra Roles and Administrators** and assign the **Cloud Application Administrator** role permission at the Microsoft Entra tenant level.
+
+    :::image type="content" source="media/deployment-arc-register-server-permissions/cloud-application-administrator-role-at-tenant.png" alt-text="Screenshot of the Cloud Application Administrator permission at the tenant level." lightbox="./media/deployment-arc-register-server-permissions/cloud-application-administrator-role-at-tenant.png":::
+
+    > [!NOTE]
+    > The Cloud Application Administrator permission is temporarily needed to create the service principal. After deployment, this permission can be removed. 
+
 ## Next steps
 
 After setting up the first machine in your instance, you're ready to deploy using Azure portal:

azure-local/deploy/deployment-azure-resource-manager-template.md

@@ -3,7 +3,7 @@ title: Azure Resource Manager template deployment for Azure Local, version 23H2
 description: Learn how to prepare and then deploy Azure Local instance, version 23H2 using the Azure Resource Manager template.
 author: alkohli
 ms.topic: how-to
-ms.date: 05/06/2025
+ms.date: 05/07/2025
 ms.author: alkohli
 ms.reviewer: alkohli
 ms.service: azure-local
@@ -12,8 +12,6 @@ ms.custom: devx-track-arm-template
 
 # Deploy Azure Local via Azure Resource Manager deployment template
 
-[!INCLUDE [applies-to](../includes/hci-applies-to-23h2.md)]
-
 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]
@@ -24,12 +22,73 @@ This article details how to use an Azure Resource Manager template in the Azure
 - Completion of [Register your machines with Azure Arc and assign deployment permissions](./deployment-arc-register-server-permissions.md). Make sure that:
   - All machines are running the same version of OS.
   - All the machines have the same network adapter configuration.
+
+::: moniker range="<=azloc-24113"
+
 - For Azure Local 2411.3 and earlier versions, make sure to select the **create-cluster-2411.3** template for deployment.
 
+::: moniker-end
+
+::: moniker range=">=azloc-2503"
+
+- For Azure Local 2503 and later versions, make sure to select the **create-cluster** template for deployment.
+
+::: moniker-end
+
 ## Step 1: Prepare Azure resources
 
 Follow these steps to prepare the Azure resources you need for the deployment:
 
+::: moniker range="<=azloc-24113"
+
+### 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](/entra/identity-platform/howto-create-service-principal-portal) to create the service principal and assign the roles. Alternatively, use the PowerShell procedure to [Create an Azure service principal with Azure PowerShell](/powershell/azure/create-azure-service-principal-azureps).
+
+The steps are also summarized here:
+
+1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/) as at least a Cloud Application Administrator. Browse to **Identity > Applications > App registrations** then select **New registration**.
+
+1. Provide a **Name** for the application, select a **Supported account type**, and then select **Register**.
+
+    :::image type="content" source="./media/deployment-azure-resource-manager-template/create-service-principal-1a.png" alt-text="Screenshot showing Register an application for service principal creation." lightbox="./media/deployment-azure-resource-manager-template/create-service-principal-1a.png":::
+
+1. Once the service principal is created, go to the **Enterprise applications** page. Search for and select the SPN you created.
+
+   :::image type="content" source="./media/deployment-azure-resource-manager-template/create-service-principal-2a.png" alt-text="Screenshot showing search results for the service principal created." lightbox="./media/deployment-azure-resource-manager-template/create-service-principal-2a.png":::
+
+1. Under properties, copy the **Application (client) ID**  and the **Object ID** for this service principal.
+
+   :::image type="content" source="./media/deployment-azure-resource-manager-template/create-service-principal-2b.png" alt-text="Screenshot showing Application (client) ID and the object ID for the service principal created." lightbox="./media/deployment-azure-resource-manager-template/create-service-principal-2b.png":::
+
+    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**.
+1. Select **+ New client** secret.
+
+    :::image type="content" source="./media/deployment-azure-resource-manager-template/create-client-secret-1.png" alt-text="Screenshot showing creation of a new client secret." lightbox="./media/deployment-azure-resource-manager-template/create-client-secret-1.png":::
+
+1. Add a **Description** for the client secret and provide a timeframe when it **Expires**. Select **Add**.
+
+    :::image type="content" source="./media/deployment-azure-resource-manager-template/create-client-secret-2.png" alt-text="Screenshot showing Add a client secret blade." lightbox="./media/deployment-azure-resource-manager-template/create-client-secret-2.png":::
+
+1. 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.
+
+    :::image type="content" source="./media/deployment-azure-resource-manager-template/create-client-secret-3.png" alt-text="Screenshot showing client secret value." lightbox="./media/deployment-azure-resource-manager-template/create-client-secret-3.png":::
+
+    You use the **client secret value** against the `arbDeploymentAppSecret` parameter in the Resource Manager template.
+
+::: moniker-end
+
 ### Get the object ID for Azure Local Resource Provider
 
 This object ID for the Azure Local Resource Provide (RP) is unique per Azure tenant.
@@ -62,76 +121,97 @@ With all the prerequisite and preparation steps complete, you're ready to deploy
 
 1. In the Azure portal, go to **Home** and select **+ Create a resource**.
 
-1. Select **Create** under **Template deployment (deploy using custom templates)**.
+2. Select **Create** under **Template deployment (deploy using custom templates)**.
 
     :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-1.png" alt-text="Screenshot showing the template deployment (deploy using custom template)." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-1.png":::
 
-1. Near the bottom of the page, find **Start with a quickstart template or template spec** section. Select **Quickstart template** option.
+3. Near the bottom of the page, find **Start with a quickstart template or template spec** section. Select **Quickstart template** option.
 
     :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-2.png" alt-text="Screenshot showing the quickstart template selected." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-2.png":::
 
-1. Use the **Quickstart template (disclaimer)** field to filter for the appropriate template. Type *azurestackhci/create-cluster* for the filter.
+::: moniker range="<=azloc-24113"
 
-1. When finished, **Select template**.
+4. From the **Quickstart template (disclaimer)** dropdown list, select the **create-cluster-2411.3** template.
 
-    :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-3a.png" alt-text="Screenshot showing template selected." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-3a.png":::
+5. When finished, select the **Select template** button.
+
+    :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-24113-and-earlier.png" alt-text="Screenshot showing template selected for version 2411.3 and earlier." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-24113-and-earlier.png":::
+
+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**.
+
+    :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-4a.png" alt-text="Screenshot showing Custom deployment page on the Basics tab." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-4a.png":::
 
     > [!NOTE]
-    > For Azure Local 2411.3 and earlier versions, make sure to select the **create-cluster-2411.3** template for deployment.
+    > For an example parameter file that shows the format of various inputs, such as `ArcNodeResourceId`, see [azuredeploy.parameters.json](https://github.com/Azure/azure-quickstart-templates/blob/master/quickstarts/microsoft.azurestackhci/create-cluster-2411.3/azuredeploy.parameters.json).
+
+::: moniker-end
 
-1. On the **Basics** tab, you see the **Custom deployment** page. You can select the various parameters through the dropdown list or select **Edit parameters**.
+::: moniker range=">=azloc-2503"
+
+4. Use the **Quickstart template (disclaimer)** field to filter for the appropriate template. Type *azurestackhci/create-cluster* for the filter.
+
+5. When finished, select the **Select template** button.
+
+    :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-3a.png" alt-text="Screenshot showing template selected." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-3a.png":::
+
+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**.
 
     :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-4a.png" alt-text="Screenshot showing Custom deployment page on the Basics tab." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-4a.png":::
 
-1. Edit parameters such as network intent or storage network intent. Once the parameters are all filled out, **Save** the parameters file.
+    > [!NOTE]
+    > For an example parameter file that shows the format of various inputs, such as `ArcNodeResourceId`, see [azuredeploy.parameters.json](https://github.com/Azure/azure-quickstart-templates/blob/master/quickstarts/microsoft.azurestackhci/create-cluster/azuredeploy.parameters.json).
+
+::: moniker-end
+
+7. Edit parameters such as network intent or storage network intent. Once the parameters are all filled out, **Save** the parameters file.
 
     :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-5.png" alt-text="Screenshot showing parameters filled out for the template." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-5.png":::
 
-1. Select the appropriate resource group for your environment.
+8. Select the appropriate resource group for your environment.
 
-1. Scroll to the bottom, and confirm that **Deployment Mode = Validate**.
+9. Scroll to the bottom, and confirm that **Deployment Mode = Validate**.
 
-1. Select **Review + create**.
+10. Select **Review + create**.
 
     :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-6.png" alt-text="Screenshot showing Review + Create selected on Basics tab." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-6.png":::
 
-1. On the **Review + Create** tab, select **Create**. This creates the remaining prerequisite resources and validates the deployment. Validation takes about 10 minutes to complete.
+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.
 
     :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-7.png" alt-text="Screenshot showing Create selected on Review + Create tab." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-7.png":::
 
-1. Once validation is complete, select **Redeploy**.
+12. Once validation is complete, select **Redeploy**.
 
     :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-7a.png" alt-text="Screenshot showing Redeploy selected." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-7a.png":::
 
-1. On the **Custom deployment** screen, select **Edit parameters**. Load up the previously saved parameters and select **Save**.
+13. On the **Custom deployment** screen, select **Edit parameters**. Load up the previously saved parameters and select **Save**.
 
-1. At the bottom of the workspace, change the final value in the JSON from **Validate** to **Deploy**, where **Deployment Mode = Deploy**.
+14. At the bottom of the workspace, change the final value in the JSON from **Validate** to **Deploy**, where **Deployment Mode = Deploy**.
 
     :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-7b.png" alt-text="Screenshot showing deploy selected for deployment mode." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-7b.png":::
 
-1. Verify that all the fields for the Resource Manager deployment template are filled in by the Parameters JSON.
+15. Verify that all the fields for the Resource Manager deployment template are filled in by the Parameters JSON.
 
-1. Select the appropriate resource group for your environment.
+16. Select the appropriate resource group for your environment.
 
-1. Scroll to the bottom, and confirm that **Deployment Mode = Deploy**.
+17. Scroll to the bottom, and confirm that **Deployment Mode = Deploy**.
 
-1. Select **Review + create**.
+18. Select **Review + create**.
 
-1. Select **Create**. The deployment begins, using the existing prerequisite resources that were created during the **Validate** step.
+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.
 
     :::image type="content" source="./media/deployment-azure-resource-manager-template/deploy-arm-template-9.png" alt-text="Screenshot showing the status of environment checker validation." lightbox="./media/deployment-azure-resource-manager-template/deploy-arm-template-9.png":::
 
-1. In a new browser window, navigate to the resource group for your environment. Select the cluster resource.
+20. In a new browser window, navigate to the resource group for your environment. Select the cluster resource.
 
-1. Select **Deployments**.
+21. Select **Deployments**.
 
-1. 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.
+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.
 
-1. The step in deployment that takes the longest is **Deploy Moc and ARB Stack**. This step takes 40-45 minutes.
+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.