Merge pull request #298427 from robertstarling/icm618958784-run-read-control-node

clarify that run-read-command requires a control-plane BMM

Author: prmerger-automator[bot]

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

@@ -1,7 +1,7 @@
 ---
 title: Best practices for Bare Metal Machine operations
 description: Steps that should be taken before executing any Bare Metal Machine replace, or reimage actions. Highlight essential prerequisites and common pitfalls to avoid.
-ms.date: 03/25/2025
+ms.date: 04/17/2025
 ms.topic: how-to
 ms.service: azure-operator-nexus
 ms.custom: template-how-to, best-practices
@@ -63,8 +63,9 @@ Connected
 
 Take a deeper look at the NetworkFabric resources by checking the NetworkFabric resources statuses, alerts, and metrics.
 See related articles:
-  - [How to monitor interface In and Out packet rate for network fabric devices]
-  - [How to configure diagnostic settings and monitor configuration differences in Nexus Network Fabric].
+
+- [How to monitor interface In and Out packet rate for network fabric devices]
+- [How to configure diagnostic settings and monitor configuration differences in Nexus Network Fabric].
 
 Evaluate for any Bare Metal Machine warnings or degraded conditions which could indicate the need to resolve hardware, network, or server configuration problems.
 For more information, see [Troubleshoot Degraded Status Errors on Bare Metal Machines] and [Troubleshoot Bare Metal Machine Warning Status].
@@ -73,7 +74,9 @@ For more information, see [Troubleshoot Degraded Status Errors on Bare Metal Mac
 
 Validate that there are no running firmware upgrade jobs through the BMC before initiating a `replace` or `reimage` operation.
 Interrupting an ongoing firmware upgrade can leave the Bare Metal Machine in an inconsistent state.
-You can view in the iDRAC GUI the `jobqueue` or use a `racadm jobqueque view` to determine if there are firmware upgrade jobs running.
+
+- You can view in the iDRAC GUI the `jobqueue` or use `run-read-command` `racadm jobqueque view` to determine if there are firmware upgrade jobs running.
+- For more information about the `run-read-command` feature, see [BareMetal Run-Read Execution](./howto-baremetal-run-read.md).
 
 ```azurecli
 az networkcloud baremetalmachine run-read-command \
@@ -86,6 +89,7 @@ az networkcloud baremetalmachine run-read-command \
 ```
 
 Here's an example output from the `racadm jobqueue view` command which shows `Firmware Update`.
+
 ```
 [Job ID=JID_833540920066]
 Job Name=Firmware Update: iDRAC
@@ -97,6 +101,7 @@ Percent Complete= [50%]
 ```
 
 Here's an example output from the `racadm jobqueue view` command showing common happy-path statements.
+
 ```
 -------------------------JOB QUEUE------------------------
 [Job ID=JID_429400224349]
@@ -191,9 +196,10 @@ Some repairs don't require a Bare Metal Machine `replace` to be executed.
 For example, a `replace` operation isn't required when you're performing a physical hot swappable power supply repair because the Bare Metal Machine host will continue to function normally after the repair.
 However, if the Bare Metal Machine failed hardware validation, the Bare Metal Machine `replace` is required even if the hot swappable repairs are done.
 Examine the Bare Metal Machine status messages to determine if hardware validation failures or other degraded conditions are present.
-  - [Troubleshoot Degraded Status Errors on Bare Metal Machines]
-  - [Troubleshoot Bare Metal Machine Warning Status]
-  - [Troubleshoot Hardware Validation Failure](./troubleshoot-hardware-validation-failure.md).
+
+- [Troubleshoot Degraded Status Errors on Bare Metal Machines]
+- [Troubleshoot Bare Metal Machine Warning Status]
+- [Troubleshoot Hardware Validation Failure](./troubleshoot-hardware-validation-failure.md).
 
 Other repairs of this type might be:
 
@@ -247,4 +253,4 @@ For more information about Support plans, see [Azure Support plans](https://azur
 [Troubleshoot Degraded Status Errors on Bare Metal Machines]: ./troubleshoot-bare-metal-machine-degraded.md
 [Troubleshoot Hardware Validation Failure]: ./troubleshoot-hardware-validation-failure.md
 [How to monitor interface In and Out packet rate for network fabric devices]: ./howto-monitor-interface-packet-rate.md
-[How to configure diagnostic settings and monitor configuration differences in Nexus Network Fabric]: ./howto-configure-diagnostic-settings-monitor-configuration-differences.md
+[How to configure diagnostic settings and monitor configuration differences in Nexus Network Fabric]: ./howto-configure-diagnostic-settings-monitor-configuration-differences.md

articles/operator-nexus/howto-baremetal-run-read.md

@@ -5,7 +5,7 @@ author: eak13
 ms.author: ekarandjeff
 ms.service: azure-operator-nexus
 ms.topic: how-to
-ms.date: 2/13/2025
+ms.date: 4/17/2025
 ms.custom: template-how-to
 ---
 
@@ -30,7 +30,7 @@ See [Azure Operator Nexus Cluster support for managed identities and user provid
 
 To change the cluster from a user-assigned identity to a system-assigned identity, the CommandOutputSettings must first be cleared using the command in the next section, then set using this command.
 
-The CommandOutputSettings can be cleared, directing run-data-extract output back to the cluster manager's storage. However, it isn't recommended since it's less secure, and the option will be removed in a future release.
+The CommandOutputSettings can be cleared, directing run-read-command output back to the cluster manager's storage. However, it isn't recommended since it's less secure, and the option will be removed in a future release.
 
 However, the CommandOutputSettings do need to be cleared if switching from a user-assigned identity to a system-assigned identity.
 
@@ -246,17 +246,19 @@ This list shows the commands you can use. Commands in `*italics*` can't have `ar
 The command syntax for a single command with no arguments is as follows, using `hostname` as an example:
 
 ```azurecli
-az networkcloud baremetalmachine run-read-command --name "<machine-name>"
+az networkcloud baremetalmachine run-read-command --name "<bareMetalMachineName>"
     --limit-time-seconds "<timeout>" \
     --commands "[{command:hostname}]" \
     --resource-group "<cluster_MRG>" \
     --subscription "<subscription>"
 ```
 
+- `--name` is the name of the BMM resource on which to execute the command.
 - The `--commands` parameter always takes a list of commands, even if there's only one command.
 - Multiple commands can be provided in json format using [Azure CLI Shorthand](https://aka.ms/cli-shorthand) notation.
 - Any whitespace must be enclosed in single quotes.
 - Any arguments for each command must also be provided as a list, as shown in the following examples.
+- Not all commands can run on any BMM. For example, `kubectl` commands can only be run from a BMM with the `control-plane` role.
 
 ```
 --commands "[{command:hostname},{command:'nc-toolbox nc-toolbox-runread racadm ifconfig'}]"

articles/operator-nexus/troubleshoot-bare-metal-machine-warning.md

@@ -4,7 +4,7 @@ description: Troubleshooting guide for Bare Metal Machines Warning status messag
 ms.service: azure-operator-nexus
 ms.custom: azure-operator-nexus
 ms.topic: troubleshooting
-ms.date: 03/03/2025
+ms.date: 04/17/2025
 author: robertstarling
 ms.author: robstarling
 ms.reviewer: ekarandjeff
@@ -46,7 +46,7 @@ For more information, use an Azure CLI Bare Metal Machine `run-read-command` com
 ```azurecli
 az networkcloud baremetalmachine run-read-command \
   -g <ResourceGroup_Name> \
-  -n <BareMetal Machine Name> \
+  -n rack1control01 \
   --limit-time-seconds 60 \
   --commands "[{command:'kubectl get',arguments:[-n,nc-system,bmm,rack1compute01,-o,json]}]" \
   --output-directory .

articles/operator-nexus/troubleshoot-memory-limits.md

@@ -4,7 +4,7 @@ description: Learn how to troubleshoot Kubernetes container limits.
 ms.service: azure-operator-nexus
 ms.custom: troubleshooting
 ms.topic: troubleshooting
-ms.date: 11/01/2024
+ms.date: 04/17/2025
 ms.author: matthewernst
 author: matternst7258
 ---
@@ -19,18 +19,21 @@ We recommend that you have alerts set up for the Azure Operator Nexus cluster to
 
 The following table lists the metrics that are exposed to identify memory limits.
 
-| Metric name                          | Description                                      |
-| ------------------------------------ | ------------------------------------------------ |
-| Container Restarts                   | `kube_pod_container_status_restarts_total`       |
-| Container Status Terminated Reason   | `kube_pod_container_status_terminated_reason`    |
-| Container Resource Limits            | `kube_pod_container_resource_limits`             |
+| Metric name                        | Description                                   |
+| ---------------------------------- | --------------------------------------------- |
+| Container Restarts                 | `kube_pod_container_status_restarts_total`    |
+| Container Status Terminated Reason | `kube_pod_container_status_terminated_reason` |
+| Container Resource Limits          | `kube_pod_container_resource_limits`          |
 
 The `Container Status Terminated Reason` metric displays the `OOMKill` reason for pods that are affected.
 
 ## Identify Out of Memory (OOM) pods
 
 Start by identifying any components that are restarting or show `OOMKill`.
 
+- Replace `<bareMetalMachineName>` with the name of a healthy `control-plane` Bare Metal Machine resource on which to execute the `kubectl` command.
+- For more information about the `run-read-command` feature, see [BareMetal Run-Read Execution](./howto-baremetal-run-read.md).
+
 ```azcli
 az networkcloud baremetalmachine run-read-command --name "<bareMetalMachineName>" \
    --limit-time-seconds 60 \
@@ -92,6 +95,6 @@ az networkcloud baremetalmachine run-read-command --name "<bareMetalMachineName>
 
 ## Known services susceptible to OOM issues
 
-* cdi-operator
-* vulnerability-operator
-* cluster-metadata-operator
+- cdi-operator
+- vulnerability-operator
+- cluster-metadata-operator