Skip to content

feat(sandbox): support rootfs tar as --from source for VM driver - #2863

Open
feloy wants to merge 1 commit into
NVIDIA:mainfrom
feloy:docker-tar
Open

feat(sandbox): support rootfs tar as --from source for VM driver#2863
feloy wants to merge 1 commit into
NVIDIA:mainfrom
feloy:docker-tar

Conversation

@feloy

@feloy feloy commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add rootfs tar archive (.tar, .tar.gz, .tgz) as a new --from source for VM-driver sandboxes, enabling daemon-free sandbox creation from flat filesystem archives produced by docker export, podman export, or buildah mount + tar
  • CLI detects the archive by file extension, validates the gateway is local and uses the VM compute driver, and passes the path via driver_config
  • VM driver copies the tar into its staging area and feeds it into the existing rootfs extraction and ext4 disk creation pipeline, with mtime-based caching

Related Issue

Closes #2175

Changes

CLI (crates/openshell-cli/)

  • New ResolvedSource::RootfsTar variant in resolve_from() with extension-based detection
  • validate_rootfs_tar_source() checks local-gateway and VM-driver constraints via GetGatewayInfo RPC
  • rootfs_tar_driver_config() and merge_driver_config() encode the tar path into driver_config
  • Updated --from help text and error messages

VM driver (crates/openshell-driver-vm/)

  • rootfs_tar_path field on VmSandboxDriverConfig
  • ensure_prepared_rootfs_tar_disk() with double-checked cache locking and mtime-based identity
  • Updated validate_sandbox(), create_sandbox(), prepare_runtime_images(), and reconciliation to accept rootfs tar as an alternative to image references
  • Extracted bootstrap_image_ref_default() for reuse in rootfs tar and reconciliation paths

Docs (docs/sandboxes/manage-sandboxes.mdx)

  • Updated --from documentation with rootfs tar example and VM-driver constraint

Tests

  • 6 unit tests in run.rs: extension detection for .tar/.tar.gz/.tgz, missing archive rejection, filename_looks_like_rootfs_tar coverage
  • E2E test (e2e/rust/tests/rootfs_tar.rs): builds a Docker image, exports a flat rootfs tar, creates a VM sandbox from it, and verifies a marker file

Testing

  • mise run pre-commit passes
  • Unit tests added/updated
  • E2E tests added/updated

Checklist

  • Follows conventional commit format
  • No proto schema changes required (driver_config carries the tar path)
  • Scoped to VM driver only — Docker and Podman drivers unaffected
  • Local-gateway constraint enforced (same as Dockerfile sources)
  • User-facing docs updated
  • DCO sign-off included

Accept flat rootfs tar archives (.tar, .tar.gz, .tgz) via the --from
flag for VM-backed gateways. The CLI detects the archive extension,
validates that the gateway uses the VM compute driver, and passes the
tar path through driver_config. The VM driver copies the tar into its
staging area and feeds it into the existing rootfs extraction and ext4
disk creation pipeline, skipping the container image pull/export steps.

Closes NVIDIA#2175

Signed-off-by: Philippe Martin <phmartin@redhat.com>
@feloy
feloy requested review from a team, derekwaynecarr, mrunalp and sjenning as code owners August 21, 2026 07:14
@copy-pr-bot

copy-pr-bot Bot commented Aug 21, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: support rootfs tar as --from source for VM driver sandboxes

1 participant