feat: publish checkpoint source facts

[leeZardNav]

Summary

• PodSnapshotContent gains an optional status.source publishing what a checkpoint was captured on: the node, the container, and the devices.
• The block is projected from the artifact's manifest.yaml and written in the same status patch that marks the capture Ready, so a content that is Ready already carries its facts.
• Device facts are grouped under one property per vendor, so each payload stays typed and validated and a second vendor can join without a discriminator or a CEL rule.
• Nothing reads the block back. The restore compatibility gates compare the manifest, so this cannot become a second source of truth.

Design: #99, section 7.1. Stacked on #140, which records the facts this publishes.

What it looks like

status:
  conditions:
    - type: Ready
      status: "True"
      reason: Captured
  source:
    devices:
      nvidia:
        driverVersion: 580.82.07
        instances:
          - productName: NVIDIA A100-SXM4-80GB
          - productName: NVIDIA A100-SXM4-80GB
    node:
      name: gpu-node-3
      architecture: amd64
      kernelVersion: 5.15.0-1071-aws
    pod:
      image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:0.6.1
      imageDigest: sha256:9f2c...
      memory: 64Gi

instances[].productName and driverVersion are the names the NVIDIA DRA driver publishes on a ResourceSlice, so the same GPU reads the same way in both places. The GPU count is the length of the instance list rather than a field of its own, so the two cannot disagree.

How to read this

The 7 commits form a ladder; each introduces one idea with its own tests.

Commits	What it does
1-3	The published shape, one block per commit: node, then pod, then vendor-keyed devices. Each regenerates both CRD copies and the deepcopy
4	The projection from manifest to status as a pure function, reusing compat.ImageDigest. Nothing calls it yet
5	Wires it into the Ready write, at all three call sites
6	A test per Ready path — fresh dump, artifact recovery, and a work order reconciled after the source pod is gone — plus the conflict retry and the do-not-erase guard
7	E2E assertion against the node object and nvidia-smi rather than against the manifest

Decisions worth a look

Absent, not empty. A fact the agent could not read is left out, and a block with nothing in it is omitted entirely. An artifact captured before a fact was ever recorded still publishes; a reader can tell unknown from a value that happens to be blank.

The published digest is the compared digest. compat.ImageDigest is exported rather than reimplemented, so the reduction that decides whether two images are the same content is the one this publishes. Runtimes wrap a digest differently and the artifact keeps whichever form it was handed, so a second implementation could show a value the gate never compares.

One read, not one per retry. The Ready write retries on optimistic-lock conflict, so the manifest is read once before the loop.

Losing the facts never costs the capture. By the time this runs the artifact is committed, so an unreadable manifest logs and Ready is written anyway.

No node.agentVersion yet. The design lists it, but #140 dropped agent-version recording along with the major/minor comparison, so the field would only ever be empty. It arrives with the deferred agent-version compatibility mapping, which is also what will give it a meaning.

No new RBAC. The agent already holds podsnapshotcontents/status update and patch. PodSnapshot keeps mirroring only Ready and Failed.

Single container. Capture is still one container per content (PodReference.Containers is MinItems=1/MaxItems=1), so one source block per content is correct. Multi-container restore does not change that; if multi-container capture arrives, this block is where it grows a key.

Verification

• Every one of the 7 commits builds, vets and tests on its own (go vet ./... and go test ./... for the agent under Linux, go test ./... for the api module, at each rung).
• Full suites green for api, agent and operator; make verify-crds clean, so the chart CRD copy matches the generated one; license headers, fmt, tidy and helm lint clean; govulncheck clean.
• Manual cluster validation pending.

Summary by CodeRabbit

• New Features

  • Pod snapshot content now reports checkpoint provenance, including source node, pod, container image, and captured device details.
  • NVIDIA GPU information includes driver version, product names, and device counts.
  • Vendor-specific device fields are preserved for broader hardware compatibility.
  • Source information is recorded across fresh captures and artifact recovery workflows.

• Bug Fixes

  • Snapshot readiness now completes even when provenance data cannot be read, while retaining previously available metadata.
  • Image digest handling is consistently normalized for compatibility checks.

Superseded by #141 after removing the internal task reference from the head branch.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: a014c968-7567-41c3-b728-6006893a179b

📥 Commits

Reviewing files that changed from the base of the PR and between 50f501c and 007f46d.

⛔ Files ignored due to path filters (2)

• api/v1alpha1/zz_generated.deepcopy.go is excluded by !**/zz_generated*.go
• charts/snapshot/crds/nvidia.com_podsnapshotcontents.yaml is excluded by !charts/snapshot/crds/**

📒 Files selected for processing (11)

• agent/internal/controller/checkpointsource.go
• agent/internal/controller/checkpointsource_test.go
• agent/internal/controller/podsnapshotcontent.go
• agent/internal/controller/podsnapshotcontent_coverage_test.go
• api/compat/checks.go
• api/v1alpha1/checkpoint_source_types.go
• api/v1alpha1/crds/embed_test.go
• api/v1alpha1/crds/nvidia.com_podsnapshotcontents.yaml
• api/v1alpha1/podsnapshot_types_test.go
• api/v1alpha1/podsnapshotcontent_types.go
• e2e/tests/test_snapshot_lifecycle.py

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

Walkthrough

The change adds checkpoint provenance types and CRD fields. The controller reads manifests beside artifacts, projects captured node, pod, and NVIDIA facts, and publishes them when PodSnapshotContent reaches Ready. Tests cover capture, recovery, conflicts, deep copies, schema preservation, and lifecycle validation.

Changes

Checkpoint source publication

Layer / File(s)	Summary
Checkpoint source API contract api/v1alpha1/checkpoint_source_types.go, api/v1alpha1/podsnapshotcontent_types.go, api/v1alpha1/crds/*, api/compat/checks.go, api/v1alpha1/podsnapshot_types_test.go	Adds checkpoint source types for node, pod, and NVIDIA device facts. Adds status.source to the CRD and preserves unknown device fields. Exports ImageDigest and validates deep-copy behavior.
Manifest projection and Ready publication agent/internal/controller/checkpointsource.go, agent/internal/controller/podsnapshotcontent.go, agent/internal/controller/checkpointsource_test.go, agent/internal/controller/podsnapshotcontent_coverage_test.go	Reads manifests beside artifacts and projects available compatibility facts. Capture and recovery paths pass artifact paths to Ready finalization. Manifest errors are logged while Ready status is still written. Tests cover retries, missing manifests, and source preservation.
Lifecycle and schema validation e2e/tests/test_snapshot_lifecycle.py, api/v1alpha1/crds/embed_test.go	Validates published node, pod, image, resource, driver, and GPU facts against capture-time data. Verifies preservation of unknown device vendor fields.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 007f4

This change publishes checkpoint source facts alongside Ready status without introducing an actionable merge-blocking risk; it is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Capture
  participant Controller
  participant Manifest
  participant PodSnapshotContent
  Capture->>Controller: artifact path
  Controller->>Manifest: read checkpoint manifest
  Manifest-->>Controller: compatibility facts
  Controller->>PodSnapshotContent: publish Ready status and source facts

Loading

🚥 Pre-merge checks | ✅ 6 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.88% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 32 functions across 10 files. (1 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (6 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Breaking Api Changes	✅ Passed	No breaking API change matches the check. The only existing Kubernetes API struct changed is PodSnapshotContentStatus, which adds Source *CheckpointSource with json:"source,omitempty" and `// +o…
Rbac Least Privilege	✅ Passed	No RBAC least-privilege violation was introduced. The complete PR diff from merge-base c1206a4 to HEAD changes no kubebuilder RBAC marker or Helm Role/ClusterRole grant. All current markers and Helm R…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title uses the required feat: Conventional Commit prefix, is 37 characters long, and clearly describes publishing checkpoint source facts.

Full details: Docstring Coverage

Explanation

Docstring coverage is 46.88% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 32 functions across 10 files. (1 skipped: 1 unsupported.)

Full details: Breaking Api Changes

Explanation

No breaking API change matches the check. The only existing Kubernetes API struct changed is PodSnapshotContentStatus, which adds Source *CheckpointSource with json:"source,omitempty" and // +optional. All fields in the new checkpoint-source types also have // +optional and omitempty tags. The diff does not remove, rename, retag, or change the Go type of an existing exported field. PodSnapshotSpec and PodSnapshotContentSpec immutability markers are unchanged. ImageDigest is a function rename, not an exported field change.

Full details: Rbac Least Privilege

Explanation

No RBAC least-privilege violation was introduced. The complete PR diff from merge-base c1206a4 to HEAD changes no kubebuilder RBAC marker or Helm Role/ClusterRole grant. All current markers and Helm RBAC rules use explicit verbs and resources; an exact wildcard search found no * in either field. The changed Helm role test only asserts an existing pods/status patch rule.

• Fix all pre-merge checks with AI

---

_{Comment @coderabbitai help to get the list of available commands.}

[leeZardNav]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.