GPU Passthrough for Virtual Machines

MetalSoft supports passing through physical GPU devices from VM pool hosts to individual virtual machines. This enables GPU-accelerated workloads such as AI/ML training, inference, graphics rendering and high-performance computing inside VMs with near-native GPU performance.

How it works

GPU passthrough in MetalSoft follows a three-level model:

1. VM Pool — physical GPUs on the hypervisor hosts are discovered and registered at the pool level
2. VM Type — defines how many GPUs (and of which model) a VM of this type requires
3. VM / VM Instance — individual VMs receive their assigned GPU devices based on the VM type

VM Pool (hosts with physical GPUs)
  └── VM Type (requires N x "GPU model")
        └── VM Instance (assigned specific GPU devices from host)

The system uses PCI passthrough to give the VM direct access to the GPU hardware, bypassing the hypervisor. This provides the same performance as running on bare metal.

Prerequisites

• The hypervisor hosts in the VM pool must have physical GPUs installed
• IOMMU (Intel VT-d or AMD-Vi) must be enabled in the BIOS of the hypervisor hosts
• The GPU must not be in use by the host operating system (no display driver attached)

Viewing GPUs in a VM Pool

When hosts with GPUs are added to a VM pool, the GPUs are automatically discovered and registered. You can view the registered GPUs on the VM pool.

Using the Admin UI

Navigate to VMs > VM Pool name > GPUs tab to see all GPUs registered in the pool.

Each GPU entry shows:

• Model — the GPU model name (e.g. GP104GL [Tesla P4])
• Vendor — the GPU vendor (e.g. NVIDIA Corporation)
• PCI Address — the PCI bus address of the device on the host

Using the API

GPUs are returned as part of the VM pool object in the gpus array:

curl "https://<your-server>/api/v2/vm-pools/{vmPoolId}"

Each entry in the gpus array contains:

Field	Description
id	Unique ID of the GPU registration
vmPoolId	The VM pool this GPU belongs to
model	GPU model name
vendor	GPU vendor
pciAddress	PCI bus address on the host

GPU information is also available in the VM pool statistics:

curl "https://<your-server>/api/v2/vm-pools/{vmPoolId}/statistics"

The gpuInfo array in the response shows aggregate GPU information across the pool.

Configuring GPU requirements on a VM Type

VM types define the resource constraints for virtual machines. To enable GPU passthrough, specify the GPU requirements when creating or editing a VM type.

Using the Admin UI

1. Navigate to VMs > VM Pool name > Virtual Machine Types tab
2. Click Add VM Type or edit an existing type
3. In the GPU section, specify:
   • GPU Name — the name of the GPU as it appears in the PCI device list (e.g. GP104GL [Tesla P4])
   • Count — the number of GPU units to assign to each VM of this type
4. Save the VM type

Using the API

curl -X POST "https://<your-server>/api/v2/vm-types" \
  -H "Content-Type: application/json" \
  -d '{
    "vmPoolId": 1,
    "name": "gpu-large",
    "cpuCores": 8,
    "ramGB": 32,
    "gpuInfo": [
      {
        "name": "GP104GL [Tesla P4]",
        "count": 2
      }
    ]
  }'

The gpuInfo array can contain multiple entries if the VM type requires different GPU models. Each entry specifies:

Field	Description
name	GPU name as it appears in the PCI device list. Must match a GPU registered in the VM pool.
count	Number of GPU units of this model to pass through to each VM.

GPU information on VMs and VM Instances

Once a VM is created from a GPU-enabled VM type, the assigned GPU devices are visible on the VM and VM instance objects.

VM level

curl "https://<your-server>/api/v2/vms/{vmId}"

The gpuInfo array on the VM shows the GPUs assigned to it:

Field	Description
name	GPU name
vendor	GPU vendor
pciAddress	PCI address of the specific GPU device assigned to this VM

VM Instance level

curl "https://<your-server>/api/v2/vm-instances/{vmInstanceId}"

The gpuInfo array on the VM instance reflects the GPU requirements from the VM type (name and count), which the scheduler uses to place the VM on a host with sufficient GPU resources.

GPU-aware placement

When deploying a VM with GPU requirements, the MetalSoft scheduler considers GPU availability during host placement:

• The scheduler selects a host that has enough available GPUs matching the requested model(s)
• GPUs that are already assigned to other VMs on the same host are excluded
• If no host has sufficient GPU resources, the deployment will fail with an appropriate error

During live migration, GPU passthrough VMs cannot be migrated to hosts that lack the required GPU resources. Ensure that multiple hosts in the pool have compatible GPUs if high availability is needed.

Related topics

• Managing VM Pools — registering VM pools and configuring VM types
• Managing VMs — creating and managing virtual machines