From 6e2c8785758ed975dd69bb7cc22016ce22861a74 Mon Sep 17 00:00:00 2001 From: Sander Knopper Date: Sat, 14 Nov 2026 18:11:39 +0100 Subject: [PATCH 1/4] feat: support Podman as an image builder Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 19 +++++++ cmd/devsy-runtime-microsandbox/main.go | 11 +++- cmd/devsy-runtime-microsandbox/main_test.go | 53 ++++++++++++++++-- .../recreate_test.go | 55 +++++++++++++++++++ internal/config/config.go | 3 + internal/config/config_test.go | 20 +++++++ internal/distribution/generate_test.go | 9 ++- internal/distribution/provider.yaml.tmpl | 6 ++ internal/distribution/release_test.tmpl | 6 ++ internal/msb/image.go | 47 ++++++++++++++-- internal/msb/image_snapshot_test.go | 25 +++++++++ internal/msb/image_test.go | 22 +++++--- internal/server/runtime_test.go | 3 +- 13 files changed, 261 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index a3c4768..fc4454c 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,25 @@ Platforms: linux amd64/arm64, darwin arm64, windows amd64. See [website documentation](https://devsy.sh/docs/managing-providers/microsandbox) and [contributor guidance](AGENTS.md). +## Podman image builds + +Docker is the default image builder. To use Podman instead: + +```sh +devsy provider set microsandbox --option MICROSANDBOX_IMAGE_BUILDER=podman +devsy workspace up /absolute/path/to/project --provider microsandbox --ide none +``` + +Use `microsandbox-local` instead for the local development provider. The option +also accepts an executable path, without flags. + +Keep connection and environment settings consistent so builds and imports use +the same Podman image store. When using rootless Podman, do not use `sudo`: +rootful Podman has a separate image store. Use `podman login` for private registries. + +No Docker installation or compatibility symlink is needed. Podman builds images +on the host; workspaces still run in MicroSandbox microVMs. Compose is not supported. + ## Local development Use existing matching runtime/firmware with absolute paths: diff --git a/cmd/devsy-runtime-microsandbox/main.go b/cmd/devsy-runtime-microsandbox/main.go index 512a9d2..93c76b1 100644 --- a/cmd/devsy-runtime-microsandbox/main.go +++ b/cmd/devsy-runtime-microsandbox/main.go @@ -4,6 +4,7 @@ package main import ( "fmt" "os" + "os/exec" "github.com/devsy-org/devsy-provider-microsandbox/internal/config" "github.com/devsy-org/devsy-provider-microsandbox/internal/msb" @@ -61,5 +62,13 @@ func newDriver() (runtimev1.RuntimeDriverServer, error) { return nil, err } } - return server.New(msb.Client{Binary: cfg.MSBPath}, cfg, version) + if cfg.ImageBuilder == "docker" { + if _, err := exec.LookPath(cfg.ImageBuilder); err != nil { + fmt.Fprintln( + os.Stderr, + "Docker is unavailable; to use Podman, set the provider option MICROSANDBOX_IMAGE_BUILDER=podman", + ) + } + } + return server.New(msb.Client{Binary: cfg.MSBPath, DockerBinary: cfg.ImageBuilder}, cfg, version) } diff --git a/cmd/devsy-runtime-microsandbox/main_test.go b/cmd/devsy-runtime-microsandbox/main_test.go index c96f7ff..0752c20 100644 --- a/cmd/devsy-runtime-microsandbox/main_test.go +++ b/cmd/devsy-runtime-microsandbox/main_test.go @@ -21,7 +21,10 @@ import ( "google.golang.org/grpc/status" ) -const fixtureEnv = "DEVSY_MSB_ENTRYPOINT_FIXTURE" +const ( + fixtureEnv = "DEVSY_MSB_ENTRYPOINT_FIXTURE" + imageCommand = "image" +) var executable string @@ -75,6 +78,21 @@ func (s *entrypointSuite) TestVersionAndArgumentValidation() { } } +func (s *entrypointSuite) TestMissingDockerSuggestsPodman() { + cmd := exec.Command(executable, "serve") + cmd.Env = append(os.Environ(), + "PATH="+s.T().TempDir(), + "MSB_PATH=", "MSB_LIBKRUNFW_PATH=", + "MICROSANDBOX_IMAGE_BUILDER=docker", + ) + var stderr bytes.Buffer + cmd.Stderr = &stderr + out, err := cmd.Output() + s.Error(err) + s.Empty(out) + s.Contains(stderr.String(), "MICROSANDBOX_IMAGE_BUILDER=podman") +} + func (s *entrypointSuite) TestRealPluginHandshakeAndLogs() { client := s.pluginClient() info, err := client.Info(s.ctx(), &runtimev1.InfoRequest{}) @@ -232,9 +250,9 @@ func runMSBFixture(args []string) int { case "logs": _, _ = os.Stdout.Write([]byte("logs\x00\xff")) case "load": - if _, err := io.Copy(io.Discard, os.Stdin); err != nil { - return 1 - } + return loadImageFixture() + case imageCommand, "save": + return imageCLIFixture(args[0]) case "run": default: return 2 @@ -242,6 +260,33 @@ func runMSBFixture(args []string) int { return 0 } +func loadImageFixture() int { + if _, err := io.Copy(io.Discard, os.Stdin); err != nil { + return 1 + } + return 0 +} + +func imageCLIFixture(command string) int { + archive := os.Getenv("DEVSY_MSB_ENTRYPOINT_IMAGE_ARCHIVE") + if archive == "" { + return 1 + } + if command == imageCommand { + return 0 + } + // #nosec G304 G703 -- the archive belongs to this test fixture. + file, err := os.Open(archive) + if err != nil { + return 1 + } + defer func() { _ = file.Close() }() + if _, err := io.Copy(os.Stdout, file); err != nil { + return 1 + } + return 0 +} + func inspectMSBFixture() int { if os.Getenv("DEVSY_MSB_ENTRYPOINT_EXISTING") == "0" { _, _ = fmt.Fprintln(os.Stderr, "sandbox not found") diff --git a/cmd/devsy-runtime-microsandbox/recreate_test.go b/cmd/devsy-runtime-microsandbox/recreate_test.go index 00a506d..a8fce79 100644 --- a/cmd/devsy-runtime-microsandbox/recreate_test.go +++ b/cmd/devsy-runtime-microsandbox/recreate_test.go @@ -3,6 +3,7 @@ package main import ( "bufio" "encoding/json" + "fmt" "io" "log" "net/http/httptest" @@ -15,6 +16,7 @@ import ( "github.com/google/go-containerregistry/pkg/registry" "github.com/google/go-containerregistry/pkg/v1/empty" "github.com/google/go-containerregistry/pkg/v1/remote" + "github.com/google/go-containerregistry/pkg/v1/tarball" "google.golang.org/grpc/codes" "google.golang.org/grpc/status" ) @@ -24,6 +26,59 @@ const ( recreateWorkspaceID = "workspace" ) +func (s *entrypointSuite) TestImageBuilderReachesPluginSnapshotImport() { + dir := s.T().TempDir() + builder := filepath.Join(dir, "podman.exe") + s.writeFixture(builder) + archive := filepath.Join(dir, "image.tar") + tag, err := name.NewTag("localhost/provider-podman-test:latest") + s.Require().NoError(err) + s.Require().NoError(tarball.WriteToFile(archive, tag, empty.Image)) + for _, built := range []bool{false, true} { + s.Run(fmt.Sprint(built), func() { + record := filepath.Join(s.T().TempDir(), "calls.jsonl") + client := s.pluginClientWithEnv( + "MICROSANDBOX_IMAGE_BUILDER="+builder, + "DEVSY_MSB_ENTRYPOINT_IMAGE_ARCHIVE="+archive, + "DEVSY_MSB_ENTRYPOINT_EXISTING=0", + fixtureRecordEnv+"="+record, + ) + req := recreateRequest(tag.Name(), false) + req.ImageBuiltLocally = built + _, err := client.RunImage(s.ctx(), req) + s.Require().NoError(err) + calls := s.readMSBInvocations(record) + if built { + s.Zero(s.countCLI(calls, imageCommand)) + } else { + s.Equal(1, s.countCLI(calls, imageCommand)) + s.Contains(calls, []string{imageCommand, "inspect", tag.Name()}) + } + s.Contains(calls, []string{"save", tag.Name()}) + s.Equal(1, s.countCLI(calls, "load")) + s.Equal(1, s.countCLI(calls, "run")) + }) + } +} + +func (s *entrypointSuite) TestMissingSelectedImageBuilderDoesNotUseDockerOrRegistry() { + builder := filepath.Join(s.T().TempDir(), "missing-podman") + for _, built := range []bool{false, true} { + s.Run(fmt.Sprint(built), func() { + client := s.pluginClientWithEnv( + "MICROSANDBOX_IMAGE_BUILDER="+builder, + "DEVSY_MSB_ENTRYPOINT_EXISTING=0", + ) + req := recreateRequest(s.loopbackImage(), false) + req.ImageBuiltLocally = built + _, err := client.RunImage(s.ctx(), req) + s.Require().Error(err) + s.ErrorContains(err, "final local image") + s.ErrorContains(err, "missing-podman") + }) + } +} + func (s *entrypointSuite) TestRecreatePermissionIsPerPluginProcess() { image := s.loopbackImage() dir := s.T().TempDir() diff --git a/internal/config/config.go b/internal/config/config.go index 0ded12c..1bd5c01 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -2,6 +2,7 @@ package config import ( + "cmp" "errors" "fmt" "strconv" @@ -17,6 +18,7 @@ const statPolicyOption = "MICROSANDBOX_WORKSPACE_STAT_VIRTUALIZATION" type Config struct { MSBPath string LibkrunfwPath string + ImageBuilder string Defaults msb.Spec WorkspacePolicy msb.MountPolicy } @@ -26,6 +28,7 @@ func Load(getenv func(string) string) (Config, error) { cfg := Config{ MSBPath: runtimePath(getenv("MSB_PATH")), LibkrunfwPath: runtimePath(getenv("MSB_LIBKRUNFW_PATH")), + ImageBuilder: cmp.Or(getenv("MICROSANDBOX_IMAGE_BUILDER"), "docker"), WorkspacePolicy: msb.MountPolicy{ StatVirtualization: msb.StatStrict, HostPermissions: msb.HostMirror, diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 0e23f82..5bcebf2 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -67,6 +67,26 @@ func (s *configSuite) TestDefaults() { s.Equal(msb.StatStrict, cfg.WorkspacePolicy.StatVirtualization) s.Equal(msb.HostMirror, cfg.WorkspacePolicy.HostPermissions) s.Zero(cfg.Defaults.Memory) + s.Equal("docker", cfg.ImageBuilder) +} + +func (s *configSuite) TestImageBuilder() { + for _, value := range []string{"", " \t", "docker", "podman", "/image tools/podman"} { + s.Run(value, func() { + cfg, err := Load(func(key string) string { + if key == "MICROSANDBOX_IMAGE_BUILDER" { + return value + } + return "" + }) + s.Require().NoError(err) + want := value + if value == "" { + want = "docker" + } + s.Equal(want, cfg.ImageBuilder) + }) + } } func (s *configSuite) TestProviderOptions() { diff --git a/internal/distribution/generate_test.go b/internal/distribution/generate_test.go index 0883407..3123026 100644 --- a/internal/distribution/generate_test.go +++ b/internal/distribution/generate_test.go @@ -32,7 +32,9 @@ func (s *distributionSuite) TestManifestPinsEveryExecutableAndPreservesOptions() s.Equal("DEVSY_RUNTIME_DRIVER", parsed.Agent.External.Binary) s.Equal([]string{"serve"}, parsed.Agent.External.Args) s.Equal("docker", parsed.Agent.External.ImageBackend) - s.Len(parsed.Options, 12) + s.Len(parsed.Options, 13) + s.Equal("docker", parsed.Options["MICROSANDBOX_IMAGE_BUILDER"].Default) + s.Equal("${MICROSANDBOX_IMAGE_BUILDER}", parsed.Agent.Docker.Path) s.Contains(parsed.Options, "MSB_PATH") s.Contains(parsed.Options, "MSB_LIBKRUNFW_PATH") s.Equal("2048", parsed.Options["MICROSANDBOX_MEMORY"].Default) @@ -83,11 +85,16 @@ type ( testAgent struct { Local bool `yaml:"local"` Driver string `yaml:"driver"` + Docker testDocker `yaml:"docker"` External testExternal `yaml:"external"` Binaries map[string][]testBinary `yaml:"binaries"` } ) +type testDocker struct { + Path string `yaml:"path"` +} + type testExternal struct { Binary string `yaml:"binary"` Args []string `yaml:"args"` diff --git a/internal/distribution/provider.yaml.tmpl b/internal/distribution/provider.yaml.tmpl index f080439..22f4c07 100644 --- a/internal/distribution/provider.yaml.tmpl +++ b/internal/distribution/provider.yaml.tmpl @@ -8,6 +8,7 @@ optionGroups: - options: - MSB_PATH - MSB_LIBKRUNFW_PATH + - MICROSANDBOX_IMAGE_BUILDER - MICROSANDBOX_MEMORY - MICROSANDBOX_CPUS - MICROSANDBOX_MAX_MEMORY @@ -28,6 +29,9 @@ options: MSB_LIBKRUNFW_PATH: description: "Path to the MicroSandbox firmware library. Set together with MSB_PATH."{{if .Local}} default: {{.Local.Firmware}}{{end}} + MICROSANDBOX_IMAGE_BUILDER: + description: "Docker-compatible image CLI used for host builds and local image imports. Set to podman to use Podman, or an executable path (not a shell command)." + default: docker MICROSANDBOX_MEMORY: description: "Guest memory limit in MiB. Empty uses the runtime default." default: "2048" @@ -71,6 +75,8 @@ agent: containerInactivityTimeout: ${INACTIVITY_TIMEOUT} local: true driver: external + docker: + path: ${MICROSANDBOX_IMAGE_BUILDER} external: binary: DEVSY_RUNTIME_DRIVER args: [serve] diff --git a/internal/distribution/release_test.tmpl b/internal/distribution/release_test.tmpl index 2bd86e1..395b583 100644 --- a/internal/distribution/release_test.tmpl +++ b/internal/distribution/release_test.tmpl @@ -8,6 +8,7 @@ optionGroups: - options: - MSB_PATH - MSB_LIBKRUNFW_PATH + - MICROSANDBOX_IMAGE_BUILDER - MICROSANDBOX_MEMORY - MICROSANDBOX_CPUS - MICROSANDBOX_MAX_MEMORY @@ -24,6 +25,9 @@ options: description: "Path to the MicroSandbox executable. Set together with MSB_LIBKRUNFW_PATH." MSB_LIBKRUNFW_PATH: description: "Path to the MicroSandbox firmware library. Set together with MSB_PATH." + MICROSANDBOX_IMAGE_BUILDER: + description: "Docker-compatible image CLI used for host builds and local image imports. Set to podman to use Podman, or an executable path (not a shell command)." + default: docker MICROSANDBOX_MEMORY: description: "Guest memory limit in MiB. Empty uses the runtime default." default: "2048" @@ -67,6 +71,8 @@ agent: containerInactivityTimeout: ${INACTIVITY_TIMEOUT} local: true driver: external + docker: + path: ${MICROSANDBOX_IMAGE_BUILDER} external: binary: DEVSY_RUNTIME_DRIVER args: [serve] diff --git a/internal/msb/image.go b/internal/msb/image.go index feaeb7e..1f2a527 100644 --- a/internal/msb/image.go +++ b/internal/msb/image.go @@ -17,6 +17,8 @@ import ( "github.com/google/go-containerregistry/pkg/v1/tarball" ) +const defaultDockerBinary = "docker" + // PreparedImage keeps the final image available for validation and import. // Close it only after all lazy image and layer reads have finished. type PreparedImage struct { @@ -55,7 +57,14 @@ func (c Client) PrepareImage( } var prepared *PreparedImage var err error - if builtLocally || c.localImageAvailable(ctx, ref) { + local := builtLocally + if !local { + local, err = c.localImageAvailable(ctx, ref) + } + if err != nil { + return nil, err + } + if local { prepared, err = c.localImage(ctx, ref) } else { prepared, err = registryImage(ctx, ref) @@ -128,14 +137,38 @@ func (c Client) dockerBinary() string { if c.DockerBinary != "" { return c.DockerBinary } - return "docker" + return defaultDockerBinary } -func (c Client) localImageAvailable(ctx context.Context, ref string) bool { +func (c Client) localImageAvailable(ctx context.Context, ref string) (bool, error) { ctx, cancel := context.WithTimeout(ctx, 5*time.Second) defer cancel() // #nosec G204 -- configured Docker-compatible executable and fixed inspection arguments. - return exec.CommandContext(ctx, c.dockerBinary(), "image", "inspect", ref).Run() == nil + output, err := exec.CommandContext(ctx, c.dockerBinary(), "image", "inspect", ref). + CombinedOutput() + if err == nil { + return true, nil + } + // Preserve Docker's optional local lookup for registry-only workspaces. + if c.dockerBinary() == defaultDockerBinary || + (ctx.Err() == nil && missingLocalImage(err, string(output))) { + return false, nil + } + return false, fmt.Errorf("inspect final local image %q with %q: %s: %w", + ref, c.dockerBinary(), strings.TrimSpace(string(output)), errors.Join(err, ctx.Err())) +} + +func missingLocalImage(err error, output string) bool { + if _, ok := errors.AsType[*exec.ExitError](err); !ok { + return false + } + output = strings.ToLower(output) + for _, marker := range []string{"no such image", "no such object", "image not known"} { + if strings.Contains(output, marker) { + return true + } + } + return false } func (c Client) localImage(ctx context.Context, ref string) (*PreparedImage, error) { @@ -153,6 +186,12 @@ func (c Client) localImage(ctx context.Context, ref string) (*PreparedImage, err closeErr := archive.Close() if err := errors.Join(runErr, closeErr, ctx.Err()); err != nil { _ = prepared.Close() + if c.dockerBinary() == defaultDockerBinary && errors.Is(runErr, exec.ErrNotFound) { + err = fmt.Errorf( + "%w; to use Podman, set the provider option MICROSANDBOX_IMAGE_BUILDER=podman", + err, + ) + } return nil, fmt.Errorf( "save final local image %q: %s: %w", ref, diff --git a/internal/msb/image_snapshot_test.go b/internal/msb/image_snapshot_test.go index 8e4498e..93a283e 100644 --- a/internal/msb/image_snapshot_test.go +++ b/internal/msb/image_snapshot_test.go @@ -64,6 +64,31 @@ func (s *clientSuite) TestConfiguredDockerBinary() { s.assertImportedDigest(digest) } +func (s *clientSuite) TestConfiguredBuilderInspectionDistinguishesMissingImageFromFailure() { + server := httptest.NewServer(registry.New(registry.Logger(log.New(io.Discard, "", 0)))) + defer server.Close() + ref, err := name.NewTag(server.Listener.Addr().String()+"/probe:latest", name.Insecure) + s.Require().NoError(err) + s.Require().NoError(remote.Write(ref, s.hostImage())) + for _, mode := range []string{"image-missing", modeInspectFail} { + s.Run(mode, func() { + s.installDockerHelper() + s.client.DockerBinary = s.client.Binary + s.T().Setenv("DEVSY_MSB_TEST_MODE", mode) + s.T().Setenv("DOCKER_CONFIG", s.T().TempDir()) + prepared, err := s.client.PrepareImage(context.Background(), ref.Name(), false) + if mode == modeInspectFail { + s.ErrorContains(err, "inspect final local image") + s.ErrorContains(err, "store unavailable") + s.Nil(prepared) + return + } + s.Require().NoError(err) + s.NoError(prepared.Close()) + }) + } +} + func (s *clientSuite) TestRegistrySnapshotSurvivesTagChange() { server := httptest.NewServer(registry.New(registry.Logger(log.New(io.Discard, "", 0)))) defer server.Close() diff --git a/internal/msb/image_test.go b/internal/msb/image_test.go index a451c0e..75dfe90 100644 --- a/internal/msb/image_test.go +++ b/internal/msb/image_test.go @@ -25,13 +25,14 @@ import ( ) const ( - testLinux = "linux" - modeLoadFail = "load-fail" - modeDocker = "docker" - modeSaveFail = "save-fail" - imageSave = "save" - imageLoad = "load" - hostMarker = "MARKER=host" + testLinux = "linux" + modeLoadFail = "load-fail" + modeDocker = "docker" + modeSaveFail = "save-fail" + modeInspectFail = "inspect-fail" + imageSave = "save" + imageLoad = "load" + hostMarker = "MARKER=host" ) func (s *clientSuite) TestImageLocalDockerLoad() { @@ -62,6 +63,7 @@ func (s *clientSuite) TestImageMissingBuiltImageDoesNotPull() { s.T().Setenv("PATH", s.T().TempDir()) _, err := s.client.PrepareImage(context.Background(), testImg, true) s.ErrorContains(err, "save final local image") + s.ErrorContains(err, "MICROSANDBOX_IMAGE_BUILDER=podman") _, err = os.Stat(s.record) s.ErrorIs(err, os.ErrNotExist) } @@ -202,6 +204,12 @@ func dockerInspectHelper(mode string) int { if mode == modeDocker || mode == modeSaveFail || mode == modeLoadFail { return 0 } + switch mode { + case "image-missing": + _ = writeHelper(os.Stderr, "image not known") + case modeInspectFail: + _ = writeHelper(os.Stderr, "store unavailable") + } return 1 } diff --git a/internal/server/runtime_test.go b/internal/server/runtime_test.go index f8ccd0e..9c26e99 100644 --- a/internal/server/runtime_test.go +++ b/internal/server/runtime_test.go @@ -380,7 +380,8 @@ func (s *runtimeSuite) prepareImage() { ref, err := name.ParseReference(strings.TrimPrefix(server.URL, "http://") + "/image:test") s.Require().NoError(err) s.Require().NoError(remote.Write(ref, empty.Image)) - prepared, err := (msb.Client{DockerBinary: "missing-test-docker"}).PrepareImage( + s.T().Setenv("PATH", s.T().TempDir()) + prepared, err := (msb.Client{}).PrepareImage( context.Background(), ref.Name(), false, From fac31cd88a952468754e011f6a2486bef5d8826b Mon Sep 17 00:00:00 2001 From: Sander Knopper Date: Sat, 14 Nov 2026 21:09:51 +0100 Subject: [PATCH 2/4] refactor: simplify image builder lookup and hints Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 7 ++ cmd/devsy-runtime-microsandbox/main.go | 15 ++-- cmd/devsy-runtime-microsandbox/main_test.go | 15 ---- .../recreate_test.go | 1 + internal/config/config.go | 16 +++-- internal/config/config_test.go | 10 +-- internal/msb/cli.go | 9 ++- internal/msb/image.go | 68 ++++++++++--------- internal/msb/image_snapshot_test.go | 26 ++++--- internal/msb/image_test.go | 26 +++---- internal/msb/image_user_test.go | 2 +- 11 files changed, 104 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index fc4454c..a8dfb88 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,13 @@ Keep connection and environment settings consistent so builds and imports use the same Podman image store. When using rootless Podman, do not use `sudo`: rootful Podman has a separate image store. Use `podman login` for private registries. +Before pulling an image that Devsy did not build, the provider checks for a +local copy with `image inspect`. That check times out after 5 seconds. With the +default `docker`, any failed check falls back to the registry. With any other +value, only a missing image falls back; other failures, including a timeout, +fail the workspace. Start Podman, or `podman machine` on macOS, before running +a workspace. + No Docker installation or compatibility symlink is needed. Podman builds images on the host; workspaces still run in MicroSandbox microVMs. Compose is not supported. diff --git a/cmd/devsy-runtime-microsandbox/main.go b/cmd/devsy-runtime-microsandbox/main.go index 93c76b1..1d11856 100644 --- a/cmd/devsy-runtime-microsandbox/main.go +++ b/cmd/devsy-runtime-microsandbox/main.go @@ -4,7 +4,6 @@ package main import ( "fmt" "os" - "os/exec" "github.com/devsy-org/devsy-provider-microsandbox/internal/config" "github.com/devsy-org/devsy-provider-microsandbox/internal/msb" @@ -62,13 +61,9 @@ func newDriver() (runtimev1.RuntimeDriverServer, error) { return nil, err } } - if cfg.ImageBuilder == "docker" { - if _, err := exec.LookPath(cfg.ImageBuilder); err != nil { - fmt.Fprintln( - os.Stderr, - "Docker is unavailable; to use Podman, set the provider option MICROSANDBOX_IMAGE_BUILDER=podman", - ) - } - } - return server.New(msb.Client{Binary: cfg.MSBPath, DockerBinary: cfg.ImageBuilder}, cfg, version) + return server.New(msb.Client{ + Binary: cfg.MSBPath, + ImageCLI: cfg.ImageBuilder, + StrictImageLookup: cfg.StrictImageLookup, + }, cfg, version) } diff --git a/cmd/devsy-runtime-microsandbox/main_test.go b/cmd/devsy-runtime-microsandbox/main_test.go index 0752c20..6401def 100644 --- a/cmd/devsy-runtime-microsandbox/main_test.go +++ b/cmd/devsy-runtime-microsandbox/main_test.go @@ -78,21 +78,6 @@ func (s *entrypointSuite) TestVersionAndArgumentValidation() { } } -func (s *entrypointSuite) TestMissingDockerSuggestsPodman() { - cmd := exec.Command(executable, "serve") - cmd.Env = append(os.Environ(), - "PATH="+s.T().TempDir(), - "MSB_PATH=", "MSB_LIBKRUNFW_PATH=", - "MICROSANDBOX_IMAGE_BUILDER=docker", - ) - var stderr bytes.Buffer - cmd.Stderr = &stderr - out, err := cmd.Output() - s.Error(err) - s.Empty(out) - s.Contains(stderr.String(), "MICROSANDBOX_IMAGE_BUILDER=podman") -} - func (s *entrypointSuite) TestRealPluginHandshakeAndLogs() { client := s.pluginClient() info, err := client.Info(s.ctx(), &runtimev1.InfoRequest{}) diff --git a/cmd/devsy-runtime-microsandbox/recreate_test.go b/cmd/devsy-runtime-microsandbox/recreate_test.go index a8fce79..dd72348 100644 --- a/cmd/devsy-runtime-microsandbox/recreate_test.go +++ b/cmd/devsy-runtime-microsandbox/recreate_test.go @@ -75,6 +75,7 @@ func (s *entrypointSuite) TestMissingSelectedImageBuilderDoesNotUseDockerOrRegis s.Require().Error(err) s.ErrorContains(err, "final local image") s.ErrorContains(err, "missing-podman") + s.ErrorContains(err, "set the provider option MICROSANDBOX_IMAGE_BUILDER") }) } } diff --git a/internal/config/config.go b/internal/config/config.go index 1bd5c01..54b1894 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -16,11 +16,14 @@ const statPolicyOption = "MICROSANDBOX_WORKSPACE_STAT_VIRTUALIZATION" // Config holds runtime defaults and the primary workspace bind-mount policy. type Config struct { - MSBPath string - LibkrunfwPath string - ImageBuilder string - Defaults msb.Spec - WorkspacePolicy msb.MountPolicy + MSBPath string + LibkrunfwPath string + ImageBuilder string + // StrictImageLookup is false only for the default builder, whose + // lookup failures historically fall back to the registry. + StrictImageLookup bool + Defaults msb.Spec + WorkspacePolicy msb.MountPolicy } // Load reads provider options without accessing process-global environment state. @@ -28,12 +31,13 @@ func Load(getenv func(string) string) (Config, error) { cfg := Config{ MSBPath: runtimePath(getenv("MSB_PATH")), LibkrunfwPath: runtimePath(getenv("MSB_LIBKRUNFW_PATH")), - ImageBuilder: cmp.Or(getenv("MICROSANDBOX_IMAGE_BUILDER"), "docker"), + ImageBuilder: cmp.Or(getenv("MICROSANDBOX_IMAGE_BUILDER"), msb.DefaultImageCLI), WorkspacePolicy: msb.MountPolicy{ StatVirtualization: msb.StatStrict, HostPermissions: msb.HostMirror, }, } + cfg.StrictImageLookup = cfg.ImageBuilder != msb.DefaultImageCLI if err := loadResources(getenv, &cfg); err != nil { return Config{}, err } diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 5bcebf2..08cdc7e 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -1,6 +1,7 @@ package config import ( + "cmp" "os" "testing" "time" @@ -68,10 +69,11 @@ func (s *configSuite) TestDefaults() { s.Equal(msb.HostMirror, cfg.WorkspacePolicy.HostPermissions) s.Zero(cfg.Defaults.Memory) s.Equal("docker", cfg.ImageBuilder) + s.False(cfg.StrictImageLookup) } func (s *configSuite) TestImageBuilder() { - for _, value := range []string{"", " \t", "docker", "podman", "/image tools/podman"} { + for _, value := range []string{"", "docker", "podman", "/image tools/podman"} { s.Run(value, func() { cfg, err := Load(func(key string) string { if key == "MICROSANDBOX_IMAGE_BUILDER" { @@ -80,11 +82,9 @@ func (s *configSuite) TestImageBuilder() { return "" }) s.Require().NoError(err) - want := value - if value == "" { - want = "docker" - } + want := cmp.Or(value, msb.DefaultImageCLI) s.Equal(want, cfg.ImageBuilder) + s.Equal(want != msb.DefaultImageCLI, cfg.StrictImageLookup) }) } } diff --git a/internal/msb/cli.go b/internal/msb/cli.go index b8171b2..52d5916 100644 --- a/internal/msb/cli.go +++ b/internal/msb/cli.go @@ -18,8 +18,13 @@ import ( // A zero value discovers msb on PATH or in its standard per-user installation directories. type Client struct { Binary string - // DockerBinary selects a Docker-compatible CLI for local image snapshots. - DockerBinary string + // ImageCLI selects a Docker-compatible CLI for local image snapshots. + // Empty uses DefaultImageCLI. + ImageCLI string + // StrictImageLookup fails a local image lookup that errors for any reason + // other than a missing image. Otherwise every lookup failure falls back to + // the registry, which keeps registry-only workspaces working without Docker. + StrictImageLookup bool } // EnsureInstalled checks discovery without imposing provisioning version policy. diff --git a/internal/msb/image.go b/internal/msb/image.go index 1f2a527..9a639c2 100644 --- a/internal/msb/image.go +++ b/internal/msb/image.go @@ -4,6 +4,7 @@ import ( "context" "errors" "fmt" + "io/fs" "os" "os/exec" "runtime" @@ -17,7 +18,11 @@ import ( "github.com/google/go-containerregistry/pkg/v1/tarball" ) -const defaultDockerBinary = "docker" +// DefaultImageCLI is the Docker-compatible CLI used when none is configured. +const DefaultImageCLI = "docker" + +const imageCLIHint = "set the provider option MICROSANDBOX_IMAGE_BUILDER " + + "to an installed Docker-compatible CLI, such as podman" // PreparedImage keeps the final image available for validation and import. // Close it only after all lazy image and layer reads have finished. @@ -59,10 +64,9 @@ func (c Client) PrepareImage( var err error local := builtLocally if !local { - local, err = c.localImageAvailable(ctx, ref) - } - if err != nil { - return nil, err + if local, err = c.localImageAvailable(ctx, ref); err != nil { + return nil, err + } } if local { prepared, err = c.localImage(ctx, ref) @@ -133,44 +137,52 @@ func (c Client) importSnapshot( return nil } -func (c Client) dockerBinary() string { - if c.DockerBinary != "" { - return c.DockerBinary +func (c Client) imageCLI() string { + if c.ImageCLI != "" { + return c.ImageCLI } - return defaultDockerBinary + return DefaultImageCLI } func (c Client) localImageAvailable(ctx context.Context, ref string) (bool, error) { ctx, cancel := context.WithTimeout(ctx, 5*time.Second) defer cancel() // #nosec G204 -- configured Docker-compatible executable and fixed inspection arguments. - output, err := exec.CommandContext(ctx, c.dockerBinary(), "image", "inspect", ref). - CombinedOutput() - if err == nil { + cmd := exec.CommandContext(ctx, c.imageCLI(), "image", "inspect", ref) + var stderr strings.Builder + cmd.Stderr = &stderr + err := cmd.Run() + switch { + case err == nil: return true, nil - } - // Preserve Docker's optional local lookup for registry-only workspaces. - if c.dockerBinary() == defaultDockerBinary || - (ctx.Err() == nil && missingLocalImage(err, string(output))) { + case !c.StrictImageLookup: + return false, nil + case ctx.Err() == nil && missingLocalImage(stderr.String()): return false, nil } return false, fmt.Errorf("inspect final local image %q with %q: %s: %w", - ref, c.dockerBinary(), strings.TrimSpace(string(output)), errors.Join(err, ctx.Err())) + ref, c.imageCLI(), strings.TrimSpace(stderr.String()), + withImageCLIHint(errors.Join(err, ctx.Err()))) } -func missingLocalImage(err error, output string) bool { - if _, ok := errors.AsType[*exec.ExitError](err); !ok { - return false - } - output = strings.ToLower(output) +func missingLocalImage(stderr string) bool { + stderr = strings.ToLower(stderr) for _, marker := range []string{"no such image", "no such object", "image not known"} { - if strings.Contains(output, marker) { + if strings.Contains(stderr, marker) { return true } } return false } +func withImageCLIHint(err error) error { + // A name searched on PATH reports ErrNotFound; an explicit path reports ErrNotExist. + if errors.Is(err, exec.ErrNotFound) || errors.Is(err, fs.ErrNotExist) { + return fmt.Errorf("%w; %s", err, imageCLIHint) + } + return err +} + func (c Client) localImage(ctx context.Context, ref string) (*PreparedImage, error) { archive, err := os.CreateTemp("", "devsy-msb-image-*.tar") if err != nil { @@ -178,7 +190,7 @@ func (c Client) localImage(ctx context.Context, ref string) (*PreparedImage, err } prepared := &PreparedImage{archive: archive.Name()} // #nosec G204 -- configured Docker-compatible executable, fixed subcommand, image argument. - cmd := exec.CommandContext(ctx, c.dockerBinary(), "save", ref) + cmd := exec.CommandContext(ctx, c.imageCLI(), "save", ref) cmd.Stdout = archive var stderr strings.Builder cmd.Stderr = &stderr @@ -186,17 +198,11 @@ func (c Client) localImage(ctx context.Context, ref string) (*PreparedImage, err closeErr := archive.Close() if err := errors.Join(runErr, closeErr, ctx.Err()); err != nil { _ = prepared.Close() - if c.dockerBinary() == defaultDockerBinary && errors.Is(runErr, exec.ErrNotFound) { - err = fmt.Errorf( - "%w; to use Podman, set the provider option MICROSANDBOX_IMAGE_BUILDER=podman", - err, - ) - } return nil, fmt.Errorf( "save final local image %q: %s: %w", ref, strings.TrimSpace(stderr.String()), - err, + withImageCLIHint(err), ) } prepared.image, err = tarball.ImageFromPath(prepared.archive, nil) diff --git a/internal/msb/image_snapshot_test.go b/internal/msb/image_snapshot_test.go index 93a283e..6301c64 100644 --- a/internal/msb/image_snapshot_test.go +++ b/internal/msb/image_snapshot_test.go @@ -4,6 +4,7 @@ import ( "bytes" "context" "crypto/rand" + "fmt" "io" "log" "net/http" @@ -49,11 +50,11 @@ func (s *clientSuite) TestLocalSnapshotSurvivesSourceChange() { s.NoError(prepared.Close()) } -func (s *clientSuite) TestConfiguredDockerBinary() { +func (s *clientSuite) TestConfiguredImageCLI() { s.installDockerHelper() s.T().Setenv("PATH", s.T().TempDir()) s.T().Setenv("DEVSY_MSB_TEST_MODE", modeDocker) - s.client.DockerBinary = s.client.Binary + s.client.ImageCLI = s.client.Binary prepared, err := s.client.PrepareImage(context.Background(), testImg, true) s.Require().NoError(err) defer func() { _ = prepared.Close() }() @@ -64,20 +65,29 @@ func (s *clientSuite) TestConfiguredDockerBinary() { s.assertImportedDigest(digest) } -func (s *clientSuite) TestConfiguredBuilderInspectionDistinguishesMissingImageFromFailure() { +func (s *clientSuite) TestImageLookupFailureFallsBackOnlyWhenNotStrict() { server := httptest.NewServer(registry.New(registry.Logger(log.New(io.Discard, "", 0)))) defer server.Close() ref, err := name.NewTag(server.Listener.Addr().String()+"/probe:latest", name.Insecure) s.Require().NoError(err) s.Require().NoError(remote.Write(ref, s.hostImage())) - for _, mode := range []string{"image-missing", modeInspectFail} { - s.Run(mode, func() { + for _, tc := range []struct { + mode string + strict bool + failure bool + }{ + {modeImageMissing, true, false}, + {modeInspectFail, true, true}, + {modeInspectFail, false, false}, + } { + s.Run(fmt.Sprint(tc.mode, "/strict=", tc.strict), func() { s.installDockerHelper() - s.client.DockerBinary = s.client.Binary - s.T().Setenv("DEVSY_MSB_TEST_MODE", mode) + s.client.ImageCLI = s.client.Binary + s.client.StrictImageLookup = tc.strict + s.T().Setenv("DEVSY_MSB_TEST_MODE", tc.mode) s.T().Setenv("DOCKER_CONFIG", s.T().TempDir()) prepared, err := s.client.PrepareImage(context.Background(), ref.Name(), false) - if mode == modeInspectFail { + if tc.failure { s.ErrorContains(err, "inspect final local image") s.ErrorContains(err, "store unavailable") s.Nil(prepared) diff --git a/internal/msb/image_test.go b/internal/msb/image_test.go index 75dfe90..e716e28 100644 --- a/internal/msb/image_test.go +++ b/internal/msb/image_test.go @@ -25,14 +25,15 @@ import ( ) const ( - testLinux = "linux" - modeLoadFail = "load-fail" - modeDocker = "docker" - modeSaveFail = "save-fail" - modeInspectFail = "inspect-fail" - imageSave = "save" - imageLoad = "load" - hostMarker = "MARKER=host" + testLinux = "linux" + modeLoadFail = "load-fail" + modeDocker = "docker" + modeSaveFail = "save-fail" + modeInspectFail = "inspect-fail" + modeImageMissing = "image-missing" + imageSave = "save" + imageLoad = "load" + hostMarker = "MARKER=host" ) func (s *clientSuite) TestImageLocalDockerLoad() { @@ -63,7 +64,7 @@ func (s *clientSuite) TestImageMissingBuiltImageDoesNotPull() { s.T().Setenv("PATH", s.T().TempDir()) _, err := s.client.PrepareImage(context.Background(), testImg, true) s.ErrorContains(err, "save final local image") - s.ErrorContains(err, "MICROSANDBOX_IMAGE_BUILDER=podman") + s.ErrorContains(err, "MICROSANDBOX_IMAGE_BUILDER") _, err = os.Stat(s.record) s.ErrorIs(err, os.ErrNotExist) } @@ -201,11 +202,10 @@ func loadHelper() int { } func dockerInspectHelper(mode string) int { - if mode == modeDocker || mode == modeSaveFail || mode == modeLoadFail { - return 0 - } switch mode { - case "image-missing": + case modeDocker, modeSaveFail, modeLoadFail: + return 0 + case modeImageMissing: _ = writeHelper(os.Stderr, "image not known") case modeInspectFail: _ = writeHelper(os.Stderr, "store unavailable") diff --git a/internal/msb/image_user_test.go b/internal/msb/image_user_test.go index 4b633af..65970f6 100644 --- a/internal/msb/image_user_test.go +++ b/internal/msb/image_user_test.go @@ -251,7 +251,7 @@ func (s *imageUserSuite) TestOwnerAndImportShareLocalSnapshot() { s.T().Setenv("DEVSY_MSB_TEST_MODE", modeDocker) s.T().Setenv("DEVSY_MSB_TEST_RECORD", record) s.T().Setenv("DEVSY_MSB_TEST_IMAGE_ARCHIVE", archive) - client := Client{Binary: binary, DockerBinary: binary} + client := Client{Binary: binary, ImageCLI: binary} prepared, err := client.PrepareImage(context.Background(), testImg, true) s.Require().NoError(err) defer func() { _ = prepared.Close() }() From bd81c71f2570ece28e84180d4e3dd90ba80b37c4 Mon Sep 17 00:00:00 2001 From: Samuel K Date: Mon, 16 Nov 2026 19:16:00 -0600 Subject: [PATCH 3/4] fix: isolate registry fixtures and clarify Podman authentication --- README.md | 7 ++++++- internal/server/runtime_test.go | 6 ++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a8dfb88..b9fe285 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ also accepts an executable path, without flags. Keep connection and environment settings consistent so builds and imports use the same Podman image store. When using rootless Podman, do not use `sudo`: -rootful Podman has a separate image store. Use `podman login` for private registries. +rootful Podman has a separate image store. Before pulling an image that Devsy did not build, the provider checks for a local copy with `image inspect`. That check times out after 5 seconds. With the @@ -41,6 +41,11 @@ value, only a missing image falls back; other failures, including a timeout, fail the workspace. Start Podman, or `podman machine` on macOS, before running a workspace. +Registry fallback uses Docker-compatible credentials and can ignore Podman's +login file when a Docker configuration exists. For private images authenticated +with `podman login`, run `podman pull registry.example.com/team/image:tag` +before starting the workspace. The provider then imports the local image. + No Docker installation or compatibility symlink is needed. Podman builds images on the host; workspaces still run in MicroSandbox microVMs. Compose is not supported. diff --git a/internal/server/runtime_test.go b/internal/server/runtime_test.go index 9c26e99..0fb01ad 100644 --- a/internal/server/runtime_test.go +++ b/internal/server/runtime_test.go @@ -6,6 +6,8 @@ import ( "io" "math" "net/http/httptest" + "os" + "path/filepath" "strings" "testing" "time" @@ -381,6 +383,10 @@ func (s *runtimeSuite) prepareImage() { s.Require().NoError(err) s.Require().NoError(remote.Write(ref, empty.Image)) s.T().Setenv("PATH", s.T().TempDir()) + dockerConfig := s.T().TempDir() + s.Require(). + NoError(os.WriteFile(filepath.Join(dockerConfig, "config.json"), []byte("{}"), 0o600)) + s.T().Setenv("DOCKER_CONFIG", dockerConfig) prepared, err := (msb.Client{}).PrepareImage( context.Background(), ref.Name(), From 77d5f7494cc48596aff8846af4dd9354c045567d Mon Sep 17 00:00:00 2001 From: Samuel K Date: Mon, 16 Nov 2026 21:23:27 -0600 Subject: [PATCH 4/4] test: isolate snapshot fallback registry credentials --- internal/msb/image_snapshot_test.go | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/internal/msb/image_snapshot_test.go b/internal/msb/image_snapshot_test.go index 6301c64..3408f5e 100644 --- a/internal/msb/image_snapshot_test.go +++ b/internal/msb/image_snapshot_test.go @@ -85,7 +85,10 @@ func (s *clientSuite) TestImageLookupFailureFallsBackOnlyWhenNotStrict() { s.client.ImageCLI = s.client.Binary s.client.StrictImageLookup = tc.strict s.T().Setenv("DEVSY_MSB_TEST_MODE", tc.mode) - s.T().Setenv("DOCKER_CONFIG", s.T().TempDir()) + dockerConfig := s.T().TempDir() + s.Require(). + NoError(os.WriteFile(filepath.Join(dockerConfig, "config.json"), []byte("{}"), 0o600)) + s.T().Setenv("DOCKER_CONFIG", dockerConfig) prepared, err := s.client.PrepareImage(context.Background(), ref.Name(), false) if tc.failure { s.ErrorContains(err, "inspect final local image")