Skip to content
Draft
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
5 changes: 3 additions & 2 deletions .packit.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,9 @@ actions:
# Uses git ls-files + tar instead of git archive so the tarball
# reflects any patching that Packit may have done (e.g. version bumps).
- 'bash -c "VERSION=${PACKIT_PROJECT_VERSION} && TMPDIR=$(mktemp -d) && DIR=openshell-${VERSION} && mkdir -p ${TMPDIR}/${DIR} && git ls-files -z | xargs -0 tar cf - | tar xf - -C ${TMPDIR}/${DIR}/ && tar -czf openshell-${VERSION}.tar.gz -C ${TMPDIR} ${DIR} && rm -rf ${TMPDIR}"'
# Step 2: Create vendored Cargo dependencies tarball for offline RPM build.
- 'bash -c "VERSION=${PACKIT_PROJECT_VERSION} && CARGO_HTTP_TIMEOUT=600 CARGO_NET_RETRY=5 cargo vendor --locked --quiet && tar -cJf openshell-${VERSION}-vendor.tar.xz vendor/ && rm -rf vendor/"'
# Step 2: Preserve Cargo source mappings, including pinned Git dependencies,
# with the vendored dependencies for the offline RPM build.
- 'bash -c "VERSION=${PACKIT_PROJECT_VERSION} && CARGO_HTTP_TIMEOUT=600 CARGO_NET_RETRY=5 cargo vendor --locked > cargo-vendor-config.toml && tar -cJf openshell-${VERSION}-vendor.tar.xz vendor/ cargo-vendor-config.toml && rm -rf vendor/ cargo-vendor-config.toml"'
# Step 3: Return the primary archive name. Packit expects create-archive
# to print one path for Source0; Source1 is patched explicitly below.
- 'bash -c "echo openshell-${PACKIT_PROJECT_VERSION}.tar.gz"'
Expand Down
47 changes: 46 additions & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ rustix = { version = "1.1", features = ["process"] }
socket2 = "0.6"

# Serialization
container-device-interface = { git = "https://github.com/cncf-tags/container-device-interface-rs", rev = "b3fec145b213afc4dfd6900c578edb42dc99e5df", default-features = false }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
jsonschema = { version = "=0.58.6", default-features = false }
Expand Down
4 changes: 3 additions & 1 deletion TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -341,7 +341,9 @@ hardware-free CDI devices and the host files they reference. The environment
tells the suite where its scenarios are with `OPENSHELL_TEST_CDI_SCENARIOS`, the
path of a document that names the device kind, each scenario and the checks it
expects. Any environment that creates matching devices and sets the variable
can run the suite. The expectations characterize the sandbox's behavior today,
can run the suite. A scenario can expect sandbox creation to fail with a given
report (`rejected`) and can be limited to some compute drivers (`drivers`). The
expectations characterize the sandbox's behavior today,
not a specification, and the `echo-socket` check needs `perl` in the workload
image, which the default image has.

Expand Down
3 changes: 3 additions & 0 deletions crates/openshell-core/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,9 @@ nix = { workspace = true }
rustix = { workspace = true }
libc = "0.2"

[target.'cfg(target_os = "linux")'.dependencies]
container-device-interface = { workspace = true }

[features]
default = ["telemetry"]
## Compile in anonymous telemetry emission support. On by default; disable with
Expand Down
7 changes: 7 additions & 0 deletions crates/openshell-core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,3 +104,10 @@ Use `openshell_core::proto_struct` when crossing between `serde_json` values and
`prost_types::{Struct, Value}`. Both conversion directions live in this module;
JSON-to-protobuf conversion is fallible so callers cannot silently replace an
unrepresentable number.

## CDI context

The shared `cdi` module defines the versioned context passed from compute drivers
to the workload, including selected devices and projected specification directories.
The CDI resolver and its dependency live in `openshell-sandbox`; see that crate's
README for resource validation and enforcement.
53 changes: 53 additions & 0 deletions crates/openshell-core/src/cdi.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

//! Shared CDI context schema.

use serde::{Deserialize, Serialize};

pub const CDI_CONTEXT_VERSION: u32 = 1;

/// Base workload-runtime path under which compute drivers mount CDI specification directories.
pub const CDI_SPEC_DIR_BASE: &str = "/.openshell/cdi-specs";

/// Return the workload-runtime path used for a CDI specification directory.
#[must_use]
pub fn cdi_spec_mount_path(index: usize) -> String {
format!("{CDI_SPEC_DIR_BASE}/{index}")
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CdiContext {
pub version: u32,
pub selected_devices: Vec<String>,
pub spec_dirs: Vec<CdiSpecDirectory>,
}

impl CdiContext {
#[must_use]
pub fn new(selected_devices: Vec<String>, spec_dirs: Vec<CdiSpecDirectory>) -> Self {
Self {
version: CDI_CONTEXT_VERSION,
selected_devices,
spec_dirs,
}
}
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CdiSpecDirectory {
pub path: String,
pub source: String,
}

impl CdiSpecDirectory {
#[must_use]
pub fn new(path: impl Into<String>, source: impl Into<String>) -> Self {
Self {
path: path.into(),
source: source.into(),
}
}
}
32 changes: 32 additions & 0 deletions crates/openshell-core/src/cdi_name.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

//! Portable CDI name checking for non-Linux targets.

/// Check `<vendor>/<class>=<name>` syntax without resolving or authorizing devices.
/// Input is neither trimmed nor normalized.
#[must_use]
pub fn is_qualified_name(device: &str) -> bool {
let Some((kind, name)) = device.split_once('=') else {
return false;
};
let Some((vendor, class)) = kind.split_once('/') else {
return false;
};
let valid_component = |value: &str, device_name: bool| {
let bytes = value.as_bytes();
bytes.first().is_some_and(|byte| {
if device_name {
byte.is_ascii_alphanumeric()
} else {
byte.is_ascii_alphabetic()
}
}) && bytes.last().is_some_and(u8::is_ascii_alphanumeric)
&& bytes.iter().all(|byte| {
byte.is_ascii_alphanumeric()
|| matches!(byte, b'_' | b'-' | b'.')
|| (device_name && *byte == b':')
})
};
valid_component(vendor, false) && valid_component(class, false) && valid_component(name, true)
}
32 changes: 4 additions & 28 deletions crates/openshell-core/src/gpu.rs
Original file line number Diff line number Diff line change
Expand Up @@ -302,39 +302,15 @@ fn cdi_nvidia_gpu_suffix(id: &str) -> Option<&str> {
id.strip_prefix(CDI_NVIDIA_GPU_PREFIX)
}

// Local equivalent of the upstream CDI parser until its public API is released:
// https://github.com/cncf-tags/container-device-interface-rs/pull/177
fn is_qualified_name(device: &str) -> bool {
let Some((kind, name)) = device.split_once('=') else {
return false;
};
let Some((vendor, class)) = kind.split_once('/') else {
return false;
};
let valid_component = |value: &str, device_name: bool| {
let bytes = value.as_bytes();
bytes.first().is_some_and(|byte| {
if device_name {
byte.is_ascii_alphanumeric()
} else {
byte.is_ascii_alphabetic()
}
}) && bytes.last().is_some_and(u8::is_ascii_alphanumeric)
&& bytes.iter().all(|byte| {
byte.is_ascii_alphanumeric()
|| matches!(byte, b'_' | b'-' | b'.')
|| (device_name && *byte == b':')
})
};
valid_component(vendor, false) && valid_component(class, false) && valid_component(name, true)
}

/// Validate vendor-agnostic CDI qualified names without resolving or authorizing devices.
///
/// # Errors
/// Returns an error for host paths or malformed `<vendor>/<class>=<name>` selectors.
pub fn validate_cdi_device_names(devices: &[String], field: &str) -> Result<(), String> {
if devices.iter().any(|device| !is_qualified_name(device)) {
if devices
.iter()
.any(|device| !crate::cdi_name::is_qualified_name(device))
{
return Err(format!(
"{field} must contain CDI qualified names (<vendor>/<class>=<name>)"
));
Expand Down
7 changes: 7 additions & 0 deletions crates/openshell-core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,14 @@
pub mod activity;
pub mod app_listener;
pub mod auth;
pub mod cdi;
pub mod compute;
#[cfg(target_os = "linux")]
pub mod cdi_name {
pub use container_device_interface::parser::is_qualified_name;
}
#[cfg(not(target_os = "linux"))]
pub mod cdi_name;
pub mod config;
pub mod container_paths;
pub mod denial;
Expand Down
37 changes: 36 additions & 1 deletion crates/openshell-driver-docker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,8 @@ traverse every parent and write and enter the workdir; OpenShell does not
change its ownership or mode.

Image `VOLUME` declarations and user mounts must not cover the workdir, one of
its parents, or the reserved `/.openshell` runtime/channel tree. OpenShell asks
its parents, or the reserved `/.openshell/channel` and `/.openshell/cdi-specs`
paths. OpenShell asks
the kernel to validate access under the final identity, so POSIX ACL and host
LSM decisions remain authoritative.

Expand All @@ -119,6 +120,7 @@ LSM decisions remain authoritative.
| Private named volumes | Separate volumes carry sandbox bootstrap keys, the runtime-initiated Unix socket, and supervisor-only credentials. The supervisor mounts bootstrap keys read-only and only the socket volume writable. |
| In-memory `/run/openshell-supervisor-ca` tmpfs | Holds only the public supervisor CA certificate and trust bundle without making all of `/run` writable. |
| CDI GPU request | Assigns the exact validated CDI devices requested by driver config or count-based selection. |
| CDI workload projection | For GPU sandboxes only, embeds selected device metadata in the protected boundary config and mounts Docker daemon CDI spec directories read-only into the workload. |

New containers dial the supervisor at `/.openshell/channel/control/supervisor/control.sock`.
The runtime remains the TLS/gRPC server; the supervisor verifies its pinned
Expand All @@ -138,6 +140,39 @@ Delete force-removes both containers, the driver-owned runtime volumes, and the
host-private runtime descriptor. Missing or altered descriptor and channel resources
fail closed; the driver does not run an older combined-supervisor layout.

## CDI GPU Metadata

Docker remains the source of truth for GPU injection. The driver selects opaque
CDI device IDs from `driver_config.cdi_devices` or the daemon's discovered CDI
inventory, then passes the same IDs to Docker with a CDI `DeviceRequest`.

For a GPU sandbox, the driver writes those IDs and projected CDI spec directory
paths to a versioned context in the protected workload boundary configuration.
It uses structured, read-only, non-recursive binds at `/.openshell/cdi-specs/<index>`.
The driver checks source existence on the daemon host using one temporary,
stopped container per directory and the prepared workload image. Each probe has
one read-only, private bind with source creation disabled. Successful probes are
removed with anonymous image-volume cleanup, including after provisioning
cancellation. Confirmed missing directories are omitted; other errors fail
provisioning. Results are cached for 30 seconds and refreshed on demand; observed
changes to daemon identity, configured directories, or GPU inventory invalidate
the cache. The resulting context records only available projections. The actual
sandbox is created once, and selected devices must still resolve from the
projected specs. No probe starts a process, creates missing directories, or
relabels host spec directories. Administrators must make the existing directories readable
under the host's SELinux policy when SELinux is enabled.

Whole spec directories are available to the trusted runtime, which resolves only
the selected devices. The mandatory Landlock baseline hides these projections
from agent processes, even when the authored policy grants a broad ancestor.
The sandbox runtime resolves the selected devices in that mount namespace before
it launches agent processes, derives Landlock paths from CDI `containerEdits`,
and warns when the runtime did not apply the spec's `additionalGids`. Containers with CDI context fail startup if their
selected devices cannot be resolved. Existing GPU containers without context
retain legacy baseline handling on restart. Admission checks persisted context
for existing containers and the creation context for new ones. Non-GPU sandboxes
receive no CDI context or spec mounts.

## Driver Config Mounts

The gateway forwards the `docker` block from `--driver-config-json`. Supported
Expand Down
Loading
Loading