Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,37 @@ 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.

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.

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.

## Local development

Use existing matching runtime/firmware with absolute paths:
Expand Down
6 changes: 5 additions & 1 deletion cmd/devsy-runtime-microsandbox/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -61,5 +61,9 @@ func newDriver() (runtimev1.RuntimeDriverServer, error) {
return nil, err
}
}
return server.New(msb.Client{Binary: cfg.MSBPath}, cfg, version)
return server.New(msb.Client{
Binary: cfg.MSBPath,
ImageCLI: cfg.ImageBuilder,
StrictImageLookup: cfg.StrictImageLookup,
}, cfg, version)
}
38 changes: 34 additions & 4 deletions cmd/devsy-runtime-microsandbox/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -232,16 +235,43 @@ 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
}
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")
Expand Down
56 changes: 56 additions & 0 deletions cmd/devsy-runtime-microsandbox/recreate_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package main
import (
"bufio"
"encoding/json"
"fmt"
"io"
"log"
"net/http/httptest"
Expand All @@ -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"
)
Expand All @@ -24,6 +26,60 @@ 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")
s.ErrorContains(err, "set the provider option MICROSANDBOX_IMAGE_BUILDER")
})
}
}

func (s *entrypointSuite) TestRecreatePermissionIsPerPluginProcess() {
image := s.loopbackImage()
dir := s.T().TempDir()
Expand Down
15 changes: 11 additions & 4 deletions internal/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
package config

import (
"cmp"
"errors"
"fmt"
"strconv"
Expand All @@ -15,22 +16,28 @@ const statPolicyOption = "MICROSANDBOX_WORKSPACE_STAT_VIRTUALIZATION"

// Config holds runtime defaults and the primary workspace bind-mount policy.
type Config struct {
MSBPath string
LibkrunfwPath 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.
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"), 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
}
Expand Down
20 changes: 20 additions & 0 deletions internal/config/config_test.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package config

import (
"cmp"
"os"
"testing"
"time"
Expand Down Expand Up @@ -67,6 +68,25 @@ 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)
s.False(cfg.StrictImageLookup)
}

func (s *configSuite) TestImageBuilder() {
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" {
return value
}
return ""
})
s.Require().NoError(err)
want := cmp.Or(value, msb.DefaultImageCLI)
s.Equal(want, cfg.ImageBuilder)
s.Equal(want != msb.DefaultImageCLI, cfg.StrictImageLookup)
})
}
}

func (s *configSuite) TestProviderOptions() {
Expand Down
9 changes: 8 additions & 1 deletion internal/distribution/generate_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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"`
Expand Down
6 changes: 6 additions & 0 deletions internal/distribution/provider.yaml.tmpl
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ optionGroups:
- options:
- MSB_PATH
- MSB_LIBKRUNFW_PATH
- MICROSANDBOX_IMAGE_BUILDER
- MICROSANDBOX_MEMORY
- MICROSANDBOX_CPUS
- MICROSANDBOX_MAX_MEMORY
Expand All @@ -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"
Expand Down Expand Up @@ -71,6 +75,8 @@ agent:
containerInactivityTimeout: ${INACTIVITY_TIMEOUT}
local: true
driver: external
docker:
path: ${MICROSANDBOX_IMAGE_BUILDER}
external:
binary: DEVSY_RUNTIME_DRIVER
args: [serve]
Expand Down
6 changes: 6 additions & 0 deletions internal/distribution/release_test.tmpl
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ optionGroups:
- options:
- MSB_PATH
- MSB_LIBKRUNFW_PATH
- MICROSANDBOX_IMAGE_BUILDER
- MICROSANDBOX_MEMORY
- MICROSANDBOX_CPUS
- MICROSANDBOX_MAX_MEMORY
Expand All @@ -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"
Expand Down Expand Up @@ -67,6 +71,8 @@ agent:
containerInactivityTimeout: ${INACTIVITY_TIMEOUT}
local: true
driver: external
docker:
path: ${MICROSANDBOX_IMAGE_BUILDER}
external:
binary: DEVSY_RUNTIME_DRIVER
args: [serve]
Expand Down
9 changes: 7 additions & 2 deletions internal/msb/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Loading