Skip to content

Commit 44e843e

Browse files
authored
feat(vm): fall back to Podman socket when Docker is unavailable (#1370)
* test(e2e): add bypass detection test for sandbox REJECT rules Validates that direct TCP connections bypassing the HTTP CONNECT proxy are rejected immediately (ECONNREFUSED) rather than hanging until a network timeout. This is implementation-agnostic — it tests observable kernel behavior regardless of whether rules are installed via iptables or nftables. * feat(vm): fall back to Podman socket when Docker is unavailable The VM driver resolves sandbox images from a local container engine before falling back to registry pulls. Previously it only checked Docker. Now it tries the Podman socket as a fallback, since Podman exposes a Docker-compatible API via bollard. On Linux, enable the Podman API socket with: systemctl --user start podman.socket Signed-off-by: Russell Bryant <[email protected]> * chore(vm): fix formatting Signed-off-by: Russell Bryant <[email protected]> * refactor(vm): rename docker-specific identifiers to engine-neutral names Rename resolve_local_docker_image → resolve_local_container_image, local_docker_image_platform_mismatch → local_image_platform_mismatch, and the local docker variable → engine since the function now supports both Docker and Podman backends. Signed-off-by: Russell Bryant <[email protected]> --------- Signed-off-by: Russell Bryant <[email protected]>
1 parent c27dd88 commit 44e843e

3 files changed

Lines changed: 92 additions & 33 deletions

File tree

‎crates/openshell-driver-vm/README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -166,9 +166,12 @@ The VM guest's serial console is appended to `<state-dir>/<sandbox-id>/console.l
166166
- Matching rustup target: `rustup target add aarch64-unknown-linux-gnu` (or `x86_64-unknown-linux-gnu` for an amd64 guest)
167167
- `cargo install --locked cargo-zigbuild` and `brew install zig` (or distro equivalent). `vm:supervisor` uses `cargo zigbuild` to cross-compile the in-VM `openshell-sandbox` supervisor binary.
168168
- [mise](https://mise.jdx.dev/) task runner
169-
- Docker-compatible socket on the local CLI/gateway host when using
169+
- Docker or Podman socket on the local CLI/gateway host when using
170170
`openshell sandbox create --from ./Dockerfile` or `--from ./dir`; the CLI
171-
builds the image and the VM driver exports it via the local Docker daemon
171+
builds the image and the VM driver exports it via the local container engine.
172+
Docker is tried first; if unavailable, the driver falls back to the Podman
173+
socket. On Linux, enable the Podman API socket with
174+
`systemctl --user start podman.socket`
172175
- `gh` CLI (used by `mise run vm:setup` to download pre-built runtime artifacts)
173176
174177
## Releases

‎crates/openshell-driver-vm/src/driver.rs‎

Lines changed: 79 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -758,12 +758,14 @@ impl VmDriver {
758758
sandbox_id: &str,
759759
image_ref: &str,
760760
) -> Result<String, Status> {
761-
if let Some((docker, image_identity)) = self.resolve_local_docker_image(image_ref).await? {
761+
if let Some((engine, image_identity)) =
762+
self.resolve_local_container_image(image_ref).await?
763+
{
762764
return self
763765
.ensure_cached_local_image_rootfs_archive(
764766
sandbox_id,
765767
image_ref,
766-
&docker,
768+
&engine,
767769
&image_identity,
768770
)
769771
.await;
@@ -856,31 +858,30 @@ impl VmDriver {
856858
Ok(image_identity)
857859
}
858860

859-
async fn resolve_local_docker_image(
861+
async fn resolve_local_container_image(
860862
&self,
861863
image_ref: &str,
862864
) -> Result<Option<(Docker, String)>, Status> {
863865
let required_local_image = is_openshell_local_build_image_ref(image_ref);
864-
let docker = match Docker::connect_with_local_defaults() {
865-
Ok(docker) => docker,
866-
Err(err) if required_local_image => {
866+
let engine = match connect_local_container_engine().await {
867+
Some(engine) => engine,
868+
None if required_local_image => {
867869
return Err(Status::failed_precondition(format!(
868-
"failed to connect to local Docker daemon for locally built sandbox image '{image_ref}': {err}"
870+
"no container engine (Docker/Podman) available for locally built sandbox image '{image_ref}'"
869871
)));
870872
}
871-
Err(err) => {
873+
None => {
872874
warn!(
873875
image_ref = %image_ref,
874-
error = %err,
875-
"vm driver: local Docker daemon unavailable, falling back to registry"
876+
"vm driver: no local container engine available, falling back to registry"
876877
);
877878
return Ok(None);
878879
}
879880
};
880881

881-
match docker.inspect_image(image_ref).await {
882+
match engine.inspect_image(image_ref).await {
882883
Ok(inspect) => {
883-
if let Some(message) = local_docker_image_platform_mismatch(
884+
if let Some(message) = local_image_platform_mismatch(
884885
image_ref,
885886
inspect.os.as_deref(),
886887
inspect.architecture.as_deref(),
@@ -891,30 +892,28 @@ impl VmDriver {
891892
warn!(
892893
image_ref = %image_ref,
893894
%message,
894-
"vm driver: local Docker image platform mismatch, falling back to registry"
895+
"vm driver: local container image platform mismatch, falling back to registry"
895896
);
896897
return Ok(None);
897898
}
898899

899-
let image_identity =
900-
inspect
901-
.id
902-
.filter(|id| !id.trim().is_empty())
903-
.ok_or_else(|| {
904-
Status::failed_precondition(format!(
905-
"local Docker image '{image_ref}' inspect response has no image ID"
906-
))
907-
})?;
900+
let image_identity = inspect.id.filter(|id| !id.trim().is_empty()).ok_or_else(
901+
|| {
902+
Status::failed_precondition(format!(
903+
"local container image '{image_ref}' inspect response has no image ID"
904+
))
905+
},
906+
)?;
908907
info!(
909908
image_ref = %image_ref,
910909
image_identity = %image_identity,
911-
"vm driver: resolved image from local Docker daemon"
910+
"vm driver: resolved image from local container engine"
912911
);
913-
Ok(Some((docker, image_identity)))
912+
Ok(Some((engine, image_identity)))
914913
}
915914
Err(err) if is_docker_not_found_error(&err) && required_local_image => {
916915
Err(Status::failed_precondition(format!(
917-
"locally built sandbox image '{image_ref}' is not present in the local Docker daemon"
916+
"locally built sandbox image '{image_ref}' is not present in the local container engine"
918917
)))
919918
}
920919
Err(err) if is_docker_not_found_error(&err) => Ok(None),
@@ -925,7 +924,7 @@ impl VmDriver {
925924
warn!(
926925
image_ref = %image_ref,
927926
error = %err,
928-
"vm driver: local Docker image inspection failed, falling back to registry"
927+
"vm driver: local container image inspection failed, falling back to registry"
929928
);
930929
Ok(None)
931930
}
@@ -1517,11 +1516,60 @@ fn parse_registry_reference(image_ref: &str) -> Result<Reference, Status> {
15171516
})
15181517
}
15191518

1519+
/// Try to connect to a local container engine (Docker or Podman).
1520+
///
1521+
/// Tries Docker first (`connect_with_local_defaults`, which respects
1522+
/// `DOCKER_HOST`). If Docker is unavailable, falls back to the Podman
1523+
/// socket, which exposes a Docker-compatible API.
1524+
async fn connect_local_container_engine() -> Option<Docker> {
1525+
if let Ok(docker) = Docker::connect_with_local_defaults() {
1526+
if docker.ping().await.is_ok() {
1527+
return Some(docker);
1528+
}
1529+
}
1530+
1531+
let podman_socket = podman_socket_path();
1532+
if podman_socket.exists() {
1533+
if let Ok(docker) =
1534+
Docker::connect_with_unix(podman_socket.to_str()?, 120, bollard::API_DEFAULT_VERSION)
1535+
{
1536+
if docker.ping().await.is_ok() {
1537+
info!(
1538+
socket = %podman_socket.display(),
1539+
"vm driver: connected to Podman (Docker-compatible API)"
1540+
);
1541+
return Some(docker);
1542+
}
1543+
}
1544+
}
1545+
1546+
None
1547+
}
1548+
1549+
/// Podman user socket path for the current platform.
1550+
fn podman_socket_path() -> PathBuf {
1551+
#[cfg(target_os = "macos")]
1552+
{
1553+
let home = std::env::var("HOME").unwrap_or_default();
1554+
PathBuf::from(home).join(".local/share/containers/podman/machine/podman.sock")
1555+
}
1556+
#[cfg(target_os = "linux")]
1557+
{
1558+
std::env::var("XDG_RUNTIME_DIR").map_or_else(
1559+
|_| {
1560+
let uid = nix::unistd::getuid();
1561+
PathBuf::from(format!("/run/user/{uid}/podman/podman.sock"))
1562+
},
1563+
|xdg| PathBuf::from(xdg).join("podman/podman.sock"),
1564+
)
1565+
}
1566+
}
1567+
15201568
fn is_openshell_local_build_image_ref(image_ref: &str) -> bool {
15211569
image_ref.starts_with("openshell/sandbox-from:")
15221570
}
15231571

1524-
fn local_docker_image_platform_mismatch(
1572+
fn local_image_platform_mismatch(
15251573
image_ref: &str,
15261574
actual_os: Option<&str>,
15271575
actual_arch: Option<&str>,
@@ -2918,17 +2966,17 @@ mod tests {
29182966
}
29192967

29202968
#[test]
2921-
fn local_docker_image_platform_mismatch_checks_guest_platform() {
2969+
fn local_image_platform_mismatch_checks_guest_platform() {
29222970
assert!(
2923-
local_docker_image_platform_mismatch(
2971+
local_image_platform_mismatch(
29242972
"openshell/sandbox-from:123",
29252973
Some("linux"),
29262974
Some(linux_oci_arch()),
29272975
)
29282976
.is_none()
29292977
);
29302978

2931-
let err = local_docker_image_platform_mismatch(
2979+
let err = local_image_platform_mismatch(
29322980
"openshell/sandbox-from:123",
29332981
Some("linux"),
29342982
Some("wrong-arch"),
@@ -2937,7 +2985,7 @@ mod tests {
29372985
assert!(err.contains("wrong-arch"));
29382986
assert!(err.contains(linux_oci_arch()));
29392987

2940-
let err = local_docker_image_platform_mismatch("openshell/sandbox-from:123", None, None)
2988+
let err = local_image_platform_mismatch("openshell/sandbox-from:123", None, None)
29412989
.expect("unknown platform should be reported");
29422990
assert!(err.contains("unknown/unknown"));
29432991
}

‎docs/reference/sandbox-compute-drivers.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,14 @@ For a service, set `OPENSHELL_DRIVERS=vm` in the service environment file and re
104104

105105
The gateway starts `openshell-driver-vm` over a private Unix socket and passes its process ID so the driver can reject unexpected local clients. The driver's standalone TCP listener is disabled unless `--allow-unauthenticated-tcp` is set for local development.
106106

107+
### Local image resolution
108+
109+
The VM driver resolves sandbox images from a local container engine before falling back to registry pulls. It tries Docker first, then falls back to the Podman socket (Docker-compatible API). On Linux with Podman, enable the API socket so the driver can find local images:
110+
111+
```shell
112+
systemctl --user start podman.socket
113+
```
114+
107115
## Kubernetes Driver
108116

109117
Kubernetes-backed sandboxes run as pods in the configured sandbox namespace. Use Kubernetes for shared clusters, remote compute, GPU scheduling, and operator-managed environments.

0 commit comments

Comments
 (0)