Troubleshoot deployment validation steps

Author: alkohli

azure-stack/hci/manage/troubleshoot-deployment.md

@@ -1,15 +1,22 @@
 ---
-author: [email protected]
-foundinbuild: Deployments after August 6th, 2024
-fixedinbuild: Targeted within 2-weeks of August 14th, 2024
-engineeringid: 532173261
+title: Troubleshoot deployment validation issues in Azure Stack HCI, version 23H2 via Azure portal
+description: Learn how to troubleshoot the deployment validation failures for Azure Stack HCI, version 23H2 when deployed via the Azure portal.
+ms.topic: how-to
+ms.author: alkohli
+author: alkohli
+ms.date: 08/21/2024
 ---
 
-# Background
-A new portal validation method which calculates the ipv4Address of the host machine was rolled out 1st week of August 2024. From the PG: "If some switch is configured for the device, we find the corresponding Virtual NIC whose MAC Address matches that of the MAC Address of the Management NIC. In these customer cases, a switch was found but that switch was not configured to any Virtual NIC, hence the missing ipv4 address, because the switch was incorrectly configured for the customer device."
 
-## Error message
+# Troubleshoot Azure portal deployment validation issues for Azure Stack HCI, version 23H2
 
+[!INCLUDE [hci-applies-to-23h2](../../includes/hci-applies-to-23h2.md)]
+
+This article provides guidance on how to troubleshoot deployment validation issues experienced during the deployment of your Azure Stack HCI cluster via the Azure portal.
+
+## Error - deployment vaildation failure with not a valid IPv4 address
+
+When deploying Azure Stack HCI, version 23H2 via the Azure portal, you might encounter a deployment validation failure.
 The "Azure Stack HCI Network - Check network requirements" validation task fail with the following error:
 
 ```
@@ -20,40 +27,51 @@ found error at deploymentdata.physicalnodes[0].ipv4address: The specified  for
 Example: 192.168.0.1 or 192.168.0.1","Target":null,"Details":null}].
 ```
 
-If you go to the **Networking** tab in Azure portal deployment, within the **Network Intent** configuration, the following error could be seen:
+If you go to the **Networking** tab in Azure portal deployment, within the **Network Intent** configuration, you could see the following error: 
 
-`The selected physical network adapter is no binded to the management virtual Switch.`
+```
+The selected physical network adapter is not binded to the management virtual Switch.
+```
 
 ## Cause
 
 This issue occurs on deployments triggered after August 6th. The issue only happens if the deployment validation was triggered on the cluster and the validation result was a failure, with subsequent validation retries.
 
-The mismatch occurs for the following reason:
-- Validation on the device creates a VM Switch for network related tests and is deleted at the end of tests.
-- DeviceManagementExtension extension is not detecting this deletion of the VM Switch.
+The issue occurs for the following reason:
+
+- Validation on the device creates a VM switch for network related tests and is deleted at the end of tests.
+- `DeviceManagementExtension` extension is not detecting the deletion of the VM switch.
 
 ## Recommended resolution
 
+The multi-step resolution process includes the following steps:
 
+- [Remove the lock from the seed node](#remove-the-lock-from-the-seed-node)
+- [Remove the validation error](#remove-the-validation-error)
+- [Clean up the Edge Device Azure Resource with incorrect VM switch information](#clean-up-the-edge-device-azure--resource-with-incorrect-vm-switch-information)
+- [Refresh the cloud data](#refresh-the-cloud-edgedevices-data)
+- [Redo the Azure portal](#redo-the-azure-portal)
+- [Recreate the lock on the seed node resource](#recreate-the-lock-on-the-seed-node-resource)
 
 ### Remove the lock from the seed node
 
-> All steps below only need to be performed for the seed node.
+> [!NOTE]
+> All the steps in this section need to be performed on the seed node.
 
 Follow this multi-step process to mitigate this validation error:
 
 1. To remove the lock, in the Azure portal, go to the object via the resource group or within Machines - Azure Arc.  
 1. In the left-pane, go to **Settings > Locks**.  You should see a lock named **DoNotDelete**. This is the automatic resource lock that is created when the node is onboarded.
 1. Select **Delete** against the lock.
 
-If you attmept the steps in the next section without removing the lock, the Delete command will fail with the following error:
+If you attmept the steps in the next section without removing the lock, the **Delete** command fails with the following error:
 
-```Output
+```
 Some resources failed to be deleted (run with `--verbose` for more information):
 /subscriptions/<subid>/resourceGroups/<rgname>/providers/Microsoft.HybridCompute/machines/<machinename>/providers/Microsoft.AzureStackHCI/edgeDevices/default
 ```
 
-Running the `--verbose` switch provides the following additional output:
+Here is the example output when run with the `--verbose` switch:
 
 ```Output
 (ScopeLocked) The scope '/subscriptions/<subid>/resourceGroups/<rgname>/providers/Microsoft.HybridCompute/machines/<machinename>/providers/Microsoft.AzureStackHCI/edgeDevices/default' cannot perform delete operation because following scope(s) are locked: '/subscriptions/<subid>/resourceGroups/<rgname>/providers/Microsoft.HybridCompute/machines/<machinename>'. Please remove the lock and try again.
@@ -71,21 +89,21 @@ With the lock removed, follow these steps to remove the validation error.
     Get-VMSwitch
     ```
 
-1. Check the output of the `Get-VMSwitch` command for any unexpected VM Switches, for example, the switch that gets created during the Network Validation step and has a name similar to: `"ConvergedSwitch(compute_management)"`. The name of the switch depends on the chosen network intent configuration.
+1. Check the output of the `Get-VMSwitch` command for any unexpected VM switches, for example, the switch that gets created during the Network Validation step and has a name similar to: `"ConvergedSwitch(compute_management)"`. The exact name of the switch depends on the chosen network intent configuration.
 
-1. If a VM switch that you didn't intentionally create (like the one named above) exists, remove the switch. Run the following PowerShell command:
+1. If a VM switch that you didn't intentionally create exists, remove the switch. Run the following PowerShell command:
 
     ```PowerShell
     Remove-VMSwitch -Name "<VM Switch Name>" -Force
     ```
-    Make sure to use the VM switch name from the `Get-VMSwitch` command. If you didn't intentionally create a VM switch, the Get-VMSwitch command will have no results.
-   - **Note 2:** If the customer did not intentionally create a VM Switch, it is likely that the output of the `Get-VMSwitch` command will have no results, this is due to the fact that the Network Validation Step cleaned this VM Switch up, and it is the DeviceManagementExtension that did not detect the cleanup, leaving the Deployment Validation in this fail state.
+
+    Make sure to use the VM switch name from the `Get-VMSwitch` command. If you didn't intentionally create a VM switch, the `Get-VMSwitch` command will have no results. The failure occurs because the Network Validation Step cleaned up the VM switch, but the `DeviceManagementExtension` didn't detect the cleanup.
 
 1. Confirm the device cleanup and wait for the cleanup to complete.
 
-### Clean up the Edge Device Azure  Resource with incorrect VM Switch information
+### Clean up the Edge Device Azure Resource with incorrect VM switch information
 
-After the VM switch on the device is removed, clean up the Edge Device ARM resource containing the incorrect VM switch information. This ARM side cleanup can be done via AZ CLI.
+After the VM switch on the device is removed, clean up the Edge Device ARM resource containing the incorrect VM switch information via the Azure CLI.
 
 1. On a machine that the customer uses with access to Azure, verify install or install AZ CLI: [Install Azure CLI on Windows](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-windows?tabs=azure-cli)
    - You can verify install by running: `az`
@@ -133,7 +151,9 @@ Message: The resource 'Microsoft.HybridCompute/machines/<machineNAME>/providers/
 
 ### Refresh the cloud `edgeDevices` data
 
-With the ARM resource and all the unintentional VM switches removed, refresh the cloud-side `edgeDevices` data again. Follow these steps to refresh the cloud data:
+With the ARM resource and all the unintentional VM switches removed, refresh the cloud-side `edgeDevices` data again. 
+
+Follow these steps to refresh the cloud data:
 
 1. Restart the `DeviceManagementService` on the seed node. Run the following PowerShell command:
 
@@ -148,27 +168,31 @@ With the ARM resource and all the unintentional VM switches removed, refresh the
 
 ### Redo the Azure portal
 
-With device and cloud-side data now back in sync, you can go to the Azure portal and navigate to Basics tab in the deployment UX. This should prevent any cached information from previous attempts. Follow these steps in the Azure portal:
+With device and cloud data now back in sync, you can go to the Azure portal and provide the deployment inputs. The previous step prevents any cached information from previous attempts. 
+
+Follow these steps in the Azure portal:
   
 1. On the **Basics** tab, provide your inputs (by selecting from the dropdowns once again) to the fields from the top.
 
 1. Uncheck the nodes at the bottom of the page.
 
 1. Revalidate the reselected nodes.
 
-1. Confirm the information on the subsequent pages. 
-    - **Note:** When you get to the Network page, you should no longer see the `"The selected physical network adapter is no binded to the management virtual Switch"` error that might have been seen previously.
-    - When you get to the Validation page at the end, you should know if you are past the original issue, as the `"deploymentdata.physicalnodes[0].ipv4address is not a valid IPv4 address"` error should no longer immediately pop.
-1. If no other/different validation issues occur, the Deployment should be ready to kick off and run.
+1. Confirm the information on the subsequent pages. You should see the following changes:
+    - On the **Network** page, you should no longer see the `"The selected physical network adapter is no binded to the management virtual Switch"` error that might have been seen previously.
+    - On the **Validation** page at the end, if you are past the original issue, the `"deploymentdata.physicalnodes[0].ipv4address is not a valid IPv4 address"` error won't be displayed.
 
+1. If no other validation issues occur, start the deployment.
 
-> :ledger: **NOTE**
->
-> Once the mitigation has been completed, it is **HIGHLY** recommended to recreate the lock on the resource.  Steps for this are included after the mitigation steps.
+### Recreate the lock on the seed node resource
 
-Once mitigation is successful, you should recreate the lock on the seed node resource.  To do this, navigate to the object via the resource group or within 'Machines - Azure Arc'.  Expand 'Settings' in the left column, then click on 'Locks'.  Click '**+ Add**' at the top of the page.  
+After the mitigation is complete, we strongly recommend that you recreate the lock on the resource.
 
-For 'Lock name', enter '**DoNotDelete**'.  
-For 'Lock type', select '**Delete**' from the drop-down.
+Follow these steps to recreate the lock:
 
-Click 'OK' to save the lock.
+1. In the Azure portal, go to the object via the resource group or within **Machines - Azure Arc**.  
+1. Expand '**Settings** in the left column, then select  **Locks**.  
+1. Select '**+ Add**' at the top of the page.
+    1. For **Lock name**, enter **DoNotDelete**.
+    1. For **Lock type**, select '**Delete**' from the drop-down.
+1. Select **OK** to save the lock.