Prepare a GPU Host
Install the physical GPU driver, container toolkit, and Docker integration before making GPUs available through STRATUM GPU Fabric.
Prepare a physical GPU host
On a worker with physical GPUs, STRATUM Host Manager → GPU lists detected devices and their operating mode. Prepare the host driver, container toolkit, and Docker integration before enabling a device as a shared GPU Fabric provider.
The procedure below is an NVIDIA + Ubuntu + Docker example. Select a driver branch supported by both the GPU and the host operating system. It is not a universal command sequence for AMD, Podman, or non-Ubuntu systems.
Choose how STRATUM uses each device
Host Manager supports a separate assignment for each GPU detected on the worker:
- GPU Fabric: offer the GPU as a shared accelerator resource to the STRATUM Continuum, so eligible VMs can attach a STRATUM GPU.
- Passthrough: bind the physical GPU to a VM running on this host. Host-driver and NVIDIA-container-toolkit requirements for GPU Fabric should not be confused with VFIO passthrough requirements.
- Host Only: leave the GPU under host control; STRATUM does not attach or share it.
The GPU Fabric checks are vendor-specific. A GPU assigned to Passthrough or Host Only does not need the NVIDIA Fabric runtime simply to retain that assignment.
Understand the Host Manager checks
For an NVIDIA GPU Fabric provider, the Host Manager GPU menu reports three prerequisites. A missing result tells you which layer to fix:
Driver: MISSING/NOT WORKING (nvidia-smi unavailable)
Toolkit: MISSING/NOT WORKING (nvidia-ctk unavailable)
Docker GPU integration: NOT READY (nvidia runtime not registered)Procedure: NVIDIA GPU Fabric provider
Identify your GPU and select the correct driver branch
Identify the GPU model and available Ubuntu server drivers. The Tesla P4 in this example is a Pascal GPU; R580 is its last supported NVIDIA driver branch. Do not choose R590/R595 or a -open kernel-module package for the P4. Other GPUs may require a different branch.
sudo apt update
sudo apt install -y ubuntu-drivers-common
# Identify the GPUs and see driver branches offered by Ubuntu
lspci -nn | grep -Ei 'NVIDIA|AMD|VGA|3D'
ubuntu-drivers list --gpgpu
# Example ONLY: Tesla P4 / Pascal on a supported Ubuntu release
sudo ubuntu-drivers install --gpgpu nvidia:580-server
sudo apt install -y nvidia-utils-580-server
sudo rebootUbuntu’s NVIDIA driver guide documents the --gpgpu flow; refer to the official GPU/driver compatibility matrix for the applicable branch.
Confirm the NVIDIA driver after reboot
nvidia-smi should list the Tesla P4 (or the installed NVIDIA GPU) and its driver version. Check which kernel driver owns the GPU; 83:00.0 is an example PCI address and must be replaced with your GPU’s address.
nvidia-smi
# Replace 83:00.0 with the BDF shown by lspci
lspci -nnk -s 83:00.0
# Expected for the NVIDIA driver:
# Kernel driver in use: nvidiaIf the GPU is bound to nouveau, resolve the conflicting driver and, if required, blacklist nouveau and rebuild initramfs following your distribution’s instructions. Reboot and confirm Kernel driver in use: nvidia before proceeding.
Install the NVIDIA Container Toolkit
Add NVIDIA’s signed container-toolkit repository and install the toolkit. This provides nvidia-ctk, NVIDIA’s container runtime, and the host-to-container GPU integration libraries. You do not need the full CUDA development toolkit just to expose GPUs to STRATUM.
sudo apt-get install -y ca-certificates curl gnupg
# NVIDIA repository signing key
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
| sudo gpg --dearmor -o \
/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
# NVIDIA stable repository
curl -fsSL \
https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
| sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
| sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
# Verify the toolkit command is installed
nvidia-ctk --versionOfficial instructions: Installing the NVIDIA Container Toolkit. Check the NVIDIA guide if the repository or supported installation command changes.
Register the NVIDIA runtime with Docker
nvidia-ctk updates /etc/docker/daemon.json to register the NVIDIA runtime. It should preserve other settings, such as a custom Docker data-root, but review the configuration before and after. Restarting Docker can interrupt existing containers, so perform this during a maintenance window.
# Recommended: back up an existing Docker daemon configuration
sudo test ! -f /etc/docker/daemon.json || \
sudo cp -a /etc/docker/daemon.json /etc/docker/daemon.json.before-nvidia
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
# Confirm Docker advertises NVIDIA as a runtime
docker info | grep -i runtimes
# Expected to include: nvidiaThe configured NVIDIA runtime does not need to become Docker’s default runtime. The verification command selects it explicitly.
Verify GPU access from inside a container
Before troubleshooting STRATUM, make sure an ordinary Docker container can see the GPU. The command downloads ubuntu:24.04 if it is not already available.
sudo docker run --rm \
--runtime=nvidia \
--gpus all \
ubuntu:24.04 nvidia-smiExpected result: an nvidia-smi table showing the physical GPU from inside the container. If this fails, correct the host driver and NVIDIA Docker runtime before continuing.
Recheck STRATUM GPU Fabric prerequisites
Return to stratum-host → GPU, refresh the device information if necessary, and confirm these readiness indicators for an NVIDIA GPU Fabric assignment:
NVIDIA GPU Fabric prerequisites:
Driver: READY
Toolkit: READY
Docker GPU integration: READYAssign each detected GPU to GPU Fabric, Passthrough, or Host Only as required, then save the configuration.
Recreate STRATUM after adding GPUs
Configuring NVIDIA on the host does not add GPU devices to a STRATUM container that was already created. If you add GPU support after STRATUM was installed, recreate the STRATUM container using the supported replacement procedure. This replaces the container without deleting the persistent datacenter state.
From the directory containing stratum-host, and after saving the GPU assignment in Host Manager:
sudo ./stratum-host stop
sudo ./stratum-host remove --yes
# Apply host configuration if GPU policy/settings changed
sudo ./stratum-host apply --yes
sudo ./stratum-host startFor the complete sequence, preservation behavior, or a new image release, see Update STRATUM →. Confirm Host Manager readiness again after the replacement, and verify the device appears in AI Accelerator Fabric.
The normal stratum-host remove --yes replacement procedure preserves durable STRATUM state in the configured persistent root. Do not delete the persistent root or remove the container directly with Docker as a substitute for Host Manager.
AMD, Podman, and other host platforms
For AMD hardware, use the AMD-supported kernel/compute driver stack and the setup requirements for the installed STRATUM release. nvidia-smi, nvidia-ctk, and the NVIDIA Docker runtime are NVIDIA-specific; do not run these NVIDIA commands for AMD devices. Confirm STRATUM GPU Fabric support for your specific AMD GPU before assigning it as a Fabric provider.
For Podman, container GPU exposure normally follows NVIDIA’s CDI workflow rather than the Docker runtime configuration shown above. Consult the NVIDIA Container Toolkit guide for the selected engine.
Passthrough is a different path: it also needs the appropriate device/IOMMU/VFIO host settings; installing the NVIDIA toolkit alone is not a passthrough setup.
The outcome you should see
Host Manager reports the NVIDIA GPU Fabric prerequisites as READY, Docker can run nvidia-smi in a container, and any newly assigned GPUs become available to STRATUM after container recreation.