Skip to content

Commit 2ab2a61

Browse files
committed
feat(api)!: reuse resource requirements in workload templates
Align reusable workload templates with SandboxSpec by using the public ResourceRequirements message directly. Update SDK surfaces, generated bindings, CLI consumers, tests, and documentation. Part of #2838 Signed-off-by: Evan Lezar <[email protected]>
1 parent e77d152 commit 2ab2a61

28 files changed

Lines changed: 1294 additions & 1432 deletions

File tree

‎architecture/compute-runtimes.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -253,20 +253,21 @@ delete, reconciliation removes the row; otherwise it can remain `Deleting`.
253253
| 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. |
254254
| Extension | Out-of-tree drivers operated alongside the gateway. | Whatever boundary the driver implements. | Selected by a custom `compute_drivers = ["<name>"]` entry with `[openshell.drivers.<name>].socket_path`, or at launch time by pairing `--drivers <name>` with `--compute-driver-socket=<path>`. A launch-time endpoint may use a canonical built-in name to preserve its driver-config key while replacing in-process construction. The gateway connects to an operator-provisioned UDS, snapshots `GetCapabilities`, 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. |
255255

256-
Per-sandbox CPU and memory values currently enter the driver layer through
257-
template resource limits. Docker and Podman apply them as runtime limits.
258-
Kubernetes mirrors each limit into the matching request. VM accepts the fields
259-
but currently ignores them.
256+
Per-sandbox CPU, memory, and GPU requirements enter the driver layer through
257+
the typed `ResourceRequirements` message. Docker and Podman apply CPU and
258+
memory as runtime limits. Kubernetes mirrors each limit into the matching
259+
request. VM and MXC reject unsupported CPU and memory requirements instead of
260+
silently ignoring them.
260261

261262
Reusable sandbox workload templates are resolved before the compute-driver
262263
boundary. Drivers do not receive a separate template resource; the gateway
263264
lowers the selected `SandboxWorkloadTemplate` into the existing sandbox spec
264265
and validates that spec before calling `ValidateSandboxCreate` or
265-
`CreateSandbox`. Template CPU and memory become the same typed resource limits
266-
described above. Template GPU settings become `ResourceRequirements`, preserving
267-
the driver's default GPU assignment when the count is omitted. Template
268-
`driver_config` remains a driver-keyed envelope until the compute layer selects
269-
the active driver block and forwards only that block to the driver.
266+
`CreateSandbox`. `SandboxWorkloadConfig.resources` reuses the public
267+
`ResourceRequirements` message, so the gateway clones the typed requirements
268+
directly into the resolved sandbox spec. Template `driver_config` remains a
269+
driver-keyed envelope until the compute layer selects the active driver block
270+
and forwards only that block to the driver.
270271

271272
Docker and Podman also accept per-sandbox driver-config mounts for existing
272273
runtime-managed named volumes and tmpfs mounts. Podman additionally accepts

‎crates/openshell-cli/src/run.rs‎

Lines changed: 27 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ use openshell_core::proto::{
5555
ListSandboxPoliciesRequest, ListSandboxTemplatesRequest, ListSandboxesRequest,
5656
ListServicesRequest, MemoryResourceRequirements, PolicySource, PolicyStatus,
5757
RejectDraftChunkRequest, ResourceRequirements, RevokeSshSessionRequest, Sandbox, SandboxPhase,
58-
SandboxPolicy, SandboxResources, SandboxServiceLevel, SandboxSpec, SandboxStartup,
59-
SandboxTemplate, SandboxWorkloadConfig, SandboxWorkloadTemplate, SandboxWorkloadTemplateSpec,
58+
SandboxPolicy, SandboxServiceLevel, SandboxSpec, SandboxStartup, SandboxTemplate,
59+
SandboxWorkloadConfig, SandboxWorkloadTemplate, SandboxWorkloadTemplateSpec,
6060
ServiceEndpointResponse, SetInferenceRouteRequest, SettingScope, StartSandboxRequest,
6161
StopSandboxRequest, TcpForwardFrame, TcpForwardInit, TcpRelayTarget, UpdateConfigRequest,
6262
WatchSandboxRequest, exec_sandbox_event, tcp_forward_init,
@@ -2278,15 +2278,15 @@ pub async fn sandbox_template_create(
22782278
tls: &TlsOptions,
22792279
) -> Result<()> {
22802280
let resources = if cpu.is_some() || memory.is_some() || gpu_requirements.is_some() {
2281-
Some(SandboxResources {
2281+
Some(ResourceRequirements {
22822282
cpu: cpu
22832283
.map(validate_cpu_quantity)
22842284
.transpose()?
2285-
.unwrap_or_default(),
2285+
.map(|limit| CpuResourceRequirements { limit }),
22862286
memory: memory
22872287
.map(validate_memory_quantity)
22882288
.transpose()?
2289-
.unwrap_or_default(),
2289+
.map(|limit| MemoryResourceRequirements { limit }),
22902290
gpu: gpu_requirements,
22912291
})
22922292
} else {
@@ -2529,12 +2529,11 @@ fn sandbox_template_to_json(template: &SandboxWorkloadTemplate) -> serde_json::V
25292529
}
25302530
if let Some(resources) = &workload.resources {
25312531
let mut resources_json = serde_json::Map::new();
2532-
if !resources.cpu.is_empty() {
2533-
resources_json.insert("cpu".to_string(), serde_json::json!(resources.cpu));
2532+
if let Some(cpu) = &resources.cpu {
2533+
resources_json.insert("cpu".to_string(), serde_json::json!(cpu.limit));
25342534
}
2535-
if !resources.memory.is_empty() {
2536-
resources_json
2537-
.insert("memory".to_string(), serde_json::json!(resources.memory));
2535+
if let Some(memory) = &resources.memory {
2536+
resources_json.insert("memory".to_string(), serde_json::json!(memory.limit));
25382537
}
25392538
if let Some(gpu) = &resources.gpu {
25402539
let value = gpu
@@ -2631,12 +2630,17 @@ fn print_sandbox_template_detail(template: &SandboxWorkloadTemplate) {
26312630
println!(
26322631
" {} {}",
26332632
"CPU:".dimmed(),
2634-
non_empty_or(&resources.cpu, "<default>")
2633+
resources
2634+
.cpu
2635+
.as_ref()
2636+
.map_or("<default>", |cpu| non_empty_or(&cpu.limit, "<default>"))
26352637
);
26362638
println!(
26372639
" {} {}",
26382640
"Memory:".dimmed(),
2639-
non_empty_or(&resources.memory, "<default>")
2641+
resources.memory.as_ref().map_or("<default>", |memory| {
2642+
non_empty_or(&memory.limit, "<default>")
2643+
})
26402644
);
26412645
println!(
26422646
" {} {}",
@@ -2720,11 +2724,13 @@ fn print_sandbox_template_table(templates: &[SandboxWorkloadTemplate], show_work
27202724
for template in templates {
27212725
let resources = template_resources(template);
27222726
let cpu = resources
2723-
.map(|resources| resources.cpu.as_str())
2727+
.and_then(|resources| resources.cpu.as_ref())
2728+
.map(|cpu| cpu.limit.as_str())
27242729
.filter(|cpu| !cpu.is_empty())
27252730
.unwrap_or("-");
27262731
let memory = resources
2727-
.map(|resources| resources.memory.as_str())
2732+
.and_then(|resources| resources.memory.as_ref())
2733+
.map(|memory| memory.limit.as_str())
27282734
.filter(|memory| !memory.is_empty())
27292735
.unwrap_or("-");
27302736
let gpu = resources
@@ -2784,15 +2790,15 @@ fn template_image(template: &SandboxWorkloadTemplate) -> String {
27842790
)
27852791
}
27862792

2787-
fn template_resources(template: &SandboxWorkloadTemplate) -> Option<&SandboxResources> {
2793+
fn template_resources(template: &SandboxWorkloadTemplate) -> Option<&ResourceRequirements> {
27882794
template
27892795
.spec
27902796
.as_ref()
27912797
.and_then(|spec| spec.workload.as_ref())
27922798
.and_then(|workload| workload.resources.as_ref())
27932799
}
27942800

2795-
fn template_resources_gpu_display(resources: &SandboxResources) -> Option<String> {
2801+
fn template_resources_gpu_display(resources: &ResourceRequirements) -> Option<String> {
27962802
if let Some(gpu) = &resources.gpu {
27972803
return Some(
27982804
gpu.count
@@ -5915,10 +5921,9 @@ mod tests {
59155921
use openshell_core::proto::{
59165922
GetSandboxConfigResponse, GpuResourceRequirements, PolicySource, PolicyStatus,
59175923
ResourceRequirements, Sandbox, SandboxCondition, SandboxPhase, SandboxPolicy,
5918-
SandboxPolicyRevision, SandboxResources, SandboxStatus, SandboxWorkloadConfig,
5919-
SandboxWorkloadTemplate, SandboxWorkloadTemplateProvenance, SandboxWorkloadTemplateSpec,
5920-
ServiceEndpoint, ServiceEndpointResponse, WorkspaceMember, WorkspaceRole,
5921-
datamodel::v1::ObjectMeta,
5924+
SandboxPolicyRevision, SandboxStatus, SandboxWorkloadConfig, SandboxWorkloadTemplate,
5925+
SandboxWorkloadTemplateProvenance, SandboxWorkloadTemplateSpec, ServiceEndpoint,
5926+
ServiceEndpointResponse, WorkspaceMember, WorkspaceRole, datamodel::v1::ObjectMeta,
59225927
};
59235928

59245929
#[test]
@@ -6848,7 +6853,7 @@ mod tests {
68486853
let template = SandboxWorkloadTemplate {
68496854
spec: Some(SandboxWorkloadTemplateSpec {
68506855
workload: Some(SandboxWorkloadConfig {
6851-
resources: Some(SandboxResources {
6856+
resources: Some(ResourceRequirements {
68526857
gpu: Some(GpuResourceRequirements { count: None }),
68536858
..Default::default()
68546859
}),
@@ -6869,7 +6874,7 @@ mod tests {
68696874
let template = SandboxWorkloadTemplate {
68706875
spec: Some(SandboxWorkloadTemplateSpec {
68716876
workload: Some(SandboxWorkloadConfig {
6872-
resources: Some(SandboxResources {
6877+
resources: Some(ResourceRequirements {
68736878
gpu: Some(GpuResourceRequirements { count: Some(2) }),
68746879
..Default::default()
68756880
}),

‎crates/openshell-cli/tests/sandbox_create_lifecycle_integration.rs‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1777,8 +1777,17 @@ async fn sandbox_template_create_sends_workload_template_resource() {
17771777
.resources
17781778
.as_ref()
17791779
.expect("resources should be sent");
1780-
assert_eq!(resources.cpu, "2");
1781-
assert_eq!(resources.memory, "4Gi");
1780+
assert_eq!(
1781+
resources.cpu.as_ref().map(|cpu| cpu.limit.as_str()),
1782+
Some("2")
1783+
);
1784+
assert_eq!(
1785+
resources
1786+
.memory
1787+
.as_ref()
1788+
.map(|memory| memory.limit.as_str()),
1789+
Some("4Gi")
1790+
);
17821791
assert_eq!(resources.gpu.as_ref().and_then(|gpu| gpu.count), Some(1));
17831792
assert!(spec.driver_config.is_some());
17841793
let startup = spec

‎crates/openshell-sdk/README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,8 @@ with a discriminable kind.
5757

5858
```rust
5959
use openshell_sdk::{
60-
ClientConfig, OpenShellClient, SandboxTemplateCreateSpec,
60+
ClientConfig, CpuResourceRequirements, MemoryResourceRequirements, OpenShellClient,
61+
ResourceRequirements, SandboxTemplateCreateSpec,
6162
SandboxWorkloadConfig, SandboxWorkloadTemplate, SandboxWorkloadTemplateSpec,
6263
};
6364

@@ -72,6 +73,11 @@ client
7273
spec: Some(SandboxWorkloadTemplateSpec {
7374
workload: Some(SandboxWorkloadConfig {
7475
image: "ghcr.io/nvidia/openshell-community/sandboxes/python:latest".to_string(),
76+
resources: Some(ResourceRequirements {
77+
cpu: Some(CpuResourceRequirements { limit: "1".to_string() }),
78+
memory: Some(MemoryResourceRequirements { limit: "512Mi".to_string() }),
79+
..Default::default()
80+
}),
7581
..Default::default()
7682
}),
7783
..Default::default()

‎crates/openshell-sdk/src/lib.rs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,8 @@ pub use config::{AuthConfig, ClientConfig};
4747
pub use error::SdkError;
4848
pub use refresh::{Refresh, RefreshError, RefreshedToken, TokenSource};
4949
pub use types::{
50-
ExecOptions, ExecResult, Health, ListOptions, SandboxPhase, SandboxRef, SandboxResources,
50+
CpuResourceRequirements, ExecOptions, ExecResult, GpuResourceRequirements, Health, ListOptions,
51+
MemoryResourceRequirements, ResourceRequirements, SandboxPhase, SandboxRef,
5152
SandboxServiceLevel, SandboxSpec, SandboxStartup, SandboxTemplateCreateSpec,
5253
SandboxTemplateListOptions, SandboxWorkloadConfig, SandboxWorkloadTemplate,
5354
SandboxWorkloadTemplateProvenance, SandboxWorkloadTemplateSpec, ServiceStatus, WorkspaceRef,

‎crates/openshell-sdk/src/raw.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ pub use openshell_core::proto::{
2626
DeleteSandboxRequest, DeleteSandboxTemplateRequest, DeleteWorkspaceRequest, ExecSandboxRequest,
2727
GetSandboxRequest, GetSandboxTemplateRequest, GetWorkspaceRequest, HealthRequest,
2828
ListProvidersRequest, ListSandboxTemplatesRequest, ListSandboxesRequest, ListWorkspacesRequest,
29-
Sandbox, SandboxPhase as ProtoSandboxPhase, SandboxResources, SandboxServiceLevel,
29+
ResourceRequirements, Sandbox, SandboxPhase as ProtoSandboxPhase, SandboxServiceLevel,
3030
SandboxSpec as ProtoSandboxSpec, SandboxStartup, SandboxTemplate, SandboxTemplateResponse,
3131
SandboxWorkloadConfig, SandboxWorkloadTemplate, SandboxWorkloadTemplateProvenance,
3232
SandboxWorkloadTemplateSpec, ServiceStatus as ProtoServiceStatus, StartSandboxRequest,

‎crates/openshell-sdk/src/types.rs‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -149,8 +149,17 @@ pub type SandboxWorkloadTemplateSpec = proto::SandboxWorkloadTemplateSpec;
149149
/// Portable sandbox workload configuration for template-backed sandboxes.
150150
pub type SandboxWorkloadConfig = proto::SandboxWorkloadConfig;
151151

152-
/// Portable resource requirements for template-backed sandboxes.
153-
pub type SandboxResources = proto::SandboxResources;
152+
/// Portable resource requirements shared by inline and template-backed sandboxes.
153+
pub type ResourceRequirements = proto::ResourceRequirements;
154+
155+
/// CPU resource requirements for a sandbox workload.
156+
pub type CpuResourceRequirements = proto::CpuResourceRequirements;
157+
158+
/// Memory resource requirements for a sandbox workload.
159+
pub type MemoryResourceRequirements = proto::MemoryResourceRequirements;
160+
161+
/// GPU resource requirements for a sandbox workload.
162+
pub type GpuResourceRequirements = proto::GpuResourceRequirements;
154163

155164
/// Desired service level for sandboxes created from a template.
156165
pub type SandboxServiceLevel = proto::SandboxServiceLevel;

‎crates/openshell-sdk/tests/client_mock.rs‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -125,10 +125,14 @@ fn workload_template_proto(name: &str, workspace: &str) -> proto::SandboxWorkloa
125125
workload: Some(proto::SandboxWorkloadConfig {
126126
image: format!("ghcr.io/test/{name}:latest"),
127127
environment: HashMap::new(),
128-
resources: Some(proto::SandboxResources {
129-
cpu: "1".to_string(),
130-
memory: "512Mi".to_string(),
131-
..proto::SandboxResources::default()
128+
resources: Some(proto::ResourceRequirements {
129+
cpu: Some(proto::CpuResourceRequirements {
130+
limit: "1".to_string(),
131+
}),
132+
memory: Some(proto::MemoryResourceRequirements {
133+
limit: "512Mi".to_string(),
134+
}),
135+
..Default::default()
132136
}),
133137
}),
134138
driver_config: None,

0 commit comments

Comments
 (0)