NVIDIA / NVIDIA/OpenShell

feat: move Kubernetes-native template resources to driver config

Open
#3,035 0 comments 0 reactions 1 assignee View on GitHub

@elezar is already working on this.

Since Sep 15, 2026.

area:compute area:docs area:sdk state:triage-needed
Dominant language
Rust
Stars
8.7k
Forks
1.3k
Avg merge
2d 11h
Merged PRs (30d)
253

Description

User Story

As an OpenShell API or SDK user targeting Kubernetes, I want Kubernetes-native resource settings to live in Kubernetes driver configuration, so that portable sandbox resources have one typed API and backend-specific settings are explicit.

Problem Statement

SandboxTemplate.resources is a public free-form Struct that now has mixed semantics. CPU and memory are being moved to typed portable resource requirements, while the remaining Kubernetes-native resource keys are translated through gateway platform config and consumed only by the Kubernetes driver. Docker and VM reject that translated config, and Podman/MXC do not consume it.

Impact / Why This Matters

Users cannot tell from the public template shape which resource fields are portable and which apply only to Kubernetes. The current field also leaves a legacy API surface with ambiguous validation and merge behavior. The workaround is to know the gateway translation details; that is not a stable SDK contract.

Proposed Design

Move Kubernetes-native container resources to the Kubernetes-specific driver configuration. Keep portable GPU, CPU, and memory under typed workload resource requirements. Deprecate and then remove SandboxTemplate.resources, providing a clear migration error and documentation for callers that use Kubernetes-native resources.

Acceptance Criteria

  • Kubernetes driver configuration exposes an explicit agent-container resources shape for native Kubernetes resource keys.
  • Portable GPU, CPU, and memory continue to use typed resource requirements and are not duplicated in the Kubernetes-specific path.
  • Requests using SandboxTemplate.resources receive a clear migration error before the field is removed or reserved.
  • Kubernetes-native resource use cases, including extended resources, huge pages, and ephemeral storage, have documented driver-config equivalents.
  • Rust, Go, TypeScript, and Python SDK surfaces and published documentation reflect the migration.
  • Tests cover successful Kubernetes driver-config resources and rejection of the legacy field.

Alternatives Considered

Keep SandboxTemplate.resources as a platform-native escape hatch. This preserves a familiar Struct, but it leaves an ambiguous public API and a Kubernetes-only capability on the portable template surface.

Retain CPU and memory in SandboxTemplate.resources. This conflicts with #2838, which intentionally moves portable compute sizing to typed resource requirements.

Agent Investigation

Related to #2838. The gateway currently preserves non-CPU/non-memory entries from template.resources as resources_raw, and only the Kubernetes driver applies them to the workload container. This work belongs under #2565, the parent API-stabilization tracker.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.