You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 532fa1b
Browse filesBrowse the repository at this point in the historyBrowse files
|`crates/openshell-isolation/`| Isolation backend contract | RFC 0012 `IsolationBackend` trait + types; the supervisor-facing runtime contract for the boundary |
36
+
|`crates/openshell-isolation-vm/`| VM isolation transport | Shared authenticated host/guest boundary transport and portable process leaf for VM drivers |
Copy file name to clipboardExpand all lines: architecture/compute-runtimes.md
+22-15Lines changed: 22 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,18 +1,20 @@
1
1
# Compute Runtimes
2
2
3
3
Compute runtimes create, stop, delete, and watch sandbox workloads for the
4
-
gateway. They do not replace sandbox policy enforcement. Every runtime starts a
5
-
workload that runs the `openshell-sandbox` supervisor, and the supervisor
6
-
enforces the sandbox contract locally.
4
+
gateway. They do not replace sandbox policy enforcement. Container runtimes run
5
+
the logical `openshell-sandbox` supervisor in the workload boundary. VM runtimes
6
+
may instead run it on the host and use an authenticated process leaf inside the
7
+
guest. In both placements the logical supervisor owns policy and the gateway
8
+
session.
7
9
8
10
## Driver Contract
9
11
10
12
Each runtime receives a sandbox spec from the gateway and is responsible for:
11
13
12
14
- Selecting the sandbox image.
13
-
- Injecting sandbox identity and gateway callback configuration.
14
-
- Supplying TLS or secret material for supervisor callbacks.
15
-
- Providing the supervisor binary or image in the workload.
15
+
- Injecting sandbox identity and the admitted topology descriptor.
16
+
- Supplying TLS or secret material only to the logical supervisor placement.
17
+
- Providing the logical supervisor and any boundary-local process leaf.
16
18
- Reporting lifecycle and platform events back to the gateway.
17
19
- Cleaning up runtime-owned resources.
18
20
@@ -119,7 +121,7 @@ delete, reconciliation removes the row; otherwise it can remain `Deleting`.
119
121
| Docker | Local development with Docker available. | Container plus nested sandbox namespace. | Uses host networking so loopback gateway endpoints work from the supervisor. |
120
122
| Podman | Rootless or single-machine deployments. | Container plus nested sandbox namespace. | Uses the Podman REST API, OCI image volumes, and CDI GPU devices when available. |
121
123
| Kubernetes | Cluster deployment through Helm. | Pod plus nested sandbox namespace. | Uses Kubernetes API objects, service accounts, secrets, PVC-backed workspace storage, and GPU resources. |
122
-
| VM | Experimental microVM isolation. | Per-sandbox libkrun VM. | Managed endpoint-backed driver. The gateway spawns `openshell-driver-vm`, waits for its Unix socket, and then consumes it through the same remote `compute_driver.proto` path used by unmanaged endpoint drivers. The VM driver boots a cached bootstrap `rootfs.ext4`, prepares requested OCI images inside a bootstrap VM with `umoci`, attaches the prepared image disk read-only, and gives each sandbox a writable `overlay.ext4` for merged-root changes and runtime material. The driver persists each accepted launch request beside the overlay and restarts those VMs on driver startup without recreating the overlay. |
124
+
| VM | Experimental host-supervised microVM isolation. | Per-sandbox libkrun VM with a portable guest process leaf. | Managed endpoint-backed driver. The gateway spawns `openshell-driver-vm`; the driver starts a native logical supervisor and connects it to the guest over authenticated virtio-vsock. The guest has no gateway credentials. The existing custom kernel, cached bootstrap `rootfs.ext4`, in-VM `umoci` preparation, read-only image disk, writable `overlay.ext4`, and restart persistence remain unchanged. |
123
125
| Extension | Out-of-tree drivers operated alongside the gateway. | Whatever boundary the driver implements. | Selected by a non-reserved custom `compute_drivers = ["<name>"]` entry with `[openshell.drivers.<name>].socket_path`, or at launch time by pairing `--drivers <name>` with `--compute-driver-socket=<path>`. Reserved built-in names such as `vm`, `docker`, `podman`, and `kubernetes` cannot be used as unmanaged socket endpoints. The gateway connects to a UDS the operator already provisioned, runs `GetCapabilities`, logs the advertised `driver_name`, and dispatches all sandbox lifecycle calls through `compute_driver.proto`. The driver process and socket lifecycle are operator-owned; the gateway does not spawn, supervise, or remove unmanaged extension drivers. The trust boundary is the socket's filesystem permissions: the operator must ensure only the gateway uid can read/write it. |
124
126
125
127
Per-sandbox CPU and memory values currently enter the driver layer through
@@ -159,25 +161,29 @@ Runtime-specific implementation notes belong in the driver crate README:
159
161
-`crates/openshell-driver-kubernetes/README.md`
160
162
-`crates/openshell-driver-vm/README.md`
161
163
162
-
The combined VM topology runs `openshell-sandbox` as guest PID 1. libkrun
163
-
executes the driver-owned guest bootstrap as PID 1, and the bootstrap preserves
164
-
that identity when it execs the supervisor after mounting and network setup.
164
+
The VM topology is delegated. libkrun executes the driver-owned guest bootstrap
165
+
as PID 1; after mounting and network setup it execs `openshell-sandbox vm-guest`
166
+
as the portable process leaf. The native host supervisor drives RFC 0012 over a
0 commit comments