docs(networking): add AINIC bundle version guide - #1094
Open
yeandy wants to merge 2 commits into
Open
Conversation
Published training images ship a fixed AINIC bundle, and the multi-node networking guide says to match the image to the site's ANP bundle without explaining how. Document rebuilding a published image against an arbitrary bundle, and verifying the change took effect. Scope is deliberately limited to making the change. Deciding which bundle a cluster needs depends on the host ionic driver and is left to the reader, with a pointer to the uverbs ABI check and a note that compatibility is not monotonic in the bundle version, so downgrades are supported as a first-class operation rather than a workaround. Covers the two silent build-time failure modes: stale AINIC repositories make AINIC_BUNDLE_VERSION advisory rather than binding, and an unpinned apt install is a no-op when the target bundle is older than the installed hostlib. Both report success, so the Dockerfile includes a verification step that fails the build instead. Verification notes that package-level checks cannot prove host compatibility: an incompatible hostlib passes them all and RCCL then falls back to TCP, measured at 3.2x lower throughput while completing every step with an identical loss. Also records that the bundle named in an image's build arguments is not necessarily the one installed, that no uninstall is required, and that automated checks must treat an empty ionic enumeration as a failure and must not parse versions out of the soname.
yeandy
marked this pull request as ready for review
September 3, 2026 18:04
yeandy
requested review from
Xiaoming-AMD,
limou102 and
wenxie-amd
as code owners
September 3, 2026 18:04
Lead with a copy-paste quickstart so a reader who already knows their target bundle does not have to read four sections of background first. Replace the invented term 'hostlib', which appeared nowhere else in the repository and inverted the container/host distinction the guide turns on, with libionic throughout. Section 3 handed the reader a uverbs abi_version to read with nothing to compare it against; state plainly that there is no container-side counterpart and that the runtime check is authoritative. Fold the no-uninstall note into the rebuild section, drop the duplicated scope and downgrade statements, and mark the bundle table as an excerpt.
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.
What
Adds
docs/04-technical-guides/ainic-bundle-versions.md, a guide to rebuilding a published training image against a different AINIC bundle. Plus index entries (docs/README.md,04-technical-guides/README.md,sphinx/_toc.yml.in) and a cross-link from the multi-node networking guide.Docs only — no code changes.
Why
multi-node-networking.md§4 tells users to "match the image to your ROCm and ANP bundle" but never explains how. This fills that gap.Scope
Covers making the change and verifying it took effect. Choosing which bundle is explicitly out of scope — it depends on the host
ionicdriver and belongs to the cluster's operators. The guide points at the uverbs ABI check and notes that compatibility is not monotonic in the bundle version, so downgrades are supported as a first-class operation.Notable content
AINIC_BUNDLE_VERSIONadvisory rather than binding, and an unpinnedapt installis a no-op when the target is older than what's installed. Both report success, so the Dockerfile ends with a check that fails the build instead.dpkg-query.Verification
Every command was run on an MI300X node. Builds tested against
maxtext-v26.3.2andmaxtext-v26.6bases in both directions. The "no uninstall required" claim was tested by fingerprinting (MD5 of every owned file, all symlink targets, package status) an in-place upgrade against a purge-then-install: byte-identical, both directions, no orphaned files,dpkg -Cclean.