NVIDIA GPU passthrough to an Edera zone

5 min read · Intermediate

Developer Platform Engineer

This guide shows how to passthrough an NVIDIA GPU to an Edera zone using protect and run a GPU-accelerated workload inside the zone.

Prerequisites

  1. Edera is successfully installed. If necessary, follow our installation guides.

  2. You have an NVIDIA GPU on your system.

    Check GPU presence:

    sudo lspci -Dnn | grep "NVIDIA"

    Expected output:

    0000:18:00.0 3D controller [0302]: NVIDIA Corporation TU104GL [Tesla T4] [10de:1eb8] (rev a1)

  3. You’ll need to define the GPU in your daemon config file. This configuration tells Edera which GPUs are available for passthrough:

    # /var/lib/edera/protect/daemon.toml

[pci.devices]
[pci.devices.gpu0]
locations = [
  "0000:18:00.0",
]
permissive = true
msi_translate = false
power_management = true
rdm_reserve_policy = "relaxed"

    The key gpu0 is the primary identifier for the GPU in Edera. It links the physical device to the zone and workload later via --device gpu0. You can choose any unique name here (for example gpu1), but it must not be duplicated and must match the name used in your launch commands.

  4. Ensure that the daemon config file contains a [zone.kernel-variants] section that defines the nvidia kernel OCI image to be used. This entry is added by default starting with Edera v1.11.

    # /var/lib/edera/protect/daemon.toml

[zone.kernel-variants]
nvidia = "ghcr.io/edera-dev/zone-nvidiagpu-kernel:6.18.38-nvidia-610.43.02@sha256:dc968f8664d41abb75e44aa7bb3eb12e02d928c1358e5f1a8435c51d1d30f239"

KVM-specific setup

ℹ️
GPU passthrough for KVM is supported starting with Edera v1.11.0.

When using GPU passthrough with KVM as the hypervisor, the GPU must first be bound to the VFIO driver before Edera can attach it to a zone.

  1. Confirm that the GPU is not currently bound to any driver on the host system.

    sudo lspci -Dknn

    Expected output:

    ...
0000:18:00.0 3D controller [0302]: NVIDIA Corporation TU104GL [Tesla T4] [10de:1eb8] (rev a1)
    Subsystem: NVIDIA Corporation Device [10de:12a2]
0000:19:00.0 3D controller [0302]: NVIDIA Corporation TU104GL [Tesla T4] [10de:1eb8] (rev a1)
    Subsystem: NVIDIA Corporation Device [10de:12a2]
...

    There should be no Kernel driver in use: field.

    Take note of the PCI vendor and device ID, in this case 10de:1eb8.

  2. Configure module parameters for the VFIO kernel modules.

    Use the PCI vendor and device IDs from the previous step. If you need to support multiple IDs, separate them by commas.

    # /etc/modprobe.d/gpu-vfio.conf (new file)

options vfio_iommu_type1 allow_unsafe_interrupts
options vfio_pci ids=10de:1eb8

  3. Enable automatic loading of the VFIO kernel modules on boot:

    # /etc/modules-load.d/gpu-vfio.conf (new file)

vfio_iommu_type1
vfio_pci

  4. Reboot the system or (re-)load the VFIO kernel modules:

    sudo modprobe -r vfio_pci
sudo modprobe -r vfio_iommu_type1
sudo modprobe vfio_iommu_type1
sudo modprobe vfio_pci

  5. Confirm that the GPUs are successfully bound to the vfio-pci driver:

    sudo lspci -Dknn

    Expected output:

    ...
0000:18:00.0 3D controller [0302]: NVIDIA Corporation TU104GL [Tesla T4] [10de:1eb8] (rev a1)
    Subsystem: NVIDIA Corporation Device [10de:12a2]
    Kernel driver in use: vfio-pci
0000:19:00.0 3D controller [0302]: NVIDIA Corporation TU104GL [Tesla T4] [10de:1eb8] (rev a1)
    Subsystem: NVIDIA Corporation Device [10de:12a2]
    Kernel driver in use: vfio-pci
...

Launch a zone with NVIDIA GPU passthrough 

sudo protect zone launch --name zone-gpu \
  --device gpu0 \
  --kernel-verbose \
  --target-memory 2048 \
  --resource-adjustment-policy static \
  --kernel-variant nvidia \
  --pull-overwrite-cache

Explanation:

  • --name zone-gpu: name of the zone
  • --device gpu0: maps to pci.devices.gpu0 which is the requested device for the zone.
  • --target-memory 2048: allocates 2 GiB memory to the zone
  • --resource-adjustment-policy static: prevents zone RAM from being dynamically resized
  • --kernel-variant nvidia: use the kernel image variant which includes NVIDIA drivers for the zone
  • --pull-overwrite-cache: overwrite image cache on pull

Check that the zone launched successfully:

sudo protect zone list

Expected output:

| name     | uuid                                  | state | ipv4         | ipv6                         |
|----------|---------------------------------------|-------|--------------|------------------------------|
| zone-gpu | 994d83fd-dc41-4b6d-98a9-6a89ad9b45cf  | ready | 10.75.0.2/16 | fdd4:1476:6c7e::2/48         |

Confirm the NVIDIA driver is loaded

Check the zone logs:

sudo protect zone logs zone-gpu

Expected output:

[2026-07-16T16:32:21.011030Z INFO  edera_protect_zone::hooks] running setup hook: load modules [nvidia, nvidia_drm, nvidia_uvm] and execute [/usr/bin/nvidia-smi, -pm, 1]
[    1.403876] nvidia: loading out-of-tree module taints kernel.
[    1.515369] nvidia-nvlink: Nvlink Core is being initialized, major device number 239
[    1.516039] 
[    1.568563] NVRM: loading NVIDIA UNIX Open Kernel Module for x86_64  610.43.02  Release Build  (build@01c4f9ab348e)  Mon Jul 13 01:02:13 UTC 2026
[    1.619087] nvidia-modeset: Loading NVIDIA UNIX Open Kernel Mode Setting Driver for x86_64  610.43.02  Release Build  (build@01c4f9ab348e)  Mon Jul 13 01:02:08 UTC 2026
[    1.676402] [drm] [nvidia-drm] [GPU ID 0x00000007] Loading driver
[    3.362604] [drm] Initialized nvidia-drm 0.0.0 for 0000:00:07.0 on minor 0

Run a GPU workload

Launch a workload with the NVIDIA GPU:

sudo protect workload launch --name workload-gpu \
  --zone zone-gpu \
  --privileged \
  nvidia/cuda:13.3.0-devel-ubuntu26.04 -- /bin/bash

Check it’s running:

sudo protect workload list

Expected output:

| name          | uuid                                   | zone                                   | state   |
|---------------|----------------------------------------|----------------------------------------|---------|
| workload-gpu  | dcb4944a-9bd9-4f22-b075-a22e3ceb0fd0   | 994d83fd-dc41-4b6d-98a9-6a89ad9b45cf   | running |

Verify that the GPU is visible to the workload and has the nvidia driver loaded:

sudo protect workload exec workload-gpu -- \
  /bin/bash -c 'DEBIAN_FRONTEND=noninteractive && apt-get update && apt-get install -y pciutils && lspci -Dknn'

Expected output:

...
0000:00:07.0 3D controller [0302]: NVIDIA Corporation TU104GL [Tesla T4] [10de:1eb8] (rev a1)
    Subsystem: NVIDIA Corporation Device [10de:12a2]
    Kernel driver in use: nvidia
...

Verify GPU access via nvidia-smi:

sudo protect workload exec workload-gpu nvidia-smi

Expected output:

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 610.43.02              KMD Version: 610.43.02     CUDA UMD Version: 13.3     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  Tesla T4                       On  |   00000000:00:07.0 Off |                    0 |
| N/A   32C    P8             11W /   70W |       0MiB /  15360MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

Success. We’ve configured the GPU and have launched a workload in an isolated zone.

Cleanup 

sudo protect workload destroy workload-gpu
sudo protect zone destroy zone-gpu

Next steps

You’ve successfully launched an NVIDIA GPU-enabled Edera zone. You can now run secure, high-performance AI workloads in hardened zones with native driver support.

See also

Last updated on