Skip to content

docs: document expected machine interfaces #4418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chet wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document expected machine interfaces #4418

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/index.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
58 changes: 49 additions & 9 deletions docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Comment on lines +67 to +78

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Document the legacy interface-option alias consistently.

Both generated pages advertise --interfaces but omit the supported --host_nics alias.

  • docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L67-L78: document --host_nics as the legacy alias for --interfaces.
  • docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L165-L175: document the same alias and regenerate both pages from the shared CLI source.
📍 Affects 2 files
  • docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L67-L78 (this comment)
  • docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L165-L175
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md`
around lines 67 - 78, Update the shared CLI source that generates the
expected-machine interface option documentation to identify --host_nics as the
legacy alias for --interfaces, then regenerate both pages:
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md
lines 67-78 and
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md
lines 165-175. Ensure both generated descriptions consistently document the
alias.

Source: Learnings


**--rack_id** *\<RACK_ID\>*
Rack ID for this machine
Expand Down Expand Up @@ -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
Comment on lines +145 to +166

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Align BMC allocation documentation with the server contract.

Both pages list unspecified without defining it and omit the invalid combination rules for bmc_ip_address with Dynamic or Retained allocation.

  • docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L145-L166: define unspecified and state the rejected combinations for add.
  • docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L142-L163: define unspecified and state the same rejected combinations for patch.
📍 Affects 2 files
  • docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L145-L166 (this comment)
  • docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L142-L163
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md`
around lines 145 - 166, The BMC allocation documentation omits the meaning of
unspecified and the invalid bmc_ip_address combinations. Update the
bmc-ip-allocation sections in
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md
lines 145-166 and
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md
lines 142-163 to define unspecified according to the server contract and state
that supplying bmc_ip_address with dynamic or retained allocation is rejected;
keep both pages consistent.


**--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
Expand Down Expand Up @@ -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
```

---
Expand Down
44 changes: 43 additions & 1 deletion docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

Comment on lines +171 to +175

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Document that omitted network_segment_type clears the stored guard.

The patch description explains preservation/reset behavior for role and ip_allocation, but omits the distinct behavior for network_segment_type: when omitted, the stored segment guard is cleared. State this explicitly to prevent operators from assuming the guard is preserved.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md`
around lines 171 - 175, Update the patch description covering stored MAC
matching to explicitly state that omitting network_segment_type clears the
stored segment guard, distinguishing this from the preservation behavior
documented for role and ip_allocation.

**--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
Expand Down Expand Up @@ -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"}]'
```

---
Expand Down
Loading
Loading