Tsg/update fails arc agent install

TSG/Update/README.md

@@ -33,3 +33,4 @@
 * [2509 | Update Service terminated repeatedly by ALM due to high memory usage](./Update-Service-terminated-repeatedly-by-ALM.md)
 * [2601 | Solution Update failed with error message "Access is denied" ] (./AZLUpdate2601.md)
 * [Test-AzStackHciARBStack: Fails on Non-Numeric Az CLI Extension Versions](./Test-AzStackHciARBStack-NonNumericAzCLIExtensionVersions.md)
+* [Update fails due to Arc Agent install failure (lockdown on azcmagent.log)](./Update-fails-due-to-Arc-Agent-install-failure.md)

TSG/Update/Update-fails-due-to-Arc-Agent-install-failure.md

@@ -0,0 +1,71 @@
+# Update Fails Due to Arc Agent Install Failure
+
+<table border="1" cellpadding="6" cellspacing="0" style="border-collapse:collapse; margin-bottom:1em;">
+  <tr>
+    <th style="text-align:left; width: 180px;">Component</th>
+    <td><strong>Arc Agent</strong></td>
+  </tr>
+  <tr>
+    <th style="text-align:left;">Applicable Scenarios</th>
+    <td><strong>Update</strong></td>
+  </tr>
+  <tr>
+    <th style="text-align:left;">Affected Versions</th>
+    <td><strong>Arc Agent versions below 1.62</strong></td>
+  </tr>
+</table>
+
+## Overview
+
+Azure Local update may fail during Arc agent installation due to a file locking issue. The Arc agent installer may encounter problems when trying to lock the existing `azcmagent.log` file under `C:\ProgramData\AzureConnectedMachineAgent\Log`, preventing it from completing successfully.
+
+> **Note:** This issue only affects Arc agent versions below 1.62. If you are running Arc agent 1.62 or later, this issue does not apply.
+
+### Check your Arc Agent version
+
+Run the following command on the affected node(s) to confirm the installed Arc Agent version:
+
+```powershell
+azcmagent version
+```
+
+If the version is **1.62 or later**, this issue does not apply and you do not need to follow the steps below.
+
+## Symptoms
+
+- Solution update fails during Arc agent installation step.
+- Arc agent install logs indicate a lockdown or file access issue.
+
+**Diagnosing the issue:**
+
+Check `C:\ImageComposition\ArcAgent\arcInstallLog.txt` on the affected node(s) for errors referencing a lockdown or inability to access the log file.
+
+**Observable behaviors:**
+
+- Update does not progress past the Arc agent installation phase.
+- The `arcInstallLog.txt` file on one or more nodes contains lockdown-related errors.
+
+## Resolution
+
+### Prerequisites
+
+- Remote PowerShell access or local console access to the affected cluster node(s).
+
+### Steps
+
+1. **Diagnose the issue**
+   Review the Arc agent install log on each affected node to confirm the lockdown error.
+
+   ```powershell
+   Get-Content "C:\ImageComposition\ArcAgent\arcInstallLog.txt" | Select-String -Pattern "lockdown"
+   ```
+
+2. **Move the existing log file**
+   Move the `azcmagent.log` file to a backup location outside of the `C:\ProgramData\AzureConnectedMachineAgent` directory. This allows the Arc agent installer to create a fresh log file without encountering the locking issue.
+
+   > **Note:** Repeat this step on all affected nodes in the cluster.
+
+3. **Retry the update**
+   Attempt the update again after the old log file has been moved. The Arc agent installer should now be able to proceed without the locking issue.
+
+---