Repository navigation
docs(architecture): add the contributor architecture reference - #657
Draft
galletas1712 wants to merge 6 commits into
Draft
galletas1712 wants to merge 6 commits into
galletas1712 wants to merge 6 commits into
Conversation
Replaces the docs/reference/architecture.md placeholder with a docs/reference/architecture/ section: an overview index plus pages on the control plane, the node agent, the checkpoint flow, the restore flow, and storage and artifacts. The multi-GPU page from #337 lives in the same directory. Refs #653, #627. Signed-off-by: Schwinn Saereesitthipitak <schwinns@nvidia.com>
… points Signed-off-by: Schwinn Saereesitthipitak <schwinns@nvidia.com>
Contributor
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: true
Comment |
Adds a terms table to the index, sequence diagrams to the checkpoint and restore pages, defines the PageBroker transaction where it is first used, corrects when the capture-eligible label is applied, and removes numbers and internals a contributor does not act on. Signed-off-by: Schwinn Saereesitthipitak <schwinns@nvidia.com>
Restructures every page so it opens with the high-level picture and elaborates progressively, moves option, reason, and event tables to the end of their page, replaces informal labels with the names of the actual objects, and defines each Snapshot-specific term where it first appears. The index gains a vocabulary section and a reading guide. Signed-off-by: Schwinn Saereesitthipitak <schwinns@nvidia.com>
Every step-by-step procedure is now a numbered list or a sequence diagram, and paragraphs are kept for explanation only. Adds diagrams for the SnapshotJob lifecycle, the PageBroker transaction, the CRIU dump, and the workload handshake. Signed-off-by: Schwinn Saereesitthipitak <schwinns@nvidia.com>
…ct on Removes the operator flag table, the exact proxy signal list, two CRIU options with no design significance, the nosuid and nodev mount flags, the nsenter file descriptor mechanics, the /proc/sys remount step, the network_lock option, the transient PageBroker directory names, and the transaction expiry time. Signed-off-by: Schwinn Saereesitthipitak <schwinns@nvidia.com>
galletas1712
force-pushed
the
schwinns/single-gpu-architecture-docs
branch
from
October 26, 2026 18:54
f8ae101 to
923e045
Compare
This branch has not been deployed
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
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.
Refs #653, #627.
Replaces the
docs/reference/architecture.mdplaceholder with adocs/reference/architecture/section for contributors and integrators. It is the single-GPU counterpart of #337: the internals every checkpoint and restore go through, with the points where the multi-GPU path hooks in marked and linked tomulti-gpu.md.Each page opens with the high-level picture and elaborates from there. Reference tables (options, reasons, events) sit at the end of their page. Every Snapshot-specific term is defined where it first appears, and the index collects them.
README.mdis the overview a new contributor reads first: what Snapshot does, the pieces, the resources, how the workload takes part, both flows in brief, where multi-GPU differs, failure behavior, privilege, a reading guide, and the vocabulary.control-plane.mdcovers the operator: accepting aPodSnapshotand binding it to aPodSnapshotContent, mirroring, deletion,SnapshotJob, deleting checkpoints, CRD installation, the code and the sharedapi/module,snapshotctl, and the failure reasons the operator originates.node-agent.mdcovers the agent pod: the containers, how the agent receives and performs work, what is in the image and in the bundle it mounts into restore containers, PageBroker and its protocol, the runtime adapters and NRI plugin, the restore proxy, what the agent needs from the node and does to it, configuration, and a code map.checkpoint.mdfollows one capture: waiting for the right moment, inspect, the mount policy, the PageBroker transaction, suspending the GPU, the CRIU dump, archiving changed files, publishing, failure behavior, and the reasons.restore.mdfollows one restore: container creation through NRI, the dependency and compatibility checks, mounting the tools and the checkpoint, every stepnsrestoreruns inside the container, how CRIU is run and what is rewritten, the two GPU restore paths, completion, reporting, and the mapping to the four benchmark stages.storage.mdcovers the artifact: where it lives, its files, the manifest, publishing and reading through PageBroker, the compatibility rules, deletion, and where the store identity and the S3 proposal fit.The root
README.mdlinks change the same way as in #337, so the two merge cleanly. The index links tomulti-gpu.md, which lands with #337.Draft until the structure is agreed. Every claim was checked against the code at
7e282f0e; file paths are linked where a reader needs them, line numbers are not.