docs: define beta support matrix by drew · Pull Request #2148 · NVIDIA/OpenShell

drew · 2026-07-06T16:03:55Z

Summary

Define the forward-looking OpenShell compatibility matrix for the beta milestone. This draft establishes the intended support contract and includes explicit TBD values where minimum versions are not yet finalized.

The initial minimum versions are deliberately provisional. They are reasonable starting points rather than fully validated support boundaries, and we will refine them as compatibility and release test infrastructure comes online.

Related Issue

None.

Changes

Reorganize the support matrix around platforms, clients, compute drivers, supervisor kernel requirements, Kubernetes distributions, and SDKs.
Document beta and stable API compatibility, deprecation, and breaking-change policies.
Reference established Kubernetes, Google AIP, Protobuf, and Buf compatibility guidance.

Testing

mise run pre-commit passes
Unit tests added/updated (documentation-only change)
E2E tests added/updated (not applicable)

Checklist

Follows Conventional Commits
Commits are signed off (DCO)
Architecture docs updated (not applicable)

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

copy-pr-bot · 2026-07-06T16:03:59Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

github-actions · 2026-07-06T16:04:22Z

🌿 Preview your docs: https://nvidia-preview-pr-2148.docs.buildwithfern.com/openshell

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

elezar · 2026-07-07T08:57:13Z

+
+| Release phase | Compatibility policy                                                                                                                                                                                                                                                                          |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Beta          | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release includes migration guidance and coordinated SDK updates.                                                      |


Suggested change

| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release includes migration guidance and coordinated SDK updates. |

| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in a preceding minor release. The release includes migration guidance and coordinated SDK updates. |

the the -> a change makes this a bit more flexible w.r.t. how long we can leave deprecated APIs active.

elezar · 2026-07-07T08:57:51Z

+| Release phase | Compatibility policy                                                                                                                                                                                                                                                                          |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Beta          | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release includes migration guidance and coordinated SDK updates.                                                      |
+| Stable        | Minor and patch releases are backward compatible within an API major version. Breaking changes use a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. |


Could you comment on where the specific time window came from?

elezar · 2026-07-07T09:00:39Z

-The gateway can manage sandboxes through several compute drivers.
+| Driver     | Supported hosts       | Minimum version                            | Requirements                                                                          |
+| ---------- | --------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
+| Docker     | macOS, Linux, Windows | 28.0.4 or later                            | Docker Engine or Docker Desktop.                                                      |


Did we need to distinguish between "Windows" and "WSL"?

elezar · 2026-07-07T09:03:50Z

-| Kubernetes | Supported through the [OpenShell Helm chart](https://github.com/NVIDIA/OpenShell/blob/main/deploy/helm/openshell/README.md). | Requires a Kubernetes cluster supplied by the operator. |
-| MicroVM | Supported for VM-backed sandboxes. | Uses the VM compute driver and libkrun-based runtime. |
+OpenShell supports NVIDIA GPU-backed sandboxes across compute drivers when the
+host or cluster exposes compatible devices. Any LTS CUDA release is supported,


Suggested change

host or cluster exposes compatible devices. Any LTS CUDA release is supported,

host or cluster exposes compatible devices through a supported mechanism. Any current CUDA driver is supported,

I don't want to get into the details here, but basically, we require that the host is configured with the GPU Driver AND the NVIDIA Container Toolkit or in the case of Kubernets, the GPU Device Plugin.

elezar · 2026-07-07T09:04:40Z

+| Docker         | Linux; Windows through WSL2 | NVIDIA CDI                | Docker CDI is enabled and NVIDIA devices are visible. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. |
+| Podman         | Linux; Windows through WSL2 | NVIDIA CDI                | NVIDIA CDI devices are visible to Podman. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device.             |
+| MicroVM        | Linux                       | QEMU/VFIO PCI passthrough | The host provides IOMMU and VFIO support, root privileges, and a compatible sandbox image. Each sandbox supports one GPU.                           |
+| Kubernetes     | Linux GPU nodes             | `nvidia.com/gpu`          | The NVIDIA device plugin or GPU Operator exposes allocatable GPU capacity, and the sandbox image includes the required user-space libraries.          |


Suggested change

| Kubernetes | Linux GPU nodes | `nvidia.com/gpu` | The NVIDIA device plugin or GPU Operator exposes allocatable GPU capacity, and the sandbox image includes the required user-space libraries. |

| Kubernetes | Linux GPU nodes | `nvidia.com/gpu` extended resources | The NVIDIA GPU Device Plugin (e.g. installed by the GPU Operator) exposes allocatable GPU capacity, and the sandbox image includes the required user-space libraries. |

elezar · 2026-07-07T09:05:05Z

-## Software Prerequisites
+| Compute driver | Supported environment       | Device interface          | Requirements and limits                                                                                                              |
+| -------------- | --------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Docker         | Linux; Windows through WSL2 | NVIDIA CDI                | Docker CDI is enabled and NVIDIA devices are visible. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. |


Suggested change

| Docker | Linux; Windows through WSL2 | NVIDIA CDI | Docker CDI is enabled and NVIDIA devices are visible. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. |

| Docker | Linux; Windows through WSL2 | NVIDIA CDI | Docker is CDI-enabled and NVIDIA devices are visible. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. |

docs: define beta support matrix

916f437

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

drew added 12 commits July 6, 2026 09:22

docs: clarify API compatibility wording

0c0e173

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: define client server validation

7ccf572

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: describe API capability discovery

aeaa330

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: reframe client server compatibility

c8952c8

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: split API compatibility policy

7362cf3

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

wip

2aa6627

docs: refine compatibility version floors

19a9862

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: introduce support matrix sections

258c9a2

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: make support matrix descriptive

1f88b3a

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: separate Linux runtime and kernel requirements

d246226

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: describe MicroVM Linux support by capability

5bf2d0f

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: simplify supervisor kernel versions

274e0a6

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

krishicks reviewed Jul 6, 2026

View reviewed changes

Comment thread docs/reference/support-matrix.mdx Outdated

drew added 4 commits July 6, 2026 12:16

docs: add GPU support matrix

2b462b9

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: address support matrix review feedback

87b4d69

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: move user namespace support into table

85dd7a5

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

docs: remove misplaced PID limit detail

4d36a5e

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

elezar reviewed Jul 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: define beta support matrix#2148

docs: define beta support matrix#2148
drew wants to merge 17 commits into
mainfrom
drew/support-matrix

drew commented Jul 6, 2026 •

edited

Loading

Uh oh!

copy-pr-bot Bot commented Jul 6, 2026

Uh oh!

github-actions Bot commented Jul 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elezar Jul 7, 2026

Uh oh!

elezar Jul 7, 2026

Uh oh!

elezar Jul 7, 2026

Uh oh!

elezar Jul 7, 2026

Uh oh!

elezar Jul 7, 2026

Uh oh!

elezar Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	\| Beta \| Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in the preceding minor release. The release includes migration guidance and coordinated SDK updates. \|
	\| Beta \| Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in a preceding minor release. The release includes migration guidance and coordinated SDK updates. \|

	host or cluster exposes compatible devices. Any LTS CUDA release is supported,
	host or cluster exposes compatible devices through a supported mechanism. Any current CUDA driver is supported,

	\| Kubernetes \| Linux GPU nodes \| `nvidia.com/gpu` \| The NVIDIA device plugin or GPU Operator exposes allocatable GPU capacity, and the sandbox image includes the required user-space libraries. \|
	\| Kubernetes \| Linux GPU nodes \| `nvidia.com/gpu` extended resources \| The NVIDIA GPU Device Plugin (e.g. installed by the GPU Operator) exposes allocatable GPU capacity, and the sandbox image includes the required user-space libraries. \|

	\| Docker \| Linux; Windows through WSL2 \| NVIDIA CDI \| Docker CDI is enabled and NVIDIA devices are visible. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. \|
	\| Docker \| Linux; Windows through WSL2 \| NVIDIA CDI \| Docker is CDI-enabled and NVIDIA devices are visible. Default and counted GPU requests are supported. WSL2 may expose all GPUs as one selectable device. \|

Uh oh!

Conversation

drew commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Testing

Checklist

Uh oh!

copy-pr-bot Bot commented Jul 6, 2026

Uh oh!

github-actions Bot commented Jul 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elezar Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

elezar Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

elezar Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

elezar Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

elezar Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

elezar Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

drew commented Jul 6, 2026 •

edited

Loading