docs: document expected machine interfaces

Explain the interface roles and IP allocation policies available during Expected Machine ingestion.

Cover segment selection, Host BMC compatibility, legacy aliases, update behavior, and reservation-only network segments.

This supports #4151

Signed-off-by: Chet Nichols III <chetn@nvidia.com>

Author: chet

docs/index.yml

@@ -117,6 +117,8 @@ navigation:
           path: provisioning/ingesting-hosts.md
         - page: Ingesting Hosts (REST API)
           path: provisioning/ingesting-hosts-rest-api.md
+        - page: Configure Expected Machine Interfaces
+          path: provisioning/expected-machine-interfaces.md
         - page: Site Setup API Parity
           path: provisioning/site-setup-api-parity.md
         - page: Boot Interfaces and DPU Policies

docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md

@@ -13,11 +13,12 @@ nico-admin-cli-expected-machine-add - Add expected machine
 \[**-p**\|**--bmc-password**\] \<**-s**\|**--chassis-serial-number**\>
 \[**-d**\|**--fallback-dpu-serial-number**\] \[**--meta-name**\]
 \[**--meta-description**\] \[**--label**\] \[**--sku-id**\] \[**--id**\]
-\[**--host_nics**\] \[**--rack_id**\]
+\[**--interfaces**\] \[**--rack_id**\]
 \[**--default_pause_ingestion_and_poweron**\] \[**--dpf-enabled**\]
 \[**--extended**\] \[**--bmc-ip-address**\]
 \[**--bmc-retain-credentials**\] \[**--dpu-policy**\]
-\[**--disable-lockdown**\] \[**--sort-by**\] \[**-h**\|**--help**\]
+\[**--bmc-ip-allocation**\] \[**--disable-lockdown**\] \[**--sort-by**\]
+\[**-h**\|**--help**\]
 
 ## DESCRIPTION
 
@@ -63,9 +64,18 @@ A SKU ID that will be added for the newly created Machine.
 **--id** *\<UUID\>*  
 Optional unique ID to assign to the ExpectedMachine on create
 
-**--host_nics** *\<HOST_NICS\>*  
-Host NICs as a JSON array of ExpectedHostNic objects (fields:
-mac_address, nic_type, fixed_ip, fixed_mask, fixed_gateway, primary)
+**--interfaces** *\<INTERFACES\>*\
+Interfaces as a JSON array of ExpectedInterface objects (fields:
+mac_address, role, ip_allocation, network_segment_type, fixed_ip,
+fixed_mask, fixed_gateway, primary; legacy: nic_type). Accepted values:
+role=host\|dpu_os\|dpu_bmc\|host_bmc and
+ip_allocation=dynamic\|fixed\|retained. An omitted role defaults to host.
+When ip_allocation is omitted, fixed_ip implies fixed; without fixed_ip,
+host_bmc defaults to retained and every other role defaults to dynamic.
+Explicit fixed policies, DPU fixed addresses, and inferred host_bmc fixed
+addresses with a segment guard must fall within a configured managed
+prefix. Legacy host entries with an omitted policy and unguarded inferred
+host_bmc fixed addresses keep the static-assignments fallback.
 
 **--rack_id** *\<RACK_ID\>*  
 Rack ID for this machine
@@ -132,6 +142,29 @@ The previous \`use-as-nic\` value remains accepted as an alias. The legacy
 
 - ignore
 
+**--bmc-ip-allocation** *\<BMC_IP_ALLOCATION\>*\
+Per-host control over how this BMC's IP is assigned and retained.
+\`auto\` (default): infer from \`--bmc-ip-address\` -- a configured
+address is \`fixed\`, no address is \`retained\`; \`dynamic\`: a normal
+DHCP lease that may expire and change; \`fixed\`: the operator-specified
+\`--bmc-ip-address\` (static); \`retained\`: an auto-allocated address
+kept Static for the lifetime of its interface record. Unset defers to
+the server default (\`auto\`). See
+[Retained Address Lifetime](../../../../provisioning/expected-machine-interfaces.md#retained-address-lifetime).\
+
+\
+*Possible values:*
+
+- unspecified
+
+- auto
+
+- dynamic
+
+- fixed
+
+- retained
+
 **--disable-lockdown** *\<DISABLE_LOCKDOWN\>*  
 If true, do not lock down the server as part of lifecycle management
 within the state machine. If unset or false, preserve the default
@@ -159,11 +192,18 @@ Print help (see a summary with -h)
 
 ## Examples
 
+> **Security:** Values passed to `--bmc-password` can appear in shell history
+> and process listings. Substitute credentials only in a protected
+> administrative environment and follow your site's secret-handling policy.
+
 ```sh
-nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password mypassword --chassis-serial-number sample_serial-1
-nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password mypassword --chassis-serial-number sample_serial-1 --meta-name MyMachine --label DATACENTER:XYZ --sku-id DGX-H100-640GB
-nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password mypassword --chassis-serial-number sample_serial-1 --bmc-ip-address 192.0.2.20
-nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password mypassword --chassis-serial-number sample_serial-1 --dpu-policy nic
+nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password '<bmc-password>' --chassis-serial-number sample_serial-1
+nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password '<bmc-password>' --chassis-serial-number sample_serial-1 --meta-name MyMachine --label DATACENTER:XYZ --sku-id DGX-H100-640GB
+nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password '<bmc-password>' --chassis-serial-number sample_serial-1 --bmc-ip-address 192.0.2.20
+nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password '<bmc-password>' --chassis-serial-number sample_serial-1 --dpu-policy nic
+nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password '<bmc-password>' --chassis-serial-number sample_serial-1 --interfaces '[{"mac_address":"00:11:22:33:44:55","role":"host_bmc","ip_allocation":"retained"}]'
+nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password '<bmc-password>' --chassis-serial-number sample_serial-1 --interfaces '[{"mac_address":"02:00:00:00:20:01","role":"dpu_os","ip_allocation":"fixed","fixed_ip":"192.0.2.10"}]'
+nico-admin-cli expected-machine add --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password '<bmc-password>' --chassis-serial-number sample_serial-1 --bmc-ip-allocation retained
 ```
 
 ---

docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md

@@ -18,6 +18,7 @@ update, preserves unprovided fields).
 \[**--rack-id**\] \[**--default_pause_ingestion_and_poweron**\]
 \[**--dpf-enabled**\] \[**--bmc-ip-address**\] \[**--extended**\]
 \[**--bmc-retain-credentials**\] \[**--dpu-policy**\]
+\[**--bmc-ip-allocation**\] \[**--interfaces**\]
 \[**--disable-lockdown**\] \[**--sort-by**\] \[**-h**\|**--help**\]
 
 ## DESCRIPTION
@@ -138,6 +139,40 @@ to \`ignore\`.\
 
 - ignore
 
+**--bmc-ip-allocation** *\<BMC_IP_ALLOCATION\>*\
+Per-host control over how this BMC's IP is assigned and retained.
+\`auto\` (default): infer from \`--bmc-ip-address\` -- a configured
+address is \`fixed\`, no address is \`retained\`; \`dynamic\`: a normal
+DHCP lease that may expire and change; \`fixed\`: the operator-specified
+\`--bmc-ip-address\` (static); \`retained\`: an auto-allocated address
+kept Static for the lifetime of its interface record. Unset preserves
+the existing per-host value. See
+[Retained Address Lifetime](../../../../provisioning/expected-machine-interfaces.md#retained-address-lifetime).\
+
+\
+*Possible values:*
+
+- unspecified
+
+- auto
+
+- dynamic
+
+- fixed
+
+- retained
+
+**--interfaces** *\<INTERFACES\>*\
+Interfaces as a JSON array of ExpectedInterface objects (fields:
+mac_address, role, ip_allocation, network_segment_type, fixed_ip,
+fixed_mask, fixed_gateway, primary; legacy: nic_type). Accepted values:
+role=host\|dpu_os\|dpu_bmc\|host_bmc\|unspecified and
+ip_allocation=dynamic\|fixed\|retained\|unspecified. Replaces the
+machine's full interface list. For a matching stored MAC, omitting role
+preserves the stored role; role=unspecified resets it to host. Omitting
+ip_allocation preserves the stored policy when the presence of fixed_ip
+is unchanged; ip_allocation=unspecified resets it to fixed_ip inference.
+
 **--disable-lockdown** *\<DISABLE_LOCKDOWN\>*  
 If true, do not lock down the server as part of lifecycle management
 within the state machine. If unset or false, preserve the default
@@ -165,11 +200,18 @@ Print help (see a summary with -h)
 
 ## Examples
 
+> **Security:** Values passed to `--bmc-password` can appear in shell history
+> and process listings. Substitute credentials only in a protected
+> administrative environment and follow your site's secret-handling policy.
+
 ```sh
 nico-admin-cli expected-machine patch --bmc-mac-address 00:11:22:33:44:55 --sku-id DGX-H100-640GB
 nico-admin-cli expected-machine patch --id 12345678-1234-5678-90ab-cdef01234567 --sku-id DGX-H100-640GB
-nico-admin-cli expected-machine patch --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password mynewpassword
+nico-admin-cli expected-machine patch --bmc-mac-address 00:11:22:33:44:55 --bmc-username admin --bmc-password '<bmc-password>'
 nico-admin-cli expected-machine patch --bmc-mac-address 00:11:22:33:44:55 --dpu-policy ignore
+nico-admin-cli expected-machine patch --bmc-mac-address 00:11:22:33:44:55 --bmc-ip-allocation retained
+nico-admin-cli expected-machine patch --bmc-mac-address 00:11:22:33:44:55 --interfaces '[{"mac_address":"02:00:00:00:20:01","fixed_ip":"192.0.2.10"}]'
+nico-admin-cli expected-machine patch --bmc-mac-address 00:11:22:33:44:55 --interfaces '[{"mac_address":"02:00:00:00:20:01","role":"unspecified","ip_allocation":"unspecified","fixed_ip":"192.0.2.10"}]'
 ```
 
 ---