actionState progress monitoring

Author: robertstarling

articles/operator-nexus/howto-bare-metal-best-practices.md

@@ -125,6 +125,60 @@ Message=[SYS043: Successfully exported Server Configuration Profile]
 Percent Complete=[100]
 ```
 
+#### Monitor progress using `run-read-command`
+
+You can monitor the progress of long running Bare Metal Machine actions using a `run-read-command`.
+
+- Some long running actions such as `Replace` or `Reimage` are composed of multiple steps, for example, `Hardware Validation`, `Deprovisioning`, or `Provisioning`.
+- The following `run-read-command` shows how to view the different steps in each action, and the progress or status of each step including any potential errors.
+- This information is available on the BareMetalMachine kubernetes resource during or after the action is completed.
+- For more information about the `run-read-command` feature, see [BareMetal Run-Read Execution](./howto-baremetal-run-read.md).
+
+Example `run-read-command` to view action progress on Bare Metal Machine `rack2compute08`:
+
+```azurecli
+az networkcloud baremetalmachine run-read-command \
+  -g <ResourceGroup_Name> \
+  -n <Control Node BMM Name> \
+  --limit-time-seconds 60 \
+  --commands "[{command:'kubectl get',arguments:[-n,nc-system,bmm,rack2compute08,-o,json]}]" \
+  --output-directory .
+```
+
+Example output for a Replace action:
+
+```json
+[
+  {
+    "correlationId": "961a6154-4342-4831-9693-27314671e6a7",
+    "endTime": "2025-05-15T21:20:44Z",
+    "startTime": "2025-05-15T20:16:19Z",
+    "status": "Completed",
+    "stepStates": [
+      {
+        "endTime": "2025-05-15T20:25:51Z",
+        "name": "Hardware Validation",
+        "startTime": "2025-05-15T20:16:19Z",
+        "status": "Completed"
+      },
+      {
+        "endTime": "2025-05-15T20:26:21Z",
+        "name": "Deprovisioning",
+        "startTime": "2025-05-15T20:25:51Z",
+        "status": "Completed"
+      },
+      {
+        "endTime": "2025-05-15T21:20:44Z",
+        "name": "Provisioning",
+        "startTime": "2025-05-15T20:26:21Z",
+        "status": "Completed"
+      }
+    ],
+    "type": "Microsoft.NetworkCloud/bareMetalMachines/replace"
+  }
+]
+```
+
 ## Best practices for a Bare Metal Machine reimage
 
 The Bare Metal Machine (BMM) `reimage` action is explained in [Bare Metal Machine Lifecycle Management Commands] and scenario procedures described in [Troubleshoot Azure Operator Nexus Server Problems].
@@ -176,7 +230,7 @@ Before initiating any `replace` operation, ensure the following preconditions ar
 - Perform high level checks covered in the article [Troubleshoot Bare Metal Machine Provisioning].
 - Evaluate any Bare Metal Machine warnings or degraded conditions which could indicate the need to resolve hardware, network, or server configuration problems before a `replace` operation.
   For more information, see [Troubleshoot Degraded Status Errors on Bare Metal Machines] and [Troubleshoot Bare Metal Machine Warning Status].
-- Validate Bare Metal Machine has been powered on.
+- Validate Bare Metal Machine is powered on.
 - Validate that there are no running firmware upgrade jobs.
   Follow steps in section [Determine if Firmware Update Jobs are Running](#determine-if-firmware-update-jobs-are-running).