Skip to content

feat(gateway): check VM host tools during config preflight - #4037

Merged
johntmyers merged 3 commits into
mainfrom
fix/3951-vm-config-preflight
Oct 3, 2026
Merged

feat(gateway): check VM host tools during config preflight#4037
johntmyers merged 3 commits into
mainfrom
fix/3951-vm-config-preflight

Conversation

@shiju-nv

@shiju-nv shiju-nv commented Oct 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

openshell-gateway config preflight checks host filesystem tools for an explicitly selected local VM driver, so an unusable e2fsprogs installation fails before provisioning. The command reports selected paths and versions or a corrective error without creating runtime state.

Related Issue

Fixes #3951. Part of #3955.

Changes

  • Run bounded host-tool probes after the existing pure configuration validator. Remote driver endpoints report that host checks were not performed; other drivers do not require VM tools.
  • Share tool resolution between the gateway and VM image operations through openshell-core, preserving the independent VM driver binary. Resolve mke2fs or mkfs.ext4, debugfs, and e2fsck from the gateway's environment and existing package prefixes, and retain a selected tool's execution failure.
  • Document operator installation and checking the gateway service's account and environment, including restricted PATH values. Package installation remains with the operator; this change adds no package dependency or service environment changes.

Testing

Branch Checks passed for signed head 8bd564bf637e: all 23 jobs succeeded. Rust lint, tests, and build modes passed on macOS aarch64, Linux aarch64, and Linux x86_64. The gateway feature checks and SDK jobs also passed.

  • mise run pre-commit passes.
  • Unit tests added/updated.
  • E2E tests added/updated (if applicable).

Runtime verification passed for signed head 8bd564bf637e: Branch E2E Checks, attempt 2. Docker, Podman, Kubernetes, managed VM, external VM and integration suites executed successfully. GPU and the separately labelled Kubernetes HA and credential-driver suites were skipped. These runs establish Linux VM coverage; fresh physical-Mac qualification remains pending.

Checklist

  • Follows Conventional Commits. The implementation commit uses feat(gateway): validate VM filesystem tools during preflight.
  • Commits are signed off (DCO). The implementation and both corrections have sign-off trailers and verified SSH signatures.
  • Architecture docs updated (if applicable). The configuration reference and VM troubleshooting guidance describe the operator workflow.

@shiju-nv
feat(gateway): validate VM filesystem tools during preflight
a6cfa1b 
Check required local VM tools through config preflight and share executable
resolution with VM image operations. Report selected paths and actionable
errors without creating gateway or sandbox state.

Bound probe output and execution time, and clean up probe descendants on
interruption. Preserve pure static validation and skip local tool checks
for remote driver endpoints and unrelated drivers.

Fixes #3951
Related to #3955

Signed-off-by: Shiju <shiju@nvidia.com>
@shiju-nv
fix(gateway): stabilize filesystem preflight checks
ee75f43 
Combine identical filesystem-tool error arms and normalize rendered
diagnostics in command tests so terminal wrapping preserves assertions.
Describe driver TLS validation without depending on removed guest fields.

Signed-off-by: Shiju <shiju@nvidia.com>
@shiju-nv
test(gateway): serialize preflight fixture paths as TOML
8bd564b 
Keep temporary paths quoted and escaped through the TOML serializer
instead of relying on Rust Debug formatting.

Signed-off-by: Shiju <shiju@nvidia.com>
@copy-pr-bot

copy-pr-bot Bot commented Oct 1, 2026

Copy link
Copy Markdown

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.

@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown

🌿 Preview your docs: https://nvidia-preview-pr-4037.docs.buildwithfern.com/openshell

@shiju-nv
shiju-nv marked this pull request as ready for review October 1, 2026 19:20
@drew drew added gator:in-review Gator is reviewing or awaiting PR review feedback test:e2e Requires end-to-end coverage labels Oct 3, 2026
@github-actions

github-actions Bot commented Oct 3, 2026

Copy link
Copy Markdown

Label test:e2e applied for 8bd564b. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

drew
drew reviewed Oct 3, 2026
View reviewed changes

@drew drew left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

gator-agent

PR Review Status

The linked operator workflow in #3951 makes this PR project-valid, and the initial code review found no blocking defects or non-blocking suggestions. The VM behavior change requires test:e2e, but the label-help workflow says the existing current-head E2E run must be manually rerun before Gator can begin pipeline monitoring.

Action required: A maintainer must open workflow run 36913527891 and choose Re-run all jobs; Gator will confirm that the required E2E workflow is queued before advancing.

Blocking findings:

  • No blocking findings remain

Carried findings:

  • None

Non-blocking suggestions:

  • None
Gator metadata
  • Validation: Implements the focused, documented VM preflight workflow in linked issue #3951; the author has repository write authority.
  • Docs: Fern gateway configuration docs, the gateway man page, and VM troubleshooting guidance are updated.
  • Checks: Branch Checks, Helm Lint, and Trivy are green on the current head; required E2E dispatch is not yet confirmed.
  • E2E: test:e2e applied; label-help requires Re-run all jobs for run 36913527891.
  • Head SHA: 8bd564bf637e1bc9250289258cd10be40354cb69
  • Base SHA: 021400be8af471f8669369e679de3e18cf0bd672
  • Merge base SHA: 912a077bd641272016fb8b2fd58209f6c7c6f194
  • Patch ID: 8d00987f215f4d7c2f317cdcf8740eee90e49bbe
  • Gator payload: 10
  • Review mode: initial
  • Previous reviewed SHA: none
  • Review budget exhausted: no
  • Maintainer decision required: no
  • Next state: gator:blocked
  • Blocked reason: test_dispatch_required

@drew drew added gator:blocked Gator is blocked by process or repository gates gator:watch-pipeline Gator is monitoring PR CI/CD status gator:approval-needed Gator completed review; maintainer approval needed and removed gator:in-review Gator is reviewing or awaiting PR review feedback gator:blocked Gator is blocked by process or repository gates gator:watch-pipeline Gator is monitoring PR CI/CD status labels Oct 3, 2026
@johntmyers
johntmyers enabled auto-merge October 3, 2026 20:19
@johntmyers
johntmyers added this pull request to the merge queue Oct 3, 2026
Merged via the queue into main with commit 1c123a4 Oct 3, 2026
170 of 174 checks passed
@johntmyers
johntmyers deleted the fix/3951-vm-config-preflight branch October 3, 2026 20:32
@drew

drew commented Oct 3, 2026

Copy link
Copy Markdown
Collaborator

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Final status: Maintainer approval was present, the required Branch Checks, Helm Lint, Trivy, E2E, and DCO gates were green, and no Gator review findings remained.

I removed the active gator:* label because there is nothing left for gator to monitor on this PR.

Gator metadata
  • Head SHA: 8bd564bf637e1bc9250289258cd10be40354cb69
  • Gator payload: 10
  • Final state: merged

@drew drew removed the gator:approval-needed Gator completed review; maintainer approval needed label Oct 3, 2026
@rhods-devops-app rhods-devops-app Bot mentioned this pull request Oct 4, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@drew drew drew left review comments
@johntmyers johntmyers johntmyers approved these changes
@mrunalp mrunalp Awaiting requested review from mrunalp mrunalp is a code owner
@sjenning sjenning Awaiting requested review from sjenning sjenning is a code owner
@derekwaynecarr derekwaynecarr Awaiting requested review from derekwaynecarr derekwaynecarr is a code owner

Assignees

No one assigned

Labels

test:e2e Requires end-to-end coverage

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Detect missing microVM host tools before sandbox creation

3 participants

@shiju-nv @drew @johntmyers