Merge pull request #311614 from dominicbetts/aio-delete

AIO: Clarify delete instructions

Author: prmerger-automator[bot]

articles/iot-operations/deploy-iot-ops/howto-manage-update-uninstall.md

@@ -4,7 +4,7 @@ description: Use the Azure CLI or Azure portal to manage your Azure IoT Operatio
 author: dominicbetts
 ms.author: dobett
 ms.topic: how-to
-ms.date: 10/02/2025
+ms.date: 02/10/2026
 ms.custom:
   - devx-track-azurecli
   - sfi-image-nochange
@@ -236,11 +236,16 @@ az iot ops update --name <INSTANCE_NAME> --resource-group <RESOURCE_GROUP> --fea
 The Azure IoT Operations CLI and Azure portal offer different options for uninstalling Azure IoT Operations.
 
 > [!IMPORTANT]
-> If you want to clean up your cluster and resource group, it's recommended to first remove Azure IoT Operations from the cluster using the Azure IoT Operations CLI commands in the following section. Then, you can delete the resource group. Deleting the resource group directly will leave orphaned resources on the cluster.
+> To clean up your cluster and resource group, first remove Azure IoT Operations from the cluster using the Azure IoT Operations CLI commands in the following section. Then, you can delete the resource group. Deleting the resource group directly leaves orphaned resources on the cluster that may cause subsequent deployments to fail.
 
 
 ### [Azure portal](#tab/portal)
 
+> [!IMPORTANT]
+> Deleting the Azure IoT Operations instance in the Azure portal doesn't remove the dependencies that were created when you deployed Azure IoT Operations. To remove these dependencies, use the `az iot ops delete --name <INSTANCE_NAME> --resource-group <RESOURCE_GROUP> --include-deps` command described in the Azure CLI procedure.
+
+To delete an Azure IoT Operations instance using the Azure portal:
+
 1. In the [Azure portal](https://portal.azure.com), go to the resource group that contains your Azure IoT Operations instance, or search for and select **Azure IoT Operations**.
 
 1. Select the name of your Azure IoT Operations instance.
@@ -251,9 +256,6 @@ The Azure IoT Operations CLI and Azure portal offer different options for uninst
 
    :::image type="content" source="./media/howto-manage-update-uninstall/delete-instance.png" alt-text="A screenshot that shows deleting an Azure IoT Operations instance in the Azure portal.":::
 
-> [!NOTE]
-> Deleting the Azure IoT Operations instance in the Azure portal doesn't remove the dependencies that were created when you deployed Azure IoT Operations. To remove these dependencies, use the `az iot ops delete --name <INSTANCE_NAME> --resource-group <RESOURCE_GROUP> --include-deps` command described in the Azure CLI procedure.
-
 ### [Azure CLI](#tab/cli)
 
 Use the [az iot ops delete](/cli/azure/iot/ops#az-iot-ops-delete) command to delete the entire Azure IoT Operations deployment from a cluster. The `delete` command evaluates the Azure IoT Operations related resources on the cluster and presents a tree view of the resources to be deleted. The cluster should be online when you run this command.

articles/iot-operations/troubleshoot/troubleshoot.md

@@ -79,6 +79,28 @@ A deployment might fail if the cluster doesn't have sufficient resources for the
 
 To learn more about how to choose suitable values for these parameters, see [Configure broker settings for high availability, scaling, and memory usage](../manage-mqtt-broker/howto-configure-availability-scale.md).
 
+## Troubleshoot Azure IoT Operations uninstall
+
+To uninstall Azure IoT Operations, always use `az iot ops delete`, which handles the proper sequencing automatically and avoids the following issues:
+
+### Namespace stuck in "Terminating" status
+
+If you try to delete the namespace directly, finalizers on Azure IoT Operations resources such as the `Instance` custom resource block the deletion. The namespace gets stuck in a permanent "Terminating" state, leaving the cluster in a deadlock that's difficult to recover from without manual intervention.
+
+To resolve this issue, use `az iot ops delete` to delete an Azure IoT Operations instance.
+
+### Orphaned cluster-scoped resources
+
+If you force-delete the namespace by manually removing finalizers, cluster-scoped resources such as `ClusterRoles`, `ClusterRoleBindings`, `ValidatingWebhookConfigurations`, and `MutatingWebhookConfigurations` remain behind. These orphaned resources can block future Azure IoT Operations installations, requiring you to either clean up each resource manually or reset the entire cluster.
+
+To resolve this issue, use `az iot ops delete` to delete an Azure IoT Operations instance.
+
+### You see an "Instance must be deleted first" error message
+
+If you try to delete the Arc extension directly using `az k8s-extension delete`, a validation blocks the operation with a message saying the `Instance` must be deleted first. Don't try to manually delete the `Instance` custom resource.
+
+To resolve this issue, use `az iot ops delete` to delete an Azure IoT Operations instance and handle the proper sequencing automatically.
+
 ## Troubleshoot Azure Key Vault secret management
 
 If you see the following error message related to secret management, update your Azure Key Vault contents: