From 84b20c4b3df9793190e7915e8371177c21677510 Mon Sep 17 00:00:00 2001 From: Samuel K Date: Mon, 9 Nov 2026 10:30:28 -0600 Subject: [PATCH] fix(microsandbox): keep runtime minimums distinct --- AGENTS.md | 11 +++-- e2e/tests/up/microsandbox_session.go | 16 ++++--- .../up/provider_microsandbox_compatibility.go | 2 +- hack/microsandbox/install.go | 4 +- hack/microsandbox/pins_test.go | 45 +++++++++++++++++++ pkg/driver/microsandbox/microsandbox.go | 14 +++--- pkg/driver/microsandbox/microsandbox_test.go | 3 +- pkg/driver/microsandbox/recreate.go | 10 ++--- .../docs/managing-providers/microsandbox.mdx | 14 +++++- 9 files changed, 92 insertions(+), 27 deletions(-) create mode 100644 hack/microsandbox/pins_test.go diff --git a/AGENTS.md b/AGENTS.md index 96d31df5f3..dfa3a0bc53 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -86,10 +86,15 @@ Devsy uses [Ginkgo](https://onsi.github.io/ginkgo/) for Go E2E and integration t `e2e/tests/up/microsandbox_session.go` pins the external provider release. Renovate tracks that source. When updating it, check the provider's runtime requirement and qualified executable and firmware pair. Update `hack/microsandbox/install.go`, -its tests, and the release bundle cache in `.github/workflows/pr-ci.yml` together. +its tests, the external runtime minimum in `e2e/tests/up/microsandbox_session.go`, +the release bundle cache in `.github/workflows/pr-ci.yml`, and the external +provider minimum in `sites/docs-devsy-sh/content/docs/managing-providers/microsandbox.mdx` +together. `TestMicrosandboxPins` checks those runtime values with +`go test ./hack/microsandbox -run TestMicrosandboxPins`. The Linux CI bundle uses msb 0.7.13 and `libkrunfw.so.5.6.1`. Keep the -built-in provider's compatibility expectations separate. The prefetch helper -reads runtime asset names and checksums from the published provider manifest. +built-in driver's ownership synchronization and explicit recreation minimums +separate from the external provider minimum. The docs page lists each check. +The prefetch helper reads runtime asset names and checksums from the published provider manifest. Run the real VM specs on Linux with KVM before claiming parity. --- diff --git a/e2e/tests/up/microsandbox_session.go b/e2e/tests/up/microsandbox_session.go index 73ba814d90..c4b1889c8b 100644 --- a/e2e/tests/up/microsandbox_session.go +++ b/e2e/tests/up/microsandbox_session.go @@ -16,11 +16,12 @@ import ( ) const ( - microsandboxResourceBuiltin = provider.DeprecatedMicrosandboxSource - osLinux = "linux" - osDarwin = "darwin" - microsandboxExternalProvider = "github.com/devsy-org/devsy-provider-microsandbox@v1.1.2" - microsandboxRootUser = "root" + microsandboxResourceBuiltin = provider.DeprecatedMicrosandboxSource + osLinux = "linux" + osDarwin = "darwin" + microsandboxExternalProvider = "github.com/devsy-org/devsy-provider-microsandbox@v1.1.2" + microsandboxExternalMinimumVersion = "0.7.13" + microsandboxRootUser = "root" ) func skipIfNoMicrosandbox(ctx context.Context) { @@ -52,9 +53,10 @@ func checkMicrosandboxVersion(ctx context.Context) { version, err := semver.ParseTolerant( strings.TrimPrefix(strings.TrimSpace(string(output)), "msb "), ) - if err != nil || version.LT(semver.Version{Major: 0, Minor: 7, Patch: 13}) { + if err != nil || version.LT(semver.MustParse(microsandboxExternalMinimumVersion)) { microsandboxUnavailable( - "microsandbox parity requires msb v0.7.13 or newer: " + string(output), + "MicroSandbox parity with the external provider requires msb v" + + microsandboxExternalMinimumVersion + " or newer: " + string(output), ) } } diff --git a/e2e/tests/up/provider_microsandbox_compatibility.go b/e2e/tests/up/provider_microsandbox_compatibility.go index da71226b0c..11f08eb803 100644 --- a/e2e/tests/up/provider_microsandbox_compatibility.go +++ b/e2e/tests/up/provider_microsandbox_compatibility.go @@ -103,7 +103,7 @@ func newCompatibilityFixture( minimumVersion: "0.7.2", } if selection.runtime == providerpkg.ExternalDriver { - fixture.minimumVersion = "0.7.13" + fixture.minimumVersion = microsandboxExternalMinimumVersion } fixture.sandbox = "devsy-" + fixture.uid fixture.label = "devsy.compatibility-parity=" + fixture.uid diff --git a/hack/microsandbox/install.go b/hack/microsandbox/install.go index 495885f4a2..00df2ff0a5 100644 --- a/hack/microsandbox/install.go +++ b/hack/microsandbox/install.go @@ -16,9 +16,9 @@ import ( const ( microsandboxVersion = "v0.7.13" microsandboxURL = "https://github.com/superradcompany/microsandbox/releases/download/" + - "v0.7.13/microsandbox-linux-x86_64.tar.gz" + microsandboxVersion + "/microsandbox-linux-x86_64.tar.gz" microsandboxSHA256 = "c41aeefc050e97f42cd55ce55cc139efc13c6ee2dc371e8d30c325a305a5c3b1" - microsandboxArchive = "microsandbox-linux-x86_64-v0.7.13.tar.gz" + microsandboxArchive = "microsandbox-linux-x86_64-" + microsandboxVersion + ".tar.gz" microsandboxLibrary = "libkrunfw.so.5.6.1" ) diff --git a/hack/microsandbox/pins_test.go b/hack/microsandbox/pins_test.go new file mode 100644 index 0000000000..9c0d83e8c4 --- /dev/null +++ b/hack/microsandbox/pins_test.go @@ -0,0 +1,45 @@ +package main + +import ( + "os" + "path/filepath" + "regexp" + "strings" + "testing" + + "github.com/stretchr/testify/suite" +) + +type microsandboxPinsSuite struct { + suite.Suite +} + +func TestMicrosandboxPins(t *testing.T) { + suite.Run(t, new(microsandboxPinsSuite)) +} + +func (s *microsandboxPinsSuite) TestExternalRuntimeMinimumMatchesCIAndDocs() { + minimum := strings.TrimPrefix(microsandboxVersion, "v") + s.Regexp( + `microsandboxExternalMinimumVersion\s*=\s*"`+regexp.QuoteMeta(minimum)+`"`, + s.read("e2e/tests/up/microsandbox_session.go"), + ) + s.Contains( + s.read("sites/docs-devsy-sh/content/docs/managing-providers/microsandbox.mdx"), + "| External provider | "+minimum+" |", + ) + s.Contains(s.read("AGENTS.md"), "The Linux CI bundle uses msb "+minimum+" and") + workflow := s.read(".github/workflows/pr-ci.yml") + s.Contains(workflow, "path: ${{ runner.temp }}/"+microsandboxArchive+"\n") + s.Contains( + workflow, + "key: ${{ runner.os }}-${{ runner.arch }}-microsandbox-bundle-"+microsandboxVersion+"\n", + ) +} + +func (s *microsandboxPinsSuite) read(path string) string { + s.T().Helper() + content, err := os.ReadFile(filepath.Join("..", "..", filepath.FromSlash(path))) + s.Require().NoError(err) + return strings.ReplaceAll(string(content), "\r\n", "\n") +} diff --git a/pkg/driver/microsandbox/microsandbox.go b/pkg/driver/microsandbox/microsandbox.go index 11f54ed279..0087579ac9 100644 --- a/pkg/driver/microsandbox/microsandbox.go +++ b/pkg/driver/microsandbox/microsandbox.go @@ -63,7 +63,10 @@ var ( _ driver.ProvisioningPreflighter = (*microsandboxDriver)(nil) ) -var minimumMicrosandboxVersion = semver.MustParse("0.7.2") +var ( + minimumBuiltinMicrosandboxVersion = semver.MustParse("0.7.2") + minimumBuiltinMicrosandboxRecreateVersion = semver.MustParse("0.7.7") +) var microsandboxVersionPattern = regexp.MustCompile( `(?:^|[^0-9])v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)`, @@ -331,12 +334,13 @@ func (d *microsandboxDriver) ProvisioningPreflight(ctx context.Context) error { if err != nil { return &driver.PreflightError{Provider: provider.MicrosandboxDriver, Err: err} } - if version.LT(minimumMicrosandboxVersion) { + if version.LT(minimumBuiltinMicrosandboxVersion) { return &driver.PreflightError{Provider: provider.MicrosandboxDriver, Err: fmt.Errorf( - "microsandbox %s is too old for Devsy workspace ownership synchronization; "+ - "v%s or newer is required to create or recreate a workspace. "+ + "msb %s is too old for the built-in MicroSandbox driver; "+ + "v%s or newer is required for workspace ownership synchronization. "+ "Update with `msb self update`", - version, minimumMicrosandboxVersion, + version, + minimumBuiltinMicrosandboxVersion, )} } return nil diff --git a/pkg/driver/microsandbox/microsandbox_test.go b/pkg/driver/microsandbox/microsandbox_test.go index 36bef06113..775ef6455f 100644 --- a/pkg/driver/microsandbox/microsandbox_test.go +++ b/pkg/driver/microsandbox/microsandbox_test.go @@ -220,10 +220,11 @@ func TestRunDevContainerRejectsOldRuntimeBeforeMutation(t *testing.T) { err := d.RunDevContainer(context.Background(), wsID, &driver.RunOptions{Image: imgX}) if err == nil || !strings.Contains( - err.Error(), "v0.7.2 or newer is required to create or recreate", + err.Error(), "v0.7.2 or newer is required for workspace ownership synchronization", ) { t.Fatalf("RunDevContainer error = %v, want provisioning version error", err) } + require.ErrorContains(t, err, "built-in MicroSandbox driver") assertProvisioningUnchanged(t, f) } diff --git a/pkg/driver/microsandbox/recreate.go b/pkg/driver/microsandbox/recreate.go index dc27a5f595..fea1d7bbb9 100644 --- a/pkg/driver/microsandbox/recreate.go +++ b/pkg/driver/microsandbox/recreate.go @@ -4,13 +4,10 @@ import ( "context" "fmt" - "github.com/blang/semver/v4" "github.com/devsy-org/devsy/pkg/driver" "github.com/devsy-org/devsy/pkg/provider" ) -var minimumMicrosandboxRecreateVersion = semver.MustParse("0.7.7") - // Replacement relies on the supported runtime's final validation before teardown, // independently of the ordinary ownership policy and its provisioning minimum. func (d *microsandboxDriver) recreationPreflight(ctx context.Context) error { @@ -25,10 +22,11 @@ func (d *microsandboxDriver) recreationPreflight(ctx context.Context) error { if err != nil { return &driver.PreflightError{Provider: provider.MicrosandboxDriver, Err: err} } - if version.LT(minimumMicrosandboxRecreateVersion) { + if version.LT(minimumBuiltinMicrosandboxRecreateVersion) { return &driver.PreflightError{Provider: provider.MicrosandboxDriver, Err: fmt.Errorf( - "MicroSandbox v%s or newer is required for explicit recreation; update with msb self update", - minimumMicrosandboxRecreateVersion, + "MicroSandbox v%s or newer is required for explicit recreation with the built-in driver; "+ + "update with msb self update", + minimumBuiltinMicrosandboxRecreateVersion, )} } return nil diff --git a/sites/docs-devsy-sh/content/docs/managing-providers/microsandbox.mdx b/sites/docs-devsy-sh/content/docs/managing-providers/microsandbox.mdx index 47f9481a91..3ae347600c 100644 --- a/sites/docs-devsy-sh/content/docs/managing-providers/microsandbox.mdx +++ b/sites/docs-devsy-sh/content/docs/managing-providers/microsandbox.mdx @@ -7,7 +7,7 @@ The external MicroSandbox provider runs Devsy workspaces in microVMs using the M ## Requirements and installation -Install Devsy v1.24.0 or later, which adds the `microsandbox` short name, and the [MicroSandbox CLI](https://github.com/superradcompany/microsandbox#install-the-cli), version 0.7.13 or later. Check `msb --version` in the environment running Devsy. Docker is required for image builds. +Install Devsy v1.24.0 or later, which adds the `microsandbox` short name, and a [MicroSandbox CLI](https://github.com/superradcompany/microsandbox#install-the-cli) that meets the external provider minimum below. Check `msb --version` in the environment running Devsy. Docker is required for image builds. Provider releases contain binaries for Linux amd64 and arm64, macOS arm64, and Windows amd64. Microsandbox VM tests have run only on macOS arm64. The Linux and Windows binaries are built and unit tested in CI, but have not been tested with a running VM. Linux needs accessible KVM. @@ -20,6 +20,16 @@ devsy workspace up . --provider microsandbox A successful add initializes the provider and makes it the default for the current context. Workspaces that do not specify a provider use the default. To keep the current default, add `--use=false` to the add command, then run `devsy provider init microsandbox` before creating a workspace. +## Runtime minimums + +| Driver and operation | Minimum msb version | +| --- | --- | +| External provider | 0.7.13 | +| Built-in driver, workspace ownership synchronization | 0.7.2 | +| Built-in driver, explicit recreation | 0.7.7 | + +The built-in ownership synchronization check does not run when `MICROSANDBOX_WORKSPACE_STAT_VIRTUALIZATION=off`. The explicit recreation check still applies. Inspecting, stopping, and deleting existing built-in workspaces do not require these minimums. + ## Existing built-in installations If the built-in provider is already configured as `microsandbox`, adding the external provider with that name fails. Add it under another name: @@ -62,7 +72,7 @@ An invalid option value stops the workspace from starting and Devsy shows the ca `msb` rejects a bind mount host path that goes through a symbolic link, such as `/tmp` or `/var` on macOS. The provider resolves symbolic links in bind mount host paths, so a project folder under `/tmp` works. Before provider v1.0.5, this failed with `bind mount host path ... goes through symlink /tmp`, and the workaround was the resolved path, for example `/private/tmp/project`. -An `msb` older than 0.7.13 is rejected in two ways. When the provider creates a workspace, it fails with `MicroSandbox v0.7.13 or newer is required`. If a newer `msb` already upgraded the `MSB_HOME` database, the older `msb` refuses it first, and the error includes the `msb inspect` output, for example `database schema is newer than this msb binary`. In both cases, update `msb` with `msb self update`. +The external provider rejects an `msb` older than its minimum in two ways. When it creates a workspace, the error states the required version. If a newer `msb` already upgraded the `MSB_HOME` database, the older `msb` refuses it first, and the error includes the `msb inspect` output, for example `database schema is newer than this msb binary`. In both cases, update `msb` with `msb self update`. Devsy does not put devcontainer environment and label values on the `msb` command line, where other local users could read them with `ps`. The provider passes them through a private runtime configuration file that refers to host variables. The values remain visible in `msb inspect` output, because `msb` stores them with the VM.