Faire tourner de l'inférence ou du calcul GPU dans une instance Incus, sans dédier une machine entière : c'est exactement ce que permet le device gpu. Pour un conteneur, Incus partage le GPU de l'hôte et injecte l'userspace NVIDIA tout seul (rien à installer dans le conteneur) ; pour une VM, c'est un passthrough PCI exclusif. Ce guide montre les deux, avec le piège des versions de pilote. Testé avec un NVIDIA H100 sur Incus 7.0.
Ce que vous allez apprendre
Section intitulée « Ce que vous allez apprendre »- La différence conteneur (partage) vs VM (passthrough exclusif).
- Attacher un GPU NVIDIA à un conteneur avec
nvidia.runtime. - Filtrer le bon GPU sur une machine multi-cartes.
- Les pièges de version de pilote.
Prérequis
Section intitulée « Prérequis »- Un hôte avec un GPU NVIDIA et son pilote noyau installé (
nvidia-smifonctionne sur l'hôte). - Incus installé : voir installer Incus.
- Pour l'injection automatique en conteneur :
nvidia-container-toolkit(paquetlibnvidia-container) sur l'hôte.
Conteneur ou VM : deux mécanismes différents
Section intitulée « Conteneur ou VM : deux mécanismes différents »C'est le point à comprendre avant tout. Le device gpu ne fait pas la même chose selon le type d'instance.
| Type | Mécanisme | Partage | Pilote dans l'instance |
|---|---|---|---|
| Conteneur | Partage des périphériques /dev/nvidia* de l'hôte | Oui, plusieurs instances | Injecté par nvidia.runtime |
| VM | Passthrough PCI (VFIO) | Non, exclusif à la VM | À installer dans la VM |
Pour de l'inférence partagée entre plusieurs environnements, le conteneur est le plus souple. Pour une isolation forte ou un OS invité différent, la VM prend le GPU en exclusivité.
Passer un GPU à un conteneur
Section intitulée « Passer un GPU à un conteneur »L'élégance d'Incus : avec nvidia.runtime=true, il monte l'userspace NVIDIA de l'hôte (bibliothèques et nvidia-smi) dans le conteneur. Inutile d'installer le moindre paquet CUDA dedans.
-
Lancer un conteneur avec le runtime NVIDIA activé :
Fenêtre de terminal incus launch images:debian/13 gpu-lab -c nvidia.runtime=true -
Attacher le GPU avec un device de type
gpu:Fenêtre de terminal incus config device add gpu-lab gpu0 gpu# Device gpu0 added to gpu-lab -
Vérifier dans le conteneur, sans rien y installer :
Fenêtre de terminal incus exec gpu-lab -- nvidia-smi -LGPU 0: NVIDIA H100 PCIe (UUID: GPU-ada5ffa8-3c66-...)
Le GPU de l'hôte est vu tel quel dans le conteneur, avec les nœuds /dev/nvidia0 et /dev/nvidiactl exposés. Comme c'est un partage, plusieurs conteneurs peuvent recevoir le même GPU.
Cibler le bon GPU
Section intitulée « Cibler le bon GPU »Sur une machine à plusieurs cartes, le device gpu sans filtre expose toutes les cartes. On restreint avec des propriétés de filtrage.
# par identifiant de carteincus config device add gpu-lab gpu0 gpu id=0
# par adresse PCIincus config device add gpu-lab gpu0 gpu pci=0000:81:00.0On peut aussi filtrer par vendorid/productid. C'est indispensable pour dédier une carte précise à une instance et en laisser d'autres libres pour l'hôte ou d'autres instances.
GPU dans une machine virtuelle
Section intitulée « GPU dans une machine virtuelle »Pour une VM, le device gpu déclenche un passthrough PCI : la carte est détachée de l'hôte et rattachée à la VM, en exclusivité. L'hôte ne peut plus l'utiliser tant que la VM tourne.
incus launch images:debian/13 gpu-vm --vmincus config device add gpu-vm gpu0 gpuLe piège des versions de pilote
Section intitulée « Le piège des versions de pilote »Le problème le plus fréquent en conteneur : une incompatibilité de version entre le pilote noyau de l'hôte et l'userspace injecté. Comme nvidia.runtime monte l'userspace de l'hôte, les deux sont par construction alignés ici. En revanche, si vous installez manuellement des paquets NVIDIA dans le conteneur, ils peuvent entrer en conflit avec le pilote noyau de l'hôte (Failed to initialize NVML: Driver/library version mismatch). La règle : en conteneur, laisser nvidia.runtime gérer l'userspace, ne pas installer de pilote dedans.
À retenir
Section intitulée « À retenir »- Device
gpu: partage en conteneur, passthrough PCI exclusif en VM. - En conteneur,
nvidia.runtime=trueinjecte l'userspace NVIDIA : rien à installer dedans. - L'injection exige
libnvidia-container(nvidia-container-toolkit) sur l'hôte. - Cibler une carte précise avec
id=,pci=ouvendorid/productid. - En VM : pilote à installer dans l'invité, IOMMU requis sur l'hôte.
FAQ : questions fréquentes sur le GPU dans Incus
Section intitulée « FAQ : questions fréquentes sur le GPU dans Incus »nvidia.runtime + device gpu
incus launch images:debian/13 gpu-lab -c nvidia.runtime=true
incus config device add gpu-lab gpu0 gpu
incus exec gpu-lab -- nvidia-smi -L
nvidia.runtime=true, Incus monte l'userspace NVIDIA de l'hôte (bibliothèques et nvidia-smi) dans le conteneur : rien à installer dedans. Le device gpu expose /dev/nvidia0 et /dev/nvidiactl. Plusieurs conteneurs peuvent partager la même carte.Partage vs passthrough exclusif
| Type | Mécanisme | Partage | Pilote |
|---|---|---|---|
| Conteneur | Partage de /dev/nvidia* |
Oui | Injecté par nvidia.runtime |
| VM | Passthrough PCI (VFIO) | Non, exclusif | À installer dans l'invité |
intel_iommu=on / amd_iommu=on).Deux causes fréquentes
libnvidia-containerabsent sur l'hôte : l'injection parnvidia.runtimerepose sur ce paquet (fourni parnvidia-container-toolkit, le même que pour Docker). Sans lui, rien n'est monté etnvidia-smiéchoue.- Pilote installé à la main dans le conteneur : il entre en conflit avec le pilote noyau de l'hôte (
Failed to initialize NVML: Driver/library version mismatch).
nvidia.runtime gérer l'userspace, ne rien installer dedans.Filtrer le device gpu
# par identifiant de carte
incus config device add gpu-lab gpu0 gpu id=0
# par adresse PCI
incus config device add gpu-lab gpu0 gpu pci=0000:81:00.0
vendorid / productid. Sans filtre, le device gpu expose toutes les cartes. Le filtrage est indispensable pour dédier une carte à une instance et en laisser d'autres libres.