docs: document expected machine interfaces - #4418
Open
chet wants to merge 1 commit into
Open
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
Summary by CodeRabbit
WalkthroughDocuments the ChangesExpected Machine Interfaces
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
Author
|
@coderabbitai full_review, thanks! |
Contributor
|
🐇🔍 ✅ Action performedFull review finished. |
|
🌿 Preview your docs: https://nvidia-preview-pull-request-4418.docs.buildwithfern.com/infra-controller |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with 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.
Inline comments:
In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md`:
- Around line 67-78: Document the supported legacy --host_nics alias alongside
--interfaces in both
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 164-173, keeping the existing interface option description consistent
across both pages.
In `@docs/provisioning/expected-machine-interfaces.md`:
- Around line 179-181: Replace every copyable BMC password in the listed
Markdown examples with a clearly non-secret placeholder; update
docs/provisioning/expected-machine-interfaces.md at lines 179-181 and 226-232,
docs/provisioning/ip-and-network-configuration.md at lines 124-126,
docs/provisioning/ingesting-hosts.md at lines 246-248, and
docs/provisioning/boot-interfaces-and-dpu-modes.md at lines 110-112 and 129-131.
For the command-argument examples at expected-machine-interfaces.md lines
226-232 and boot-interfaces-and-dpu-modes.md lines 129-131, explicitly document
the shell-history and process-list exposure risk while keeping the examples
realistic and safe.
In `@docs/provisioning/ingesting-hosts.md`:
- Around line 228-233: Update the documentation for bmc_ip_address and
bmc_ip_allocation to state that Auto infers Fixed when an address is present,
while an explicit top-level allocation takes precedence over both the inferred
value and nested policy; clarify that an address is not necessarily reserved
when a different allocation is explicitly selected.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 6623cdbb-25a5-4cc6-9544-7f66ed9ccd0c
📒 Files selected for processing (7)
docs/index.ymldocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.mddocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.mddocs/provisioning/boot-interfaces-and-dpu-modes.mddocs/provisioning/expected-machine-interfaces.mddocs/provisioning/ingesting-hosts.mddocs/provisioning/ip-and-network-configuration.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with 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.
Inline comments:
In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md`:
- Around line 199-201: Update the three expected-machine add examples to replace
the literal BMC password “mypassword” with a clearly non-secret placeholder, and
add an explicit warning that command-line passwords may be exposed through shell
history and process listings.
- Around line 145-152: Update the retained-address description in
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md
lines 145-152 to say it remains static for the lifetime of the interface record
instead of “never expires.” Apply the same wording correction in
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md
lines 142-149 and link it to the retained-address lifetime section.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 652d4fd9-0949-4700-9a7b-a60b3a833787
📒 Files selected for processing (7)
docs/index.ymldocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.mddocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.mddocs/provisioning/boot-interfaces-and-dpu-modes.mddocs/provisioning/expected-machine-interfaces.mddocs/provisioning/ingesting-hosts.mddocs/provisioning/ip-and-network-configuration.md
Contributor
Author
|
@coderabbitai full_review, thanks! |
Contributor
|
🐇🔍 ✅ Action performedFull review finished. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/provisioning/expected-machine-interfaces.md`:
- Around line 132-136: Clarify the segment-guard wording in the explicit
allocation policy or DPU role section so rejection occurs only when a
network_segment_type guard is supplied and the selected segment has a different
type. State that the role alone does not impose a segment constraint, while
preserving the existing DHCP or fixed-address selection behavior and example.
- Around line 148-166: Update the “Allow Only Reserved Addresses” documentation
to explicitly describe how retained Expected Machine reservations behave on
reserved segments: state whether retained is unsupported or requires a
pre-seeded fixed reservation, and clarify the resulting interface
address-acquisition behavior so operators avoid an unusable configuration.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 11f7469a-3c68-4bb0-9ac6-06627d0e0f73
📒 Files selected for processing (7)
docs/index.ymldocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.mddocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.mddocs/provisioning/boot-interfaces-and-dpu-modes.mddocs/provisioning/expected-machine-interfaces.mddocs/provisioning/ingesting-hosts.mddocs/provisioning/ip-and-network-configuration.md
🚧 Files skipped from review as they are similar to previous changes (6)
- docs/provisioning/ingesting-hosts.md
- docs/index.yml
- docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md
- docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md
- docs/provisioning/boot-interfaces-and-dpu-modes.md
- docs/provisioning/ip-and-network-configuration.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with 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.
Inline comments:
In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md`:
- Around line 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.
- Around line 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.
In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md`:
- Around line 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.
In `@docs/provisioning/expected-machine-interfaces.md`:
- Around line 163-166: Clarify the Retained address behavior for
reservation-only segments in both
docs/provisioning/expected-machine-interfaces.md lines 163-166 and
docs/provisioning/ip-and-network-configuration.md lines 213-217: explicitly
state whether Retained is unsupported or requires a pre-seeded reservation, and
apply the same rule consistently in both procedures.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 5dde8219-53a5-4824-882e-3921ab392c32
📒 Files selected for processing (7)
docs/index.ymldocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.mddocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.mddocs/provisioning/boot-interfaces-and-dpu-modes.mddocs/provisioning/expected-machine-interfaces.mddocs/provisioning/ingesting-hosts.mddocs/provisioning/ip-and-network-configuration.md
10 tasks
chet
force-pushed
the
gh-issue-4151-docs
branch
from
August 7, 2026 06:59
ff8d460 to
5d25202
Compare
Contributor
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
Contributor
Author
|
@coderabbitai full_review, thanks! |
Contributor
|
🐇🔍 ✅ Action performedFull review finished. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/provisioning/expected-machine-interfaces.md`:
- Around line 239-259: Expand the “Configure Host BMC Allocation” documentation
to define the top-level credential contract: require bmc_mac_address and
bmc_username, allow CLI add to omit bmc_password as an empty string, and require
both credential fields for JSON updates and patches. Document
bmc_retain_credentials as an optional boolean defaulting to false on creation
and preserving its stored value when omitted during patching; clarify that
replacing interfaces, including interfaces: [], leaves top-level credentials and
retention settings unchanged.
- Around line 19-24: Update the expected machine interfaces documentation to
list unspecified as an accepted wire-level value for role and ip_allocation,
including that role "unspecified" resolves to host and ip_allocation
"unspecified" triggers inference. Document that matching interfaces in updates
reset these stored values to their defaults, and that em add, replace-all, and
patch JSON accept the sentinels without persisting them as unspecified.
- Around line 63-72: Update the inference documentation adjacent to the policy
table to explicitly describe the legacy role: host case: with fixed_ip and no
ip_allocation, resolve to fixed, select the containing managed prefix when
available, otherwise use static-assignments, and treat network_segment_type only
as an initial DHCP segment selector. Distinguish this legacy behavior from an
explicit ip_allocation: fixed configuration.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 07574cf7-b2a7-4c19-aca3-5becf36d0414
📒 Files selected for processing (7)
docs/index.ymldocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.mddocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.mddocs/provisioning/boot-interfaces-and-dpu-modes.mddocs/provisioning/expected-machine-interfaces.mddocs/provisioning/ingesting-hosts.mddocs/provisioning/ip-and-network-configuration.md
🚧 Files skipped from review as they are similar to previous changes (6)
- docs/provisioning/ingesting-hosts.md
- docs/index.yml
- docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md
- docs/provisioning/boot-interfaces-and-dpu-modes.md
- docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md
- docs/provisioning/ip-and-network-configuration.md
chet
changed the title
This was referenced Aug 11, 2026
chet
added a commit
that referenced
this pull request
Aug 11, 2026
A Retained BMC address becomes Static for the lifetime of its
machine-interface record. Calling it non-expiring made it sound like the
address was saved for reuse after that interface was deleted and
re-ingested, which it is not.
So, this updates the `nico-admin-cli expected-machine {add,patch}` help,
the model Rustdoc, and the protobuf comments to name the actual
lifetime. The checked-in REST protobuf mirrors are regenerated from the
updated source. CLI arguments, protobuf wire values, and allocation
behavior all stay the same.
## Related issues
- #4836
- #3491
## Type of Change
- [ ] **Add** - New feature or capability
- [ ] **Change** - Changes in existing functionality
- [ ] **Fix** - Bug fixes
- [ ] **Remove** - Removed features or deprecated functionality
- [x] **Internal** - Internal changes (refactoring, tests, docs, etc.)
## Breaking Changes
- [ ] **This PR contains breaking changes**
## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [x] Manual testing performed
- [ ] No testing required (docs, internal refactor, etc.)
- `cargo test -p nico-admin-cli` (427 passed)
- Rendered and inspected `nico-admin-cli expected-machine add --help`
- Rendered and inspected `nico-admin-cli expected-machine patch --help`
- Regenerated the REST Core protobuf snapshots and Go bindings, then
verified the worktree stayed clean
- `cargo make format-nightly`
- `cargo make clippy`
- Cached Carbide-lints workflow
## Additional Notes
The generated `nico-admin-cli` reference under `docs/` stays in the
separate docs-only #4151 / #4418 so the code and documentation review
paths remain independent.
Signed-off-by: Chet Nichols III <chetn@nvidia.com>
10 tasks
chet
force-pushed
the
gh-issue-4151-docs
branch
from
August 11, 2026 23:23
5d25202 to
db05e12
Compare
Contributor
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
chet
changed the title
Contributor
Author
|
@coderabbitai full_review, thanks! |
Contributor
|
🐇🔍 ✅ Action performedFull review finished. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with 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.
Inline comments:
In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md`:
- Around line 142-165: Update the --bmc-ip-allocation documentation to
distinguish explicit unspecified from an omitted option: unspecified resets the
stored policy to auto, while omission preserves the existing per-host value.
Clarify that auto resolves to fixed when --bmc-ip-address is provided and to
retained when no address is provided.
- Around line 166-179: Expand the --interfaces documentation to require
mac_address and describe new-entry defaults for role, ip_allocation, primary,
and network_segment_type. Document validation errors for malformed MAC/IP/enum
values, incompatible allocation with fixed_ip, unmanaged fixed addresses,
invalid primary declarations, duplicate MAC roles, and invalid host_bmc identity
or cardinality; also clarify that fixed_mask and fixed_gateway are optional
compatibility metadata.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 340cc5a5-5277-42bf-a5fd-e94af1e5543b
📒 Files selected for processing (7)
docs/index.ymldocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.mddocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.mddocs/provisioning/boot-interfaces-and-dpu-modes.mddocs/provisioning/expected-machine-interfaces.mddocs/provisioning/ingesting-hosts.mddocs/provisioning/ip-and-network-configuration.md
🚧 Files skipped from review as they are similar to previous changes (6)
- docs/index.yml
- docs/provisioning/expected-machine-interfaces.md
- docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md
- docs/provisioning/boot-interfaces-and-dpu-modes.md
- docs/provisioning/ingesting-hosts.md
- docs/provisioning/ip-and-network-configuration.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md (1)
142-164: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winDefine explicit
unspecifiedbehavior for BMC allocation.Both pages list
unspecifiedbut do not distinguish it from an omitted option.
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L142-L164: state that explicitunspecifiedresets the stored policy toauto, omission preserves the stored policy, andautoresolves tofixedwith--bmc-ip-addressorretainedwithout it.docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L147-L169: state the create-time behavior forunspecifiedand document thatdynamicorretainedcannot be combined with--bmc-ip-address.As per coding guidelines, document accepted values, defaults, interactions, and reset behavior.
🤖 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 142 - 164, Clarify BMC allocation semantics in docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md: explicitly state that unspecified resets the stored policy to auto, omission preserves the stored policy, and auto resolves to fixed when --bmc-ip-address is provided or retained otherwise. In docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md, document create-time behavior for unspecified and state that dynamic and retained cannot be combined with --bmc-ip-address; preserve the accepted-values documentation.Source: Coding guidelines
docs/provisioning/expected-machine-interfaces.md (1)
14-25: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winMake the interface contract complete across all documentation surfaces.
The canonical page and generated CLI pages do not expose one complete contract for accepted wire values, new-entry defaults, validation, and compatibility behavior.
docs/provisioning/expected-machine-interfaces.md#L14-L25: distinguish persisted values from accepted wire-levelunspecifiedvalues and document their create/update behavior.docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L67-L80: document the complete interface contract, including accepted sentinels, the legacy--host_nicsalias, requiredmac_address, and primary/host_bmcconstraints.docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L166-L178: document new-entry defaults and validation for malformed addresses, incompatiblefixed_ippolicies, unmanaged fixed addresses, invalid primary declarations, duplicate MAC roles, and invalidhost_bmcidentity or cardinality.As per coding guidelines, document requiredness, defaults, interactions, fallback behavior, and errors for interface contracts. Based on learnings, update generated CLI help at its shared source and regenerate the affected pages.
🤖 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/provisioning/expected-machine-interfaces.md` around lines 14 - 25, Complete the interface contract across docs/provisioning/expected-machine-interfaces.md:14-25, docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md:67-80, and docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md:166-178. Document persisted versus wire-level unspecified values, create/update behavior, defaults, validation, fallback and compatibility rules; include accepted sentinels, the --host_nics alias, required mac_address, primary/host_bmc constraints, malformed or unmanaged addresses, incompatible fixed_ip policies, duplicate MAC roles, and invalid host_bmc identity/cardinality. Update the shared generated CLI help source and regenerate both affected CLI pages.Sources: Coding guidelines, Path instructions, Learnings
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/provisioning/ip-and-network-configuration.md`:
- Around line 85-103: Clarify the Fixed policy description in the Expected
Interface IP Allocation section to include the legacy host fallback: a host
entry with fixed_ip and no explicit ip_allocation may use the static-assignments
fallback instead of requiring a managed segment prefix. Link to the canonical
rule if appropriate, while preserving the existing behavior for other Fixed
allocations.
---
Duplicate comments:
In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md`:
- Around line 142-164: Clarify BMC allocation semantics in
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md:
explicitly state that unspecified resets the stored policy to auto, omission
preserves the stored policy, and auto resolves to fixed when --bmc-ip-address is
provided or retained otherwise. In
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md,
document create-time behavior for unspecified and state that dynamic and
retained cannot be combined with --bmc-ip-address; preserve the accepted-values
documentation.
In `@docs/provisioning/expected-machine-interfaces.md`:
- Around line 14-25: Complete the interface contract across
docs/provisioning/expected-machine-interfaces.md:14-25,
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md:67-80,
and
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md:166-178.
Document persisted versus wire-level unspecified values, create/update behavior,
defaults, validation, fallback and compatibility rules; include accepted
sentinels, the --host_nics alias, required mac_address, primary/host_bmc
constraints, malformed or unmanaged addresses, incompatible fixed_ip policies,
duplicate MAC roles, and invalid host_bmc identity/cardinality. Update the
shared generated CLI help source and regenerate both affected CLI pages.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: c03ee287-3a29-4619-873a-5836d9b0a6b2
📒 Files selected for processing (7)
docs/index.ymldocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.mddocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.mddocs/provisioning/boot-interfaces-and-dpu-modes.mddocs/provisioning/expected-machine-interfaces.mddocs/provisioning/ingesting-hosts.mddocs/provisioning/ip-and-network-configuration.md
chet
force-pushed
the
gh-issue-4151-docs
branch
from
August 11, 2026 23:35
db05e12 to
018fc7d
Compare
chet
added a commit
that referenced
this pull request
Aug 12, 2026
Explain the numeric `network_segment_type` values accepted by the Expected Machine CLI and make patch omission behavior explicit. This keeps the live `--help` output as the source for the generated CLI reference. ## Related issues - #4847 - Documentation companion: #4151 ## Type of Change - [ ] **Add** - New feature or capability - [ ] **Change** - Changes in existing functionality - [ ] **Fix** - Bug fixes - [ ] **Remove** - Removed features or deprecated functionality - [x] **Internal** - Internal changes (refactoring, tests, docs, etc.) ## Breaking Changes - [ ] **This PR contains breaking changes** ## Testing - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [x] Manual testing performed - [ ] No testing required (docs, internal refactor, etc.) ## Additional Notes Verified the updated contract in `nico-admin-cli expected-machine add --help` and `nico-admin-cli expected-machine patch --help`. The generated CLI reference remains isolated in the docs-only #4418 PR. Signed-off-by: Chet Nichols III <chetn@nvidia.com>
chet
force-pushed
the
gh-issue-4151-docs
branch
from
August 12, 2026 19:26
018fc7d to
0bf95a2
Compare
Contributor
Author
|
@coderabbitai full_review, thanks! |
Contributor
|
🐇🔍 ✅ Action performedFull review finished. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/provisioning/expected-machine-interfaces.md (1)
163-166:⚠️ Potential issue | 🟡 MinorState the Retained prerequisite for reservation-only segments in both guides.
A
retainedinterface needs an existing reservation before it can acquire its first address on areservedsegment. Document this same rule in both locations, or explicitly mark Retained unsupported for that segment strategy.
docs/provisioning/expected-machine-interfaces.md#L163-L166: add the Retained prerequisite beside the Fixed reservation procedure.docs/provisioning/ip-and-network-configuration.md#L213-L217: add the same prerequisite to the reservation-only configuration step.As per path instructions, Markdown documentation must be technically correct and operator-usable.
🤖 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/provisioning/expected-machine-interfaces.md` around lines 163 - 166, Document in both docs/provisioning/expected-machine-interfaces.md lines 163-166 and docs/provisioning/ip-and-network-configuration.md lines 213-217 that a retained interface on a reserved segment must have an existing reservation before acquiring its first address; place this prerequisite alongside the reservation-only configuration guidance and keep both guides consistent.Source: Path instructions
🤖 Prompt for all review comments with 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.
Inline comments:
In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md`:
- Around line 201-203: Replace the literal mypassword values in the
expected-machine add examples with a clearly non-secret password placeholder,
keeping the commands realistic. Update the shared CLI help source that generates
these examples and retain an explicit warning about credential exposure; then
verify the operator-guide coverage rather than editing only the generated
Markdown page.
---
Duplicate comments:
In `@docs/provisioning/expected-machine-interfaces.md`:
- Around line 163-166: Document in both
docs/provisioning/expected-machine-interfaces.md lines 163-166 and
docs/provisioning/ip-and-network-configuration.md lines 213-217 that a retained
interface on a reserved segment must have an existing reservation before
acquiring its first address; place this prerequisite alongside the
reservation-only configuration guidance and keep both guides consistent.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: fe1e0222-e980-4840-abbb-41a4bad0d606
📒 Files selected for processing (7)
docs/index.ymldocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.mddocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.mddocs/provisioning/boot-interfaces-and-dpu-modes.mddocs/provisioning/expected-machine-interfaces.mddocs/provisioning/ingesting-hosts.mddocs/provisioning/ip-and-network-configuration.md
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 NVIDIA#4151 Signed-off-by: Chet Nichols III <chetn@nvidia.com>
chet
force-pushed
the
gh-issue-4151-docs
branch
from
August 12, 2026 19:41
0bf95a2 to
dc0290b
Compare
Contributor
Author
|
@coderabbitai full_review, thanks! |
Contributor
|
🐇🔍 ✅ Action performedFull review finished. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs/provisioning/expected-machine-interfaces.md (1)
240-260: 🗄️ Data Integrity & Integration | 🟡 MinorKeep BMC allocation semantics consistent across the documentation.
The pages list related BMC fields and modes but omit important create/update behavior. Operators cannot distinguish omitted values from explicit
unspecifiedvalues or determine when compatibility fields are preserved or cleared.
docs/provisioning/expected-machine-interfaces.md#L240-L260: document required credentials, the CLI add password default,bmc_retain_credentialscreation and patch behavior, and preservation during interface replacement.docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L149-L167: define create-timeunspecified, Auto inference, and invalid address/policy combinations.docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L144-L162: distinguish omitted allocation from explicitunspecifiedand document Dynamic/Retained compatibility-address handling.🤖 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/provisioning/expected-machine-interfaces.md` around lines 240 - 260, Update the BMC allocation documentation consistently across docs/provisioning/expected-machine-interfaces.md:240-260, docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md:149-167, and docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md:144-162. In the provisioning guide, document required credentials, the CLI add-password default, bmc_retain_credentials creation and patch behavior, and preservation during interface replacement. In the add command documentation, define create-time unspecified handling, Auto inference, and invalid address/policy combinations. In the patch command documentation, distinguish omitted allocation from explicit unspecified and specify Dynamic/Retained compatibility-address handling.Source: Path instructions
🤖 Prompt for all review comments with 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.
Inline comments:
In
`@docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md`:
- Around line 85-88: Correct the shared CLI help text that generates these
pages, then regenerate the documentation: in
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md
lines 85-88, 97-98, and 147-148, fix the ingestion wording and “dont,” change
“Default is updated as true” to “Defaults to true,” and use “this BMC's IP”;
apply the same corrections in
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md
lines 80-83, 92-93, and 142-143, and change “machines full interface list” to
“machine's full interface list” at lines 171-171. Avoid manually editing only
generated output or introducing unrelated regenerated-page churn.
In `@docs/provisioning/ip-and-network-configuration.md`:
- Around line 167-173: Update the DHCP decision-order documentation around the
Dynamic interface description to state that Dynamic allocation occurs only when
no existing Static address blocks the transition. Explain that the existing
Static address must be removed through targeted cleanup before a new lease is
assigned, while preserving the current Dynamic and Retained behavior
descriptions.
---
Duplicate comments:
In `@docs/provisioning/expected-machine-interfaces.md`:
- Around line 240-260: Update the BMC allocation documentation consistently
across docs/provisioning/expected-machine-interfaces.md:240-260,
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md:149-167,
and
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md:144-162.
In the provisioning guide, document required credentials, the CLI add-password
default, bmc_retain_credentials creation and patch behavior, and preservation
during interface replacement. In the add command documentation, define
create-time unspecified handling, Auto inference, and invalid address/policy
combinations. In the patch command documentation, distinguish omitted allocation
from explicit unspecified and specify Dynamic/Retained compatibility-address
handling.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: e5206427-ccad-4c4b-b5a8-b19e59dca6ae
📒 Files selected for processing (7)
docs/index.ymldocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.mddocs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.mddocs/provisioning/boot-interfaces-and-dpu-modes.mddocs/provisioning/expected-machine-interfaces.mddocs/provisioning/ingesting-hosts.mddocs/provisioning/ip-and-network-configuration.md
Comment on lines
85
to
+88
| **--default_pause_ingestion_and_poweron** *\<DEFAULT_PAUSE_INGESTION_AND_POWERON\>* | ||
| Optional flag to pause machines ingestion and power on. False - dont | ||
| pause, true - will pause it. The actual mutable state is stored in | ||
| explored_endpoints.\ | ||
| explored_endpoints. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the shared CLI help wording before regeneration.
The generated pages contain the same grammar defects because they come from shared help text.
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L85-L88: correct “machines ingestion” and “dont”.docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L97-L98: replace “Default is updated as true” with “Defaults to true.”docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L147-L148: replace “this BMCs IP” with “this BMC's IP”.docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L80-L83: correct “machines ingestion” and “dont”.docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L92-L93: replace “Default is updated as true” with “Defaults to true.”docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L142-L143: replace “this BMCs IP” with “this BMC's IP”.docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L171-L171: replace “machines full interface list” with “machine's full interface list”.
As per path instructions, Markdown requires spelling and grammar review. Based on learnings, correct the shared source and regenerate the documentation; avoid partial generated-page churn when the generator rewrites unrelated pages.
📍 Affects 2 files
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L85-L88(this comment)docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L97-L98docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md#L147-L148docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L80-L83docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L92-L93docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L142-L143docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md#L171-L171
🤖 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 85 - 88, Correct the shared CLI help text that generates these
pages, then regenerate the documentation: in
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md
lines 85-88, 97-98, and 147-148, fix the ingestion wording and “dont,” change
“Default is updated as true” to “Defaults to true,” and use “this BMC's IP”;
apply the same corrections in
docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-patch.md
lines 80-83, 92-93, and 142-143, and change “machines full interface list” to
“machine's full interface list” at lines 171-171. Avoid manually editing only
generated output or introducing unrelated regenerated-page churn.
Sources: Path instructions, Learnings
Contributor
Author
There was a problem hiding this comment.
@coderabbitai Good catch. The shared source is grammatical, but clap_mangen encodes apostrophes in a form that the Bookworm Pandoc conversion drops. #4898 rephrases the shared help and corrects the DPF add/patch semantics; I will regenerate these two pages here after that source-only PR lands. Thanks!
Contributor
There was a problem hiding this comment.
@chet, thank you for the clarification.
The proposed sequence is correct. Rephrase the source help in #4898, then regenerate both Expected Machine pages with the Bookworm Pandoc toolchain. This avoids manual changes to generated output and prevents the apostrophe conversion defect from recurring.
🐇
✏️ Learnings added
Learnt from: chet
Repo: NVIDIA/infra-controller PR: 4418
File: docs/manuals/nico-admin-cli/commands/expected-machine/expected-machine-add.md:85-88
Timestamp: 2026-08-12T20:20:13.095Z
Learning: In NVIDIA/infra-controller generated `nico-admin-cli` Markdown documentation, `clap_mangen` can encode apostrophes in a form that the Bookworm Pandoc conversion drops. Do not assume a missing apostrophe in generated command pages means the shared Rust CLI help text is ungrammatical. Rephrase the shared help to avoid the conversion issue, then regenerate the affected documentation pages with the Bookworm Pandoc toolchain.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: chet
Repo: NVIDIA/infra-controller PR: 4229
File: docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface.md:23-25
Timestamp: 2026-07-28T06:22:14.191Z
Learning: For generated nico-admin-cli command documentation pages (e.g., under docs/manuals/nico-admin-cli/commands/**), if you find wording/grammar issues, don’t request a targeted correction limited to a subset of the generated Markdown files. Instead, update the shared source of that text (the repository-wide CliOptions::extended help text) and make a dedicated change that regenerates the full documentation corpus so all affected pages stay consistent.
You are interacting with an AI system.
Comment on lines
+167
to
+173
| - Whether the source MAC matches a Fixed Expected Machine interface | ||
| reservation. | ||
| - Otherwise, whether the source MAC has a Dynamic or Retained Expected Machine | ||
| policy or is a known host, host BMC, DPU BMC, or DPU OS interface. | ||
| `nico-api` selects the applicable network segment. Dynamic interfaces receive | ||
| the next free address. Retained interfaces reuse their existing static | ||
| address, or receive a new address when none exists. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Qualify Dynamic allocation when a Static address already exists.
Line [172] says that every Dynamic interface receives the next free address. Line [215] states that an existing Static address can block this transition and requires targeted cleanup. Add that exception to the DHCP decision order so operators do not expect a new lease before the existing Static address is removed.
As per path instructions, Markdown documentation must be technically correct and clear.
🤖 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/provisioning/ip-and-network-configuration.md` around lines 167 - 173,
Update the DHCP decision-order documentation around the Dynamic interface
description to state that Dynamic allocation occurs only when no existing Static
address blocks the transition. Explain that the existing Static address must be
removed through targeted cleanup before a new lease is assigned, while
preserving the current Dynamic and Retained behavior descriptions.
Source: Path instructions
10 tasks
srinivasadmurthy
pushed a commit
to srinivasadmurthy/bare-metal-manager-core
that referenced
this pull request
Aug 13, 2026
Explain the numeric `network_segment_type` values accepted by the Expected Machine CLI and make patch omission behavior explicit. This keeps the live `--help` output as the source for the generated CLI reference. ## Related issues - NVIDIA#4847 - Documentation companion: NVIDIA#4151 ## Type of Change - [ ] **Add** - New feature or capability - [ ] **Change** - Changes in existing functionality - [ ] **Fix** - Bug fixes - [ ] **Remove** - Removed features or deprecated functionality - [x] **Internal** - Internal changes (refactoring, tests, docs, etc.) ## Breaking Changes - [ ] **This PR contains breaking changes** ## Testing - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [x] Manual testing performed - [ ] No testing required (docs, internal refactor, etc.) ## Additional Notes Verified the updated contract in `nico-admin-cli expected-machine add --help` and `nico-admin-cli expected-machine patch --help`. The generated CLI reference remains isolated in the docs-only NVIDIA#4418 PR. Signed-off-by: Chet Nichols III <chetn@nvidia.com>
chet
added a commit
that referenced
this pull request
Aug 13, 2026
Keep Expected Machine help grammatical in both the live CLI and generated reference pages. The roff-to-Markdown conversion drops apostrophes, so phrases such as `machine's` render incorrectly. This rephrases those options without apostrophes and documents the actual initial-only pause semantics plus the different DPF behavior for add and patch. ## Related issues - #4894 - Documentation companion: #4418 ## Type of Change - [ ] **Add** - New feature or capability - [ ] **Change** - Changes in existing functionality - [ ] **Fix** - Bug fixes - [ ] **Remove** - Removed features or deprecated functionality - [x] **Internal** - Internal changes (refactoring, tests, docs, etc.) ## Breaking Changes - [ ] **This PR contains breaking changes** ## Testing - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [x] Manual testing performed - [ ] No testing required (docs, internal refactor, etc.) ## Additional Notes Verified the live `nico-admin-cli expected-machine add --help` and `patch --help` contracts, then rendered the affected pages through the Bookworm roff/Pandoc pipeline. The generated reference updates remain isolated in the docs-only #4418 PR. Validation also included nightly formatting, full workspace Clippy, custom Carbide lints, and the focused `nico-admin-cli` tests. Signed-off-by: Chet Nichols III <chetn@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
Related issues
Type of Change
Breaking Changes
Testing
Validated with:
nico-admin-cli expected-machine add --helpandnico-admin-cli expected-machine patch --helpcargo test -p nico-admin-cli cfg::cli_options::testsrumdl checkfor the hand-authored documentationfern docs md checkfern checkAdditional Notes
This is a docs-only PR so the documentation review can proceed independently from the implementation changes.
PR #4848 is the merged source companion for the Expected Interface JSON help shown in the generated command reference.
PR #4898 is the source companion for the final grammar and option-lifecycle wording. The two affected pages will be regenerated after it merges.
The CLI documentation corpus has repository-wide generated output drift across Pandoc versions. This refresh uses the Pandoc version from the Bookworm build environment and commits only the affected Expected Machine pages. Those generated pages include Pandoc hard-break whitespace, so
git diff --checkreports the source-generated lines; the hand-authored documentation passes the whitespace check.