Skip to content

Commit 8f3ab94

Browse files
committed
feat(rootfs): add rootfs provider boundary with containerd-backed provider
Adds openshell-rootfs, the rootfs provider boundary for compute drivers: a provider resolves an OCI image reference into provider-neutral PreparedRootfs mounts keyed by a per-sandbox key, and owns image resolution, acquisition, unpacking, and the lifetime of the backend resources realizing the root filesystem. ContainerdRootfsProvider is the first implementation, backed by a system-provided containerd used only for image pull/unpack and snapshot management via its Transfer/Images/Content/Snapshots/Leases services. containerd concepts (snapshots, chain IDs, leases) are fully encapsulated: prepare() pulls, resolves the OCI chain ID, prepares a per-sandbox writable snapshot protected from containerd's GC by a lease, and cleans up after itself on failure; release() removes the snapshot and lease at teardown. Keeping the containerd daemon behind this boundary (rather than in a compute driver's own contract) leaves room to swap in a daemonless provider, or converge the VM driver's image acquisition pipeline onto the same types, without redesigning the sandbox provisioner on top. Related: NVIDIA#2255 Signed-off-by: Eric Curtin <[email protected]>
1 parent 930f4bd commit 8f3ab94

6 files changed

Lines changed: 751 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
4646
| `crates/openshell-driver-podman/` | Podman compute driver | In-process `ComputeDriver` backend for local Podman sandbox containers |
4747
| `crates/openshell-driver-vm/` | VM compute driver | Standalone libkrun-backed `ComputeDriver` subprocess (embeds its own rootfs + runtime) |
4848
| `crates/openshell-nft-ruleset/` | nftables rulesets | Shared per-sandbox NAT + default-deny nftables ruleset generation used by compute drivers |
49+
| `crates/openshell-rootfs/` | Rootfs providers | Rootfs provider boundary for compute drivers; containerd-backed provider for image pull/unpack and snapshots |
4950
| `crates/openshell-prover/` | Policy prover | Policy verification and proof generation |
5051
| `crates/openshell-server-macros/` | Server macros | Compile-time helpers for gateway RPC authorization |
5152
| `crates/openshell-supervisor-middleware/` | Middleware runtime | Generic middleware registry, remote service integration, and chain execution |

‎Cargo.lock‎

Lines changed: 28 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎architecture/compute-runtimes.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,25 @@ owned task prevents cancellation from stranding a mutation. A gateway restart
5858
does not resume a persisted `Deleting` operation. If the backend completed the
5959
delete, reconciliation removes the row; otherwise it can remain `Deleting`.
6060

61+
## Rootfs Provisioning Boundary
62+
63+
Rootfs provisioning — resolving an OCI image reference into a root filesystem
64+
a sandbox can be launched from — is a provider concern, separate from sandbox
65+
provisioning (namespaces, cgroups, VM boot). `openshell-rootfs` defines that
66+
boundary: a provider produces provider-neutral `PreparedRootfs` mounts keyed
67+
by a per-sandbox key, and owns image resolution, acquisition, unpacking, and
68+
the lifetime of whatever backend resources realize the root filesystem.
69+
Backend concepts (containerd snapshots, leases, chain IDs) must stay behind
70+
the provider and out of the compute-driver contract, so a daemon-backed
71+
provider can be replaced by a daemonless one without redesigning the
72+
provisioner on top of it.
73+
74+
`ContainerdRootfsProvider` is the first implementation, backed by a
75+
system-provided containerd used only for image pull/unpack and snapshot
76+
management. The VM driver's image acquisition and ext4 materialization
77+
pipeline is the same boundary shape; converging it onto the shared types is
78+
tracked follow-up work.
79+
6180
## Runtime Summary
6281

6382
| Runtime | Best fit | Sandbox boundary | Notes |

‎crates/openshell-rootfs/Cargo.toml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
[package]
5+
name = "openshell-rootfs"
6+
description = "Rootfs provider boundary for OpenShell compute drivers, with a containerd-backed provider"
7+
version.workspace = true
8+
edition.workspace = true
9+
rust-version.workspace = true
10+
license.workspace = true
11+
repository.workspace = true
12+
13+
[lib]
14+
name = "openshell_rootfs"
15+
path = "src/lib.rs"
16+
17+
[dependencies]
18+
# containerd's own generated gRPC client. This is the "system-provided
19+
# containerd" integration point behind `ContainerdRootfsProvider`, used
20+
# only for image pull/unpack and snapshot management -- never bundled,
21+
# installed, or managed by OpenShell. containerd's container/task
22+
# services and shim are never used; consumers of a prepared rootfs (the
23+
# OCI compute driver) spawn the low-level OCI runtime themselves.
24+
containerd-client = "0.9"
25+
26+
futures = { workspace = true }
27+
serde_json = { workspace = true }
28+
sha2 = "0.10"
29+
thiserror = { workspace = true }
30+
tonic = { workspace = true, features = ["transport"] }
31+
32+
[lints]
33+
workspace = true

0 commit comments

Comments
 (0)