docs: explain templated iPXE Operating Systems - #4457
Draft
pbreton wants to merge 4 commits into
Draft
Conversation
Document the template, ownership, synchronization, and site rules so operators can create and safely use templated boot definitions through REST or Core. Signed-off-by: Patrice Breton <pbreton@nvidia.com>
Contributor
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Summary by CodeRabbit
WalkthroughThe PR adds a comprehensive guide for templated iPXE Operating Systems. It documents resource relationships, creation, validation, synchronization, Instance usage, lifecycle operations, troubleshooting, navigation, and related CLI references. ChangesTemplated iPXE Operating Systems
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Use the list endpoint for site-association status and document the Core command that records cached artifact URLs. Signed-off-by: Patrice Breton <pbreton@nvidia.com>
|
🌿 Preview your docs: https://nvidia-preview-pull-request-4457.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: 1
🤖 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/configuration/templated-ipxe-operating-systems.md`:
- Line 351: Update the “Definition remains non-ready with CachedOnly”
troubleshooting text to replace “every required cached URL” with clearer wording
such as “every URL required to be cached” or “a cached URL for every required
artifact,” while preserving the existing guidance.
🪄 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: 7365f958-bd32-4d6c-a026-dbd26684e992
📒 Files selected for processing (6)
docs/configuration/templated-ipxe-operating-systems.mddocs/configuration/tenant_management.mddocs/index.ymldocs/manuals/nico-admin-cli/commands/ipxe-template/ipxe-template-show.mddocs/manuals/nico-admin-cli/commands/operating-system/operating-system-create.mddocs/manuals/nico-admin-cli/commands/operating-system/operating-system-update.md
| | Missing or reserved parameter error | Compare the request with `requiredParams` and `reservedParams` from `ipxe-template get`. | | ||
| | Missing artifact error | Supply every name in `requiredArtifacts`; names are case-sensitive. | | ||
| | Operating System is not synchronized to the Instance's Site | Wait for the Site association to become `Synced`, or create the definition for the Instance's Site. | | ||
| | Definition remains non-ready with `CachedOnly` | Ensure the Site's cache service populated every required cached URL, or use another cache strategy. | |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use clearer wording for cached URLs.
Replace “every required cached URL” with “every URL required to be cached” or “a cached URL for every required artifact.”
🧰 Tools
🪛 LanguageTool
[style] ~351-~351: The double modal “required cached” is nonstandard (only accepted in certain dialects). Consider “to be cached”.
Context: ... cache service populated every required cached URL, or use another cache strategy. | |...
(NEEDS_FIXED)
🤖 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/configuration/templated-ipxe-operating-systems.md` at line 351, Update
the “Definition remains non-ready with CachedOnly” troubleshooting text to
replace “every required cached URL” with clearer wording such as “every URL
required to be cached” or “a cached URL for every required artifact,” while
preserving the existing guidance.
Source: Linters/SAST tools
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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/operating-system/operating-system-set-cached-url.md`:
- Line 61: Update both generator targets that currently emit README.md links to
emit index.md instead, preserving the existing relative-link structure. Then
regenerate the CLI documentation so command and domain pages contain the
corrected links and no stale README.md references remain.
🪄 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: 9d489791-5b8d-457d-8149-f77cfacf1302
📒 Files selected for processing (2)
docs/configuration/templated-ipxe-operating-systems.mddocs/manuals/nico-admin-cli/commands/operating-system/operating-system-set-cached-url.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/configuration/templated-ipxe-operating-systems.md
| --- | ||
|
|
||
| **See also:** [Tenant commands](../../tenant.md) · [CLI reference index](../../README.md) | ||
| **See also:** [Tenant commands](../../tenant.md) · [CLI reference index](../../index.md) |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
current="docs/manuals/nico-admin-cli/commands/operating-system/operating-system-set-cached-url.md"
sibling="docs/manuals/nico-admin-cli/commands/operating-system/operating-system.md"
directory="$(dirname "$current")"
printf '%s\n' 'Link targets:'
for target in ../../index.md ../../README.md; do
if test -f "$directory/$target"; then
printf 'exists: %s\n' "$directory/$target"
else
printf 'missing: %s\n' "$directory/$target"
fi
done
printf '%s\n' 'Relevant links:'
rg -n -C 2 'CLI reference index|README\.md|index\.md' "$current" "$sibling"
printf '%s\n' 'Nearby documentation sources and generation references:'
rg -n -C 2 'operating-system-set-cached-url|CLI reference index|nico-admin-cli|regenerat|generated' docs README.md 2>/dev/null | head -250Repository: NVIDIA/infra-controller
Length of output: 20839
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf '%s\n' 'nico-admin-cli documentation tree:'
git ls-files 'docs/manuals/nico-admin-cli*' | sed -n '1,240p'
printf '%s\n' 'Top-level reference files:'
for file in docs/manuals/nico-admin-cli.md docs/manuals/nico-admin-cli/index.md docs/manuals/nico-admin-cli/README.md; do
if test -f "$file"; then
printf '\n--- %s ---\n' "$file"
cat -n "$file" | sed -n '1,100p'
fi
done
printf '%s\n' 'Generation/source references:'
rg -n -C 3 'nico-admin-cli|admin-cli.*doc|doc.*admin-cli|README\.md|index\.md' \
.github Makefile* justfile Taskfile.yml scripts tools crates docs 2>/dev/null | head -300Repository: NVIDIA/infra-controller
Length of output: 47709
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf '%s\n' 'Top-level files under docs/manuals/nico-admin-cli:'
find docs/manuals/nico-admin-cli -maxdepth 1 -type f -printf '%f\n' | sort
printf '%s\n' 'Generator implementation and link text:'
rg -n -C 4 'generate-cli-docs|CLI reference index|See also|README\.md|index\.md' \
crates/admin-cli Makefile.toml docs/manuals/nico-admin-cli 2>/dev/null | head -350
printf '%s\n' 'All CLI reference-index links using README.md or index.md:'
rg -l 'CLI reference index' docs/manuals/nico-admin-cli | sort | while IFS= read -r file; do
link="$(rg -o '\]\(\.\./\.\./(README|index)\.md\)' "$file" | head -1 || true)"
printf '%s: %s\n' "$file" "${link:-no matching relative link}"
done | sed -n '1,260p'Repository: NVIDIA/infra-controller
Length of output: 50381
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
import re
root = Path("docs/manuals/nico-admin-cli")
pattern = re.compile(r"\]\(([^)#]+)(?:#[^)]*)?\)")
counts = {}
broken = []
for page in root.rglob("*.md"):
for target in pattern.findall(page.read_text(encoding="utf-8")):
if "://" in target or target.startswith("mailto:"):
continue
resolved = (page.parent / target).resolve()
try:
relative = resolved.relative_to(Path.cwd().resolve())
except ValueError:
continue
exists = resolved.is_file()
key = (target, exists)
counts[key] = counts.get(key, 0) + 1
if not exists:
broken.append((page.as_posix(), target, relative.as_posix()))
print("relative-link summary:")
for (target, exists), count in sorted(counts.items(), key=lambda item: (item[0][0], item[0][1])):
if target in {"../../README.md", "../../index.md", "./README.md"}:
print(f"{count:4} {'ok' if exists else 'BROKEN':7} {target}")
print("broken CLI reference links:")
for page, target, resolved in broken:
if target in {"../../README.md", "../../index.md", "./README.md"}:
print(f"{page}: {target} -> {resolved}")
PY
printf '%s\n' 'Generator source:'
sed -n '175,208p' crates/admin-cli/src/generate_docs/cmd.rsRepository: NVIDIA/infra-controller
Length of output: 50379
Update the generator and regenerate the CLI pages.
docs/manuals/nico-admin-cli/README.md does not exist. The generator still emits README.md links, causing 577 broken command-page links and four broken domain-page links. Change both generator targets to index.md, then regenerate the documentation.
🤖 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/operating-system/operating-system-set-cached-url.md`
at line 61, Update both generator targets that currently emit README.md links to
emit index.md instead, preserving the existing relative-link structure. Then
regenerate the CLI documentation so command and domain pages contain the
corrected links and no stale README.md references remain.
Sources: Path instructions, Learnings
pbreton
marked this pull request as draft
July 31, 2026 20:36
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
Document provider-owned Operating Systems as selectable by tenants at authorized, synchronized Sites while retaining provider-only mutation rights. Signed-off-by: Patrice Breton <pbreton@nvidia.com>
Document direct curl usage alongside the CLI examples and remove the obsolete Operating System scope discussion. Signed-off-by: Patrice Breton <pbreton@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.
Summary
nicocliandnico-admin-cliworkflows plus validation and troubleshooting guidance--orgownership semanticsThe content is traced against the merged implementation and the corrected design requirements. In particular, it documents that OS
scopeno longer exists, REST-created Templated iPXE definitions target exactly one immutable Site, and single-Site definitions synchronize bidirectionally.Related implementation
Type of Change
Breaking Changes
Testing
docs/index.ymlparses as YAMLgit diff --check