Update BMC & SA password references to support URI

Gage Hugo · Gage Hugo · commit 425d7af4d232 · 2025-06-11T17:11:52.000-05:00
diff --git a/articles/operator-nexus/TOC.yml b/articles/operator-nexus/TOC.yml
@@ -483,6 +483,8 @@
           href: reference-acl-examples.md
     - name: Operator Nexus SKUs
       href: reference-operator-nexus-skus.md
+    - name: Password By Key Vault Reference
+      href: reference-key-vault-credential.md
 - name: Release Notes
   items:
     - name: 2024
diff --git a/articles/operator-nexus/howto-baremetal-functions.md b/articles/operator-nexus/howto-baremetal-functions.md
@@ -155,13 +155,15 @@ Use the `replace` command when a server encounters hardware issues requiring a c
 After the replacing components such as motherboard or Network Interface Card (NIC), the MAC address of Bare Metal Machine will change; however, the iDRAC IP address and hostname will remain the same.
 A `replace` **must** be executed after each hardware maintenance operation, read through [Best practices for a Bare Metal Machine replace](./howto-bare-metal-best-practices.md#best-practices-for-a-bare-metal-machine-replace) for more details.
 
+As of the 2506.2 release, the password value for iDRAC can be provided as a Key Vault Uniform Resource Identifier (URI) or password value. See [Key Vault Credential Reference](reference-key-vault-credential.md). Using a URI instead of a plaintext password provides extra security.
+
 [!INCLUDE [warning-do-not-run-multiple-actions](./includes/baremetal-machines/warning-do-not-run-multiple-actions.md)]
 
 ```azurecli
 az networkcloud baremetalmachine replace \
   --name <BareMetalMachineName> \
   --resource-group <resourceGroup> \
-  --bmc-credentials password=<IDRAC_PASSWORD> username=<IDRAC_USER> \
+  --bmc-credentials password=<PASSWORD_URI or IDRAC_PASSWORD> username=<IDRAC_USER> \
   --bmc-mac-address <IDRAC_MAC> \
   --boot-mac-address <PXE_MAC> \
   --machine-name <OS_HOSTNAME> \
@@ -173,7 +175,17 @@ If the `replace` action fails due to a hardware validation failure, the specific
 This information can also be found in the Activity Log for the Bare Metal Machine (Operator Nexus).
 The error code and error message are included the JSON properties of the corresponding `BareMetalMachines_Replace` operation.
 
-**Example 1: hardware validation fails due to invalid Baseboard Management Controller (BMC) credentials provided**
+**Example 1: Hardware validation fails due to invalid Key Vault URI for Baseboard Management Controller (BMC) credentials**
+
+```shell
+$ az networkcloud baremetalmachine replace --name rack1compute02 --resource-group hostedRG --bmc-credentials password=$KEY_VAULT_URI username=root --bmc-mac-address 00-00-5E-00-01-00 --boot-mac-address 00-00-5E-00-02-00 --machine-name RACK1COMPUTE02 --serial-number SN123435
+(failed to retrieve password from key vault) failed to get secret value from key vault: failed to get cluster key vault secret
+Code: failed to retrieve password from key vault
+Message: failed to retrieve password from key vault
+Response: 400 Bad Request
+```
+
+**Example 2: Hardware validation fails due to invalid Baseboard Management Controller (BMC) credentials provided**
 
 ```shell
 $ az networkcloud baremetalmachine replace --name rack1compute02 --resource-group hostedRG --bmc-credentials password=REDACTED username=root --bmc-mac-address 00-00-5E-00-01-00 --boot-mac-address 00-00-5E-00-02-00 --machine-name RACK1COMPUTE02 --serial-number SN123435
@@ -182,7 +194,7 @@ Code: None
 Message: BMC login unsuccessful: Fail - Unauthorized; System health test(s) failed: [Additional logs: Server power down at end of test failed with: Unauthorized]
 ```
 
-**Example 2: hardware validation fails due to networking failure**
+**Example 3: Hardware validation fails due to networking failure**
 
 ```shell
 $ az networkcloud baremetalmachine replace --name rack1compute02 --resource-group hostedRG --bmc-credentials password=REDACTED username=root --bmc-mac-address 00-00-5E-00-01-00 --boot-mac-address 00-00-5E-00-02-00 --machine-name RACK1COMPUTE02 --serial-number SN123435
diff --git a/articles/operator-nexus/howto-configure-cluster.md b/articles/operator-nexus/howto-configure-cluster.md
@@ -78,7 +78,7 @@ az networkcloud cluster create --name "<CLUSTER_NAME>" --location "<LOCATION>" \
   --cluster-service-principal application-id="<SP_APP_ID>" \
     password="$SP_PASS" principal-id="$SP_ID" tenant-id="<TENANT_ID>" \
   --subscription "<SUBSCRIPTION_ID>" \
-  --secret-archive "{key-vault-id:<KVRESOURCE_ID>, use-key-vault:true}" \
+  --secret-archive-settings "{identity-type:<ID_TYPE>, vault-uri:<VAULT_URI>}" \
   --cluster-type "<CLUSTER_TYPE>" --cluster-version "<CLUSTER_VERSION>" \
   --tags <TAG_KEY1>="<TAG_VALUE1>" <TAG_KEY2>="<TAG_VALUE2>"
 ```
@@ -105,7 +105,7 @@ az networkcloud cluster create --name "<CLUSTER_NAME>" --location "<LOCATION>" \
   --cluster-service-principal application-id="<SP_APP_ID>" \
     password="$SP_PASS" principal-id="$SP_ID" tenant-id="<TENANT_ID>" \
   --subscription "<SUBSCRIPTION_ID>" \
-  --secret-archive "{key-vault-id:<KVRESOURCE_ID>, use-key-vault:true}" \
+  --secret-archive-settings "{identity-type:<ID_TYPE>, vault-uri:<VAULT_URI>}" \
   --cluster-type "<CLUSTER_TYPE>" --cluster-version "<CLUSTER_VERSION>" \
   --tags <TAG_KEY1>="<TAG_VALUE1>" <TAG_KEY2>="<TAG_VALUE2>"
 ```
@@ -127,16 +127,16 @@ az networkcloud cluster create --name "<CLUSTER_NAME>" --location "<LOCATION>" \
 | AGGR_RACK_BMM             | Used for single rack deployment only, empty for multi-rack                                                                                              |
 | SA1_NAME                   | First Storage Appliance Device name                                                                                                                           |
 | SA2_NAME                   | Second Storage Appliance Device name                                                                                                                           |
-| SA1_PASS                   | First Storage Appliance admin password                                                                                                                        |
-| SA2_PASS                   | Second Storage Appliance admin password                                                                                                                        |
+| SA1_PASS                   | First Storage Appliance admin password reference URI or password value \*See [Key Vault Credential Reference](reference-key-vault-credential.md)                                                                                            |
+| SA2_PASS                   | Second Storage Appliance admin password reference URI or password value \*See [Key Vault Credential Reference](reference-key-vault-credential.md)                                                                                             |
 | SA_USER                   | Storage Appliance admin user                                                                                                                            |
 | SA1_SN                     | First Storage Appliance Serial Number                                                                                                                         |
 | SA2_SN                     | Second Storage Appliance Serial Number                                                                                                                         |
 | COMPX_RACK_RESOURCE_ID    | RackID for CompX Rack; repeat for each rack in compute-rack-definitions                                                                                 |
 | COMPX_RACK_SKU            | The Rack Stock Keeping Unit (SKU) for CompX Rack; repeat for each rack in compute-rack-definitions \*See [Operator Nexus Network Cloud Stock Keeping Unit (SKUs)](./reference-operator-nexus-skus.md) |
 | COMPX_RACK_SN             | Rack Serial Number for CompX Rack; repeat for each rack in compute-rack-definitions                                                                     |
 | COMPX_RACK_LOCATION       | Rack physical location for CompX Rack; repeat for each rack in compute-rack-definitions                                                                 |
-| COMPX_SVRY_BMC_PASS       | CompX Rack ServerY Baseboard Management Controller (BMC) password; repeat for each rack in compute-rack-definitions and for each server in rack         |
+| COMPX_SVRY_BMC_PASS       | CompX Rack ServerY Baseboard Management Controller (BMC) password reference URI or password value; repeat for each rack in compute-rack-definitions and for each server in rack \*See [Key Vault Credential Reference](reference-key-vault-credential.md)        |
 | COMPX_SVRY_BMC_USER       | CompX Rack ServerY BMC user; repeat for each rack in compute-rack-definitions and for each server in rack                                               |
 | COMPX_SVRY_BMC_MAC        | CompX Rack ServerY BMC MAC address; repeat for each rack in compute-rack-definitions and for each server in rack                                        |
 | COMPX_SVRY_BOOT_MAC       | CompX Rack ServerY boot Network Interface Card (NIC) MAC address; repeat for each rack in compute-rack-definitions and for each server in rack          |
@@ -157,6 +157,8 @@ az networkcloud cluster create --name "<CLUSTER_NAME>" --location "<LOCATION>" \
 | TAG_VALUE1                | Optional tag1 value to pass to Cluster Create                                                                                                           |
 | TAG_KEY2                  | Optional tag2 to pass to Cluster Create                                                                                                                 |
 | TAG_VALUE2                | Optional tag2 value to pass to Cluster Create                                                                                                           |
+| ID_TYPE                   | See [Cluster Support for Managed Identities](./howto-cluster-managed-identity-user-provided-resources.md#key-vault-settings) for details on secret-archive-settings                               |
+| VAULT_URI                 | See [Cluster Support for Managed Identities](./howto-cluster-managed-identity-user-provided-resources.md#key-vault-settings) for details on secret-archive-settings                               |
 
 ## Cluster Identity
 
diff --git a/articles/operator-nexus/reference-key-vault-credential.md b/articles/operator-nexus/reference-key-vault-credential.md
@@ -0,0 +1,64 @@
+---
+title: "Azure Operator Nexus: Password By Key Vault Reference"
+description: Reference for using a key vault secret reference instead of a plaintext password
+author: ghugo
+ms.author: gagehugo
+ms.service: azure-operator-nexus
+ms.topic: how-to
+ms.date: 05/20/2025
+---
+
+# Password by Key Vault reference
+
+This guide details how to configure a Cluster for deployment using a Key Vault Uniform Resource Identifier (URI) instead of a plaintext password. This credential is used when creating or updating an Azure Operator cluster and can be located in the same key vault configured in `--secret-archive-settings` or a separate key vault. The key vault URI is used for deploying the cluster. Once the cluster is deployed, automatic credential rotation handles the rotation of the password.
+
+This Key Vault URI is used to retrieve the password value from the specified Key Vault as a one-time operation. Once this password value is retrieved, the URI is no longer used and the password is securely stored in the cluster.
+
+## Key Vault URI vs. Plaintext Password
+
+Using a key vault URI instead of a password provides extra security by avoiding the issue of using a plaintext value. The URI value isn't used once the Cluster Create/Update & Bare Metal Machine Replace Actions are complete.
+
+>[!NOTE]
+> This feature is supported for cluster create and update as part of the 2506.2 release. A later release is planned to remove support for using plaintext passwords.
+
+## Role Assignment
+
+The managed identity that is specified in the `--secret-archive-settings` field needs to be assigned the `Key Vault Secrets User` role on the key vault that contains the password. The role assignment is required so that the cluster can retrieve the password value from the URI value referenced. The `Key Vault Secrets User` role assignment is different than `Operator Nexus Key Vault Writer Service Role`, which is required for the automatic rotation of credentials.
+
+For more information on `--secret-archive-settings`, see [Cluster Support for Managed Identities](./howto-cluster-managed-identity-user-provided-resources.md#key-vault-settings).
+
+## Configuration for Base Management Controller (BMC) and Storage Appliance
+
+When a cluster is deployed, multiple passwords are provided as part of the configuration data. As of the 2506.2 release, the ability to pass in a URI reference value instead of a plaintext password was introduced.
+
+In these examples, the `KEY_VAULT_NAME` is the name of the key vault and `SECRET_NAME` is the name of the secret. If there are multiple versions of a secret, the `VERSION` can be appended to specify that particular version should be used.
+
+## Base Management Controller password
+
+```yaml
+"bareMetalMachineConfigurationData": [
+    {
+        "bmcCredentials": {
+            "username": "$BMC_USERNAME",
+            "password": "https://$KEY_VAULT_NAME.vault.azure.net/secrets/$SECRET_NAME/$VERSION"
+        },
+    }
+]
+```
+
+### Storage Appliance password
+
+```yaml
+"storageApplianceConfigurationData": [
+    {
+        "adminCredentials": {
+            "username": "pureuser",
+            "password": "https://$KEY_VAULT_NAME.vault.azure.net/secrets/$SECRET_NAME/$VERSION"
+        },
+    }
+]
+```
+
+### Bare Metal Machine replacement
+
+This key vault URI can also be provided for the password value when performing a bare metal machine replace: [Replace a Bare Metal Machine](./howto-baremetal-functions.md#replace-a-bare-metal-machine). The same [Role Assignment](#role-assignment) is needed to exist for this functionality to work.
