Updates

Author: sethmanheim

AKS-Arc/TOC.yml

@@ -194,7 +194,7 @@
     - name: BGP with FRR not working
       href: connectivity-troubleshoot.md
     - name: Cluster status stuck during upgrade
-      href: tsg-aksarc-upgrade-issues.md
+      href: tsg-upgrade-issues.md
   - name: Reference
     items:
     - name: Azure CLI

AKS-Arc/tsg-aksarc-upgrade-issues.md renamed to AKS-Arc/tsg-upgrade-issues.md

@@ -4,23 +4,25 @@ description: Learn how to troubleshoot and mitigate the issue when an AKS enable
 ms.topic: troubleshooting
 author: rcheeran
 ms.author: rcheeran
-ms.date: 06/25/2025
+ms.date: 06/26/2025
 ms.reviewer: abha
 
 ---
 
-# Troubleshoot the issue when the AKS Arc cluster is stuck in 'Upgrading' state
+# Troubleshoot AKS Arc cluster stuck in "Upgrading" state
 
-This article describes how to fix the issue when your Azure Kubernetes Service enabled by Arc (AKS Arc) cluster is stuck in 'Upgrading' state. This issue typically occurs after updating Azure Local to version 2503 or 2504 and when you try to upgrade the Kubernetes version on your cluster.
+This article describes how to fix an issue in which your Azure Kubernetes Service enabled by Arc (AKS Arc) cluster is stuck in the **Upgrading** state. This issue typically occurs after you update Azure Local to version 2503 or 2504, and you then try to upgrade the Kubernetes version on your cluster.
 
 ## Symptoms
 
-When you try to upgrade an AKS Arc cluster, you notice that the **Current state** property of the cluster remains in the 'Upgrading' state.
+When you try to upgrade an AKS Arc cluster, you notice that the **Current state** property of the cluster remains in the **Upgrading** state.
 
-```output
+```azurecli
 az aksarc upgrade --name "cluster-name" --resource-group "rg-name"
+```
 
-===> Kubernetes may be unavailable during cluster upgrades.
+```output
+===> Kubernetes might be unavailable during cluster upgrades.
  Are you sure you want to perform this operation? (y/N): y
 The cluster is on version 1.28.9 and is not in a failed state. 
 
@@ -44,10 +46,10 @@ Upgrading the AKSArc cluster. This operation might take a while...
         ...
 ```
 
-## Possible causes and follow-ups
+## Cause
 
-- The root cause is a recent change introduced in Azure Local version 2503. Under certain conditions, if there are transient or intermittent failures during the Kubernetes upgrade process, they're not correctly detected or recovered from. This can cause the cluster state to stay stuck in the 'Upgrading' state.
-- You hit this issue if the AKS Arc extension on your custom location - the `hybridaksextension` extension's version is 2.1.211 or 2.1.223. You can run the following command to check the extension version on your cluster:
+- The root cause is a recent change introduced in Azure Local version 2503. Under certain conditions, if there are transient or intermittent failures during the Kubernetes upgrade process, they're not correctly detected or recovered from. This can cause the cluster state to remain in the **Upgrading** state.
+- You see this issue if the AKS Arc extension on your custom location - the `hybridaksextension` extension version is 2.1.211 or 2.1.223. You can run the following command to check the extension version on your cluster:
 
 ```azurecli
 az login --use-device-code --tenant <Azure tenant ID> 
@@ -58,7 +60,7 @@ az k8s-extension show -g $res.HybridaksExtension.resourceGroup -c $res.ResourceB
 
 ## Mitigation
 
-This issue can be resolved by invoking the AKS Arc update command. The `update` command retriggers the upgrade flow. You can invoke the `aksarc update` command with placeholder parameters, which do not impact the state of the cluster. So in this case, you could invoke the update call to enable NFS or SMB drivers if those features aren't already enabled. First, check if any of the storage drivers are already enabled:
+You can resolve this issue by running the AKS Arc `update` command. The `update` command restarts the upgrade flow. You can run the `aksarc update` command with placeholder parameters, which do not impact the state of the cluster. So in this case, you can run the `update` command to enable NFS or SMB drivers if those features aren't already enabled. First, check if any of the storage drivers are already enabled:
 
 ```azurecli
 az login --use-device-code --tenant <Azure tenant ID> 
@@ -80,14 +82,14 @@ Check the storage profile section:
    }
 ```
 
-If one of the drivers is disabled, you can enable it using the following command:
+If one of the drivers is disabled, you can enable it using one of the following commands:
 
 ```azurecli
 az aksarc update --enable-smb-driver -g <resource_group_name> -n <cluster_name>
 az aksarc update --enable-nfs-driver -g <resource_group_name> -n <cluster_name>
 ```
 
-Running the `aksarc update` command should resolve the issue and the `Current state` parameter of the cluster should now show as 'Succeeded'. Once the status is updated, if you don't want to retain the drivers as enabled, you can revert this action by running the following command
+Running the `aksarc update` command should resolve the issue and the `Current state` parameter of the cluster should now show as **Succeeded**. Once the status is updated, if you don't want to retain the drivers as enabled, you can revert this action by running the following commands:
 
 ```azurecli
 az aksarc update --disable-smb-driver -g <resource_group_name> -n <cluster_name>
@@ -98,16 +100,15 @@ If both drivers are already enabled on your cluster, you can disable the one tha
 
 ## Verification
 
-Run the following command and check that the **Current State** parameter in the JSON output is set to 'Succeeded' to confirm the K8s version upgrade is complete.
+To confirm the K8s version upgrade is complete, run the following command and check that the `Current State` parameter in the JSON output is set to `Succeeded`.
 
 ```azurecli
 az aksarc show -g <resource_group> -n <cluster_name>
-
 ```
 
 ## Contact Microsoft Support
 
-If the problem persists, collect the following information before [creating a support request](aks-troubleshoot.md#open-a-support-request). Collect [AKS cluster logs](get-on-demand-logs.md) before creating the support request.
+If the problem persists, collect the [AKS cluster logs](get-on-demand-logs.md) before you [create a support request](aks-troubleshoot.md#open-a-support-request).
 
 ## Next steps