NVIDIA GPU passthrough to an Edera zone

6 min read · Intermediate

Developer Platform Engineer

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

Getting Started

  1. Edera must be successfully installed. See our installation guides, which should also include making sure you have access to the Edera image registry.

  2. Find the GPUs on your host.

    Supported GPUs, like the Tesla, should show up in the output of lspci:

    sudo lspci -Dknn -d ::03xx

    Example output:

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

    Make note of the PCI ids at the front (like 0000:18:00.0) for the next step.

  3. Add your GPUs to the Protect demon’s config file.

    This tells Edera which GPUs are available for passthrough and names them:

    # /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. Although we only show one GPU here, if you have multiple GPUs you will need a block for each GPU you want to pass through and each will need a unique name. We recommend numbering them gpu0, gpu1, gpu2 and so on, but you can choose any name here (for example testcard, leftcard), but it must be unique and must match the name used later in your launch commands.

  4. Optionally check the nvidia kernel variant defined in the daemon config file.

    By default each Edera release ships an nvidia kernel variant, which is pre-defined in the daemon config file. This lets you launch a zone with --kernel-variant nvidia and Edera will resolve the correct images for you. Typically you shouldn’t need to modify this, but if you do see Selecting a zone kernel with variants for more details.

    # /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"

  5. Restart the Protect daemon and verify.

    If you made any changes to the daemon.toml file, restart the daemon (sudo systemctl restart protect-daemon).

    If you changed the kernel variant configs, confirm the variant is resolvable with sudo protect image list-kernel-variants.

  6. Additional Steps if using KVM

ℹ️
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. Ensure that no other driver has grabbed the GPU:

    Similar to above, run sudo lspci -Dknn -d ::03xx and locate the GPUs. They should still not display a Kernel driver in use: field. Make note of the PCI Vendor and Device ids that look like [10de:1eb8] for use in the next step.

  2. Configure module parameters for the VFIO kernel modules:

    Use the PCI vendor and device IDs for the card from the previous step. You don’t need to list the IDs for ‘Subsystems’. If you need to support multiple PCI 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 -d ::03xx
    ...
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: This is the name you gave the GPU in the daemon.toml file as pci.devices.gpu0
  • --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