GPU Host Device Management#

KubeVirt supports two paths for attaching GPU devices to VMs: the traditional device-plugin path (via GPU.DeviceName) and the newer Dynamic Resource Allocation (DRA) path (via GPU.ClaimRequest). Both paths converge in the hostdevice package inside virt-launcher, which translates GPU specs into libvirt HostDevice domain XML entries.

Package Layout#

API Types#

The GPU spec embeds ClaimRequest inline 3:

GPU
├── Name string
├── DeviceName string (device-plugin path)
├── *ClaimRequest (DRA path — embedded inline)
│ ├── ClaimName string
│ └── RequestName string
└── VirtualGPUOptions *VGPUOptions
    └── Display *VGPUDisplayOptions
        ├── Enabled *bool (nil = default true for MDEV; must be explicit for PCI)
        └── RamFB *FeatureState
            └── Enabled *bool

A GPU is considered DRA-managed when DeviceName == "" and ClaimRequest != nil 4. This is tested by drautil.IsGPUDRA(gpu).

DRA GPU Host-Device Creation#

CreateDRAGPUHostDevices is the entry point for DRA GPUs. For each DRA-flagged GPU it calls createHostDeviceForGPU, which resolves the device type by probing mdev UUID first, then PCI address 5:

1. MDEV (vGPU) — drautil.GetMDevUUIDForClaim succeeds → creates a HostDeviceMDev with type=mdev mode=subsystem model=vfio-pci and UUID address 6.
2. PCI passthrough — drautil.GetPCIAddressForClaim succeeds → creates a HostDevicePCI with managed=no 7.
3. Neither → error.

Both utility functions read KEP-5304 metadata files at the path formed from basePath and the VMI's resourceClaims 8.

After all devices are created, validateCreationOfDRAGPUDevices asserts that the count of DRA-flagged GPUs matches the count of created host devices.

Display / vGPU Options and Nil-Safety#

VGPUDisplayOptions uses *bool pointer fields for every optional setting, so every level of nesting must be nil-checked before dereferencing. Both the DRA and non-DRA code paths follow the same guard pattern, but the default behaviors differ by device type:

MDEV (vGPU)#

Display defaults to on unless explicitly disabled 9 10:

VirtualGPUOptions != nil AND Display != nil
  → displayEnabled := Display.Enabled
  → if displayEnabled == nil || *displayEnabled → set Display="on"
      → if Display.RamFB == nil || *Display.RamFB.Enabled → set RamFB="on"

If no GPU in the spec has VirtualGPUOptions.Display set at all, both DRA and non-DRA paths apply a global default of Display="on" RamFB="on" to the first MDEV device 11 12.

PCI (SR-IOV vGPU)#

Display is opt-in — it is set only when Display.Enabled is explicitly true 13. This was tightened in PR #18112 to prevent startup failures when VirtualGPUOptions is set on a physical GPU that does not support display output.

The three helper predicates encapsulating these nil-safe checks live in hostdev.go 14:

Feature Gates#

DRA GPU support is guarded by the GPUsWithDRA or HostDevicesWithDRA alpha feature gates 3. The ClaimRequest field should only be populated when one of these gates is enabled.

Key References#

• DRA GPU host device implementation — pkg/virt-launcher/virtwrap/device/hostdevice/dra/gpu_hostdev.go
• Core hostdevice creation + display helpers — pkg/virt-launcher/virtwrap/device/hostdevice/hostdev.go
• DRA utilities (IsGPUDRA, GetMDevUUIDForClaim, GetPCIAddressForClaim) — pkg/dra/utils.go
• API schema (GPU, VGPUOptions, VGPUDisplayOptions) — staging/src/kubevirt.io/api/core/v1/schema.go
• PR #18112 – vGPU display options for SR-IOV