Cette note technique s'adresse aux ingénieurs qui ont besoin de GPU dans des conteneurs : équipes plateforme et MLOps, administrateurs Kubernetes, et toute personne à qui l'on confie un nouveau serveur GPU en lui demandant d'y faire fonctionner Docker. Elle explique ce que fait le NVIDIA Container Toolkit, comment l'installer sur les systèmes Debian, Ubuntu, de la famille RHEL et SUSE, comment configurer Docker, Docker rootless, containerd, nerdctl, CRI-O et Podman, comment le tester et ce qui peut mal tourner. Les commandes suivent le guide d'installation de NVIDIA pour la version 1.20.1 du toolkit, la version en vigueur au moment de la rédaction. Les explications, vérifications, conseils de dépannage et recommandations pour les parcs de machines sont les nôtres, issus de notre expérience d'assemblage et de support de serveurs GPU.
Sommaire
- Ce que fait le toolkit
- Avant de commencer
- Installation sur Ubuntu et Debian (apt)
- Installation sur RHEL, Rocky, Fedora et Amazon Linux (dnf)
- Installation sur openSUSE et SLES (zypper)
- Figer les versions et planifier les mises à niveau
- Configurer Docker
- Configurer Docker rootless
- Configurer containerd pour Kubernetes
- nerdctl
- Configurer CRI-O
- Podman et la Container Device Interface (CDI)
- Modifier en toute sécurité les paramètres du toolkit
- Tester l'accès au GPU dans un conteneur
- Dépannage
- Exploitation sur un parc de machines
- Comment Workstation peut vous aider
1. Ce que fait le toolkit
Une image de conteneur ne doit pas embarquer de pilote GPU. Le pilote est lié au module noyau de l'hôte, et une image construite pour une version de pilote ne fonctionnerait plus avec la suivante. Le NVIDIA Container Toolkit résout ce problème : lorsqu'un conteneur demande un GPU, le toolkit trouve les bibliothèques du pilote de l'hôte, les nœuds de périphériques et les utilitaires, tels que nvidia-smi, et les monte dans le conteneur juste avant son démarrage. L'image n'a besoin que des bibliothèques CUDA en espace utilisateur avec lesquelles l'application a été construite.
Le toolkit est un petit ensemble de paquets qui fonctionnent ensemble :
| Paquet ou outil | Rôle |
|---|---|
libnvidia-container1 et libnvidia-container-tools | La bibliothèque et la CLI qui trouvent les composants du pilote sur l'hôte et les mettent en place dans le conteneur. |
nvidia-container-toolkit-base | Le nvidia-container-runtime, une fine surcouche de runc (ou crun) qui ajoute la configuration GPU à la spécification du conteneur, et la commande nvidia-ctk. |
nvidia-container-toolkit | Le hook que les moteurs de conteneurs appellent au démarrage d'un conteneur, avec tous les éléments ci-dessus en dépendances. |
nvidia-ctk | La commande qui sert à configurer les moteurs de conteneurs, modifier les paramètres du toolkit et générer les spécifications CDI. |
Vous n'avez pas besoin du CUDA Toolkit sur l'hôte. L'hôte a besoin du pilote NVIDIA ; la version de CUDA réside dans l'image du conteneur. La seule règle est que le pilote de l'hôte doit être suffisamment récent pour la version de CUDA de l'image. Un pilote plus récent exécute les images construites pour des versions de CUDA plus anciennes.
2. Avant de commencer
- Une distribution prise en charge. NVIDIA publie la liste des plateformes prises en charge. En pratique : les versions actuelles d'Ubuntu LTS et de Debian, RHEL et ses recompilations (Rocky, AlmaLinux), Fedora, Amazon Linux, openSUSE et SLES, sur x86_64 ou arm64.
- Un pilote NVIDIA fonctionnel. Installez-le depuis le gestionnaire de paquets de votre distribution, comme le recommande NVIDIA, ou avec l'installateur
.runde NVIDIA. Vérifiez-le avant d'aller plus loin :
Si cette commande ne liste pas vos GPU, arrêtez-vous et corrigez d'abord le pilote. Le toolkit ne peut pas fonctionner sans lui. Sur les serveurs avec Secure Boot, le module noyau doit être signé, sinon le pilote s'installe mais ne se charge pas.$ nvidia-smi - Un moteur de conteneurs pour les étapes de configuration : Docker, containerd, CRI-O ou Podman. Vous pouvez installer le toolkit d'abord et le moteur ensuite.
- Un accès root ou sudo, et un accès HTTPS sortant vers
nvidia.github.io, ou un miroir local du dépôt de NVIDIA sur les sites isolés (air gap).
Un problème connu à anticiper. Sur les hôtes où le moteur de conteneurs utilise le pilote de cgroups systemd, l'exécution de systemctl daemon-reload peut faire perdre aux conteneurs en cours d'exécution l'accès à leurs GPU. Ils signalent alors Failed to initialize NVML: Unknown Error. Les mises à niveau de paquets déclenchent souvent un rechargement du démon ; ce problème apparaît donc généralement quelques jours après l'installation. Le guide de dépannage de NVIDIA le traite ; les correctifs habituels consistent à utiliser CDI (section 12) ou à créer les liens symboliques /dev/char dont les périphériques du pilote ont besoin :
$ sudo nvidia-ctk system create-dev-char-symlinks --create-all
3. Installation sur Ubuntu et Debian (apt)
Ces étapes fonctionnent sur la plupart des distributions dérivées de Debian.
Étape 1 : installer les outils nécessaires à la configuration du dépôt.
$ sudo apt-get update && sudo apt-get install -y --no-install-recommends \
ca-certificates curl gnupg2
Étape 2 : ajouter la clé de signature de NVIDIA et le dépôt de production. La clé est placée dans son propre trousseau et le dépôt y est restreint avec signed-by, de sorte que cette clé ne peut pas signer de paquets provenant d'un autre dépôt.
$ curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
| sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
$ curl -s -L 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
NVIDIA publie également un canal expérimental. Laissez-le désactivé sur les machines de production ; pour l'activer à des fins de test, décommentez-le :
$ sudo sed -i -e '/experimental/ s/^#//g' /etc/apt/sources.list.d/nvidia-container-toolkit.list
Étape 3 : actualiser les listes de paquets.
$ sudo apt-get update
Étape 4 : installer les quatre paquets dans une même version. Indiquer la version garantit que tous les hôtes d'un parc sont identiques et que les quatre paquets restent synchronisés entre eux.
$ export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.20.1-1
$ sudo apt-get install -y \
nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}
Vérifiez ce que vous avez installé :
$ nvidia-ctk --version
4. Installation sur RHEL, Rocky, Fedora et Amazon Linux (dnf)
Ces étapes fonctionnent sur la plupart des distributions basées sur RPM qui utilisent dnf.
Étape 1 : vérifier que curl est présent.
$ sudo dnf install -y curl
Étape 2 : ajouter le dépôt de production.
$ curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo \
| sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo
Pour essayer les paquets expérimentaux sur une machine de test :
$ sudo dnf config-manager --enable nvidia-container-toolkit-experimental
Étape 3 : installer les paquets dans une même version. Notez que dnf relie le nom et la version par un trait d'union, et non par un signe égal.
$ export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.20.1-1
$ sudo dnf install -y \
nvidia-container-toolkit-${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
nvidia-container-toolkit-base-${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
libnvidia-container-tools-${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
libnvidia-container1-${NVIDIA_CONTAINER_TOOLKIT_VERSION}
dnf vous demande d'accepter la clé de signature de NVIDIA la première fois. Vérifiez l'empreinte par rapport à la clé publiée par NVIDIA avant de l'accepter.
5. Installation sur openSUSE et SLES (zypper)
Étape 1 : ajouter le dépôt de production.
$ sudo zypper ar https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo
Pour essayer les paquets expérimentaux :
$ sudo zypper modifyrepo --enable nvidia-container-toolkit-experimental
Étape 2 : installer les paquets dans une même version.
$ export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.20.1-1
$ sudo zypper --gpg-auto-import-keys install -y \
nvidia-container-toolkit-${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
nvidia-container-toolkit-base-${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
libnvidia-container-tools-${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
libnvidia-container1-${NVIDIA_CONTAINER_TOOLKIT_VERSION}
--gpg-auto-import-keys accorde sa confiance à la clé du dépôt sans rien demander. Cela convient à l'automatisation ; sur un serveur isolé, vous préférerez peut-être importer et vérifier la clé manuellement d'abord.
6. Figer les versions et planifier les mises à niveau
Une mise à niveau automatique qui fait évoluer le toolkit, ou qui fait évoluer le pilote sans le toolkit, est une cause fréquente de conteneurs GPU qui tombent en panne pendant la nuit. Bloquez les paquets et mettez-les à niveau de manière délibérée :
| Distribution | Bloquer les paquets du toolkit |
|---|---|
| Ubuntu, Debian | sudo apt-mark hold nvidia-container-toolkit nvidia-container-toolkit-base libnvidia-container-tools libnvidia-container1 |
| Famille RHEL, Fedora | sudo dnf versionlock add nvidia-container-toolkit nvidia-container-toolkit-base libnvidia-container-tools libnvidia-container1 (nécessite le plugin versionlock) |
| openSUSE, SLES | sudo zypper addlock nvidia-container-toolkit nvidia-container-toolkit-base libnvidia-container-tools libnvidia-container1 |
Lors d'une mise à niveau, mettez à niveau les quatre paquets ensemble, d'abord sur un hôte de test, puis suivez l'ordre décrit à la section 16.
7. Configurer Docker
Étape 1 : enregistrer le runtime NVIDIA auprès de Docker.
$ sudo nvidia-ctk runtime configure --runtime=docker
Cette commande modifie /etc/docker/daemon.json et ajoute un runtime nvidia. Les paramètres existants du fichier sont conservés. Le résultat ressemble à ceci :
{
"runtimes": {
"nvidia": {
"args": [],
"path": "nvidia-container-runtime"
}
}
}
Étape 2 : redémarrer Docker.
$ sudo systemctl restart docker
Le redémarrage de Docker arrête les conteneurs en cours d'exécution, sauf si le live restore est activé ; faites-le donc pendant une fenêtre de maintenance sur un hôte chargé. Si vous gérez daemon.json avec un outil de gestion de configuration, ajoutez-y plutôt le runtime, sinon votre outil le supprimera lors de sa prochaine exécution.
L'option --gpus de Docker fonctionne dès que le runtime est enregistré. Si vous voulez que chaque conteneur utilise le runtime NVIDIA par défaut, par exemple sur un hôte GPU dédié, ajoutez --set-as-default à la commande de configuration.
8. Configurer Docker rootless
Docker rootless exécute le démon en tant qu'utilisateur ordinaire, avec son propre fichier de configuration. Trois étapes :
Étape 1 : enregistrer le runtime dans la configuration Docker de l'utilisateur (sans sudo) :
$ nvidia-ctk runtime configure --runtime=docker --config=$HOME/.config/docker/daemon.json
Étape 2 : redémarrer le démon Docker de l'utilisateur.
$ systemctl --user restart docker
Étape 3 : indiquer au toolkit de ne pas gérer les cgroups, ce qu'un démon rootless n'est pas autorisé à faire. Il s'agit d'un paramètre global à l'hôte, qui nécessite donc sudo :
$ sudo nvidia-ctk config --set nvidia-container-cli.no-cgroups --in-place
Ce paramètre affecte tous les moteurs de l'hôte. Ne l'appliquez pas sur un hôte qui exécute aussi des conteneurs rootful dépendant du toolkit pour la configuration des cgroups.
9. Configurer containerd pour Kubernetes
Étape 1 : enregistrer le runtime auprès de containerd.
$ sudo nvidia-ctk runtime configure --runtime=containerd
Par défaut, cette commande écrit un fichier de configuration complémentaire (drop-in), /etc/containerd/conf.d/99-nvidia.toml, et l'ajoute à la liste imports de /etc/containerd/config.toml, en créant ce fichier s'il n'existe pas. Conserver les paramètres NVIDIA dans un drop-in permet à votre propre config.toml de rester lisible et rend la modification facile à retirer.
Étape 2 : redémarrer containerd.
$ sudo systemctl restart containerd
Kubernetes doit ensuite avoir connaissance des GPU. La plupart des clusters utilisent le NVIDIA GPU Operator, qui peut installer pour vous le toolkit et le device plugin, ou bien le NVIDIA device plugin seul. Les pods sélectionnent le runtime via une RuntimeClass nommée nvidia, ou l'utilisent par défaut si vous l'avez défini comme runtime par défaut de containerd. Si vous utilisez le GPU Operator avec son toolkit intégré, n'installez pas en plus le toolkit manuellement sur les nœuds, sinon les deux se disputeront la même configuration.
Les distributions qui embarquent leur propre containerd, comme k3s et RKE2, conservent sa configuration à un autre emplacement et détectent souvent automatiquement le runtime NVIDIA. Suivez leur documentation GPU plutôt que de modifier /etc/containerd.
10. nerdctl
nerdctl, la ligne de commande de style Docker pour containerd, ne nécessite aucune configuration. Une fois le toolkit installé, nerdctl run --gpus=all fonctionne avec ou sans root. Vous n'avez pas besoin de la configuration containerd de la section 9 pour utiliser nerdctl seul.
11. Configurer CRI-O
Étape 1 : enregistrer le runtime auprès de CRI-O.
$ sudo nvidia-ctk runtime configure --runtime=crio
Cette commande écrit un fichier drop-in, /etc/crio/conf.d/99-nvidia.toml, afin que CRI-O puisse utiliser le runtime NVIDIA.
Étape 2 : redémarrer CRI-O.
$ sudo systemctl restart crio
12. Podman et la Container Device Interface (CDI)
Pour Podman, NVIDIA recommande la Container Device Interface. CDI est une spécification ouverte : un fichier YAML décrit chaque périphérique et tout ce dont un conteneur a besoin pour l'utiliser, et tout moteur compatible CDI lit ce fichier. Rien n'a besoin de s'accrocher au moteur au démarrage.
Étape 1 : générer la spécification CDI pour les GPU de cet hôte :
$ sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
Étape 2 : vérifier les noms de périphériques créés :
$ nvidia-ctk cdi list
nvidia.com/gpu=0
nvidia.com/gpu=1
nvidia.com/gpu=all
...
Étape 3 : exécuter un conteneur avec un GPU.
$ podman run --rm --device nvidia.com/gpu=all --security-opt=label=disable \
ubuntu nvidia-smi -L
--security-opt=label=disable est nécessaire sur les systèmes SELinux tels que RHEL, où l'étiquette par défaut empêche le conteneur de lire les fichiers de périphériques.
La spécification enregistre la version du pilote et les chemins de fichiers au moment de sa génération. Régénérez-la après chaque mise à niveau du pilote, ainsi qu'après l'ajout ou le retrait de GPU ou la modification des partitions MIG. Les versions récentes du toolkit peuvent le faire automatiquement via une unité systemd ; vérifiez que votre version l'inclut avant de vous y fier. Docker et containerd peuvent également utiliser CDI, ce qui évite le problème de cgroups décrit à la section 2.
13. Modifier en toute sécurité les paramètres du toolkit
Le toolkit conserve ses paramètres dans /etc/nvidia-container-runtime/config.toml. Modifiez-le avec nvidia-ctk config plutôt qu'à la main. Sans --in-place ni --output, la commande se contente d'afficher le résultat, ce qui vous offre un aperçu sans risque.
Prévisualiser une modification :
$ sudo nvidia-ctk config --set nvidia-container-runtime.log-level=debug
L'appliquer une fois le résultat satisfaisant :
$ sudo nvidia-ctk config --in-place --set nvidia-container-runtime.log-level=debug
Définissez plusieurs valeurs en une fois en répétant --set. Ceci active la journalisation de débogage et l'envoie vers un fichier :
$ sudo nvidia-ctk config --in-place \
--set nvidia-container-runtime.log-level=debug \
--set nvidia-container-runtime.debug=/var/log/nvidia-container-runtime.log
Pour un paramètre de type liste, séparez les éléments par des deux-points. Ceci fait de crun le premier runtime de bas niveau essayé, runc servant de solution de repli :
$ sudo nvidia-ctk config --in-place --set nvidia-container-runtime.runtimes=crun:runc
Les paramètres que vous ne mentionnez pas sont conservés. Si la même clé est indiquée deux fois, c'est la dernière valeur qui l'emporte. Désactivez à nouveau la journalisation de débogage une fois terminé : le journal grossit vite sur un hôte chargé.
14. Tester l'accès au GPU dans un conteneur
Exécutez nvidia-smi dans un conteneur Ubuntu standard. L'image ne contient aucun logiciel NVIDIA ; c'est le toolkit qui y monte l'utilitaire.
$ docker run --rm --gpus all ubuntu nvidia-smi
Vous devriez voir le même tableau de GPU que sur l'hôte. Vérifiez ensuite les cas que vous utiliserez en production :
| Ce qu'il faut vérifier | Commande |
|---|---|
| Tous les GPU | docker run --rm --gpus all ubuntu nvidia-smi -L |
| Des GPU précis par index | docker run --rm --gpus '"device=0,1"' ubuntu nvidia-smi -L |
| Un nombre de GPU | docker run --rm --gpus 2 ubuntu nvidia-smi -L |
| Directement via le runtime | docker run --rm --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all ubuntu nvidia-smi |
| Via CDI | docker run --rm --device nvidia.com/gpu=all ubuntu nvidia-smi |
| Une vraie charge de travail CUDA | Exécutez un exemple CUDA ou la vérification GPU de votre framework (par exemple torch.cuda.is_available()) dans l'image que vous déploierez réellement. |
Notez les guillemets dans le deuxième exemple : la liste de périphériques a besoin des deux niveaux de guillemets, sinon Docker la coupe à la virgule.
Par défaut, les conteneurs disposent d'un ensemble limité de fonctionnalités du pilote : calcul et utilitaires. Le graphisme, l'encodage et le décodage vidéo ainsi que l'affichage en nécessitent davantage. Définissez-les avec la variable d'environnement NVIDIA_DRIVER_CAPABILITIES, par exemple -e NVIDIA_DRIVER_CAPABILITIES=compute,utility,video pour un conteneur de transcodage.
15. Dépannage
| Symptôme | Cause probable | Solution |
|---|---|---|
could not select device driver "" with capabilities: [[gpu]] | Docker ne connaît pas le runtime NVIDIA. | Exécutez nvidia-ctk runtime configure --runtime=docker et redémarrez Docker. Vérifiez que l'outil de gestion de configuration n'a pas écrasé daemon.json. |
Failed to initialize NVML: Unknown Error dans un conteneur qui fonctionnait auparavant | Le problème de cgroups systemd après systemctl daemon-reload. | Redémarrez le conteneur. Pour éviter que cela ne se reproduise, utilisez CDI ou créez les liens symboliques /dev/char (section 2). |
Failed to initialize NVML: Driver/library version mismatch sur l'hôte | Le paquet du pilote a été mis à niveau mais l'ancien module noyau est toujours chargé. | Redémarrez, ou déchargez et rechargez le module pendant une fenêtre de maintenance. |
nvidia-smi fonctionne sur l'hôte mais pas dans le conteneur | Le conteneur a démarré sans demande de GPU, ou les fonctionnalités excluent utility. | Ajoutez --gpus ou un périphérique CDI, et vérifiez NVIDIA_DRIVER_CAPABILITIES. |
| Erreur CUDA indiquant que le pilote est trop ancien | La version de CUDA de l'image exige un pilote plus récent que celui de l'hôte. | Mettez à niveau le pilote de l'hôte, ou utilisez une image construite pour une version de CUDA plus ancienne. |
| Périphérique CDI introuvable après une mise à niveau du pilote | La spécification CDI décrit l'ancien pilote. | Régénérez-la avec nvidia-ctk cdi generate. |
Permission refusée sur /dev/nvidia* avec Podman | Étiquetage SELinux. | Ajoutez --security-opt=label=disable, ou utilisez une politique qui autorise les périphériques. |
| Erreurs du hook avec Docker rootless | Le toolkit tente de gérer les cgroups. | Définissez nvidia-container-cli.no-cgroups (section 8). |
Pour tout autre problème, activez la journalisation de débogage (section 13), reproduisez la panne et lisez le journal. Il enregistre chaque fichier et chaque périphérique que le toolkit a tenté de monter.
16. Exploitation sur un parc de machines
- Automatisez. Placez le dépôt, les paquets figés, la configuration du moteur et la génération CDI dans Ansible, Salt ou votre build d'image, et non dans un runbook que quelqu'un tape à la main.
- Mettez à niveau par anneaux. Mettez à niveau le pilote et le toolkit sur un hôte de test, exécutez vos vraies charges de travail et les vérifications de la section 14, puis passez à un petit groupe d'hôtes de production, puis au reste. Notre propre Ring Promoter fonctionne ainsi pour les publications logicielles.
- Séparez les changements de pilote et de toolkit. Changez un élément à la fois, afin de savoir quelle modification a causé un problème.
- Régénérez les spécifications CDI à chaque mise à niveau du pilote.
- Créez un miroir du dépôt pour les sites isolés ou réglementés, et signez ou contrôlez par somme de contrôle ce que vous mettez en miroir.
- Supervisez les GPU, pas seulement les conteneurs. NVIDIA DCGM et son exportateur Prometheus montrent la santé, les erreurs et l'utilisation des GPU, ce qui vous permet de distinguer un GPU défaillant d'un conteneur cassé.
- Consignez les versions. Conservez dans votre inventaire les versions du pilote, du toolkit, de l'image CUDA et du moteur pour chaque hôte. C'est la première chose que l'on demande quand quelque chose tombe en panne.
17. Comment Workstation peut vous aider
Chaque serveur et chaque station de travail d'IA que nous assemblons est livré avec le pilote NVIDIA, le Container Toolkit et le moteur de conteneurs installés, configurés et testés, avec des versions figées et consignées. Nous pouvons également :
- mettre en place Kubernetes avec le GPU Operator sur vos serveurs, avec des mises à niveau déployées par anneaux ;
- construire le pipeline Ansible ou d'images qui maintient la cohérence d'un parc GPU ;
- trouver de la capacité GPU en location si vous préférez ne pas posséder le matériel (voir GPU Leasing) ;
- assurer ensuite le support de la plateforme, y compris les mises à niveau du pilote et du toolkit.
Découvrez nos stations de travail d'IA et nos clusters GPU, ou contactez-nous pour parler à un ingénieur.
Sources
- NVIDIA, Installing the NVIDIA Container Toolkit, version 1.20.1 du toolkit. Les commandes d'installation et de configuration suivent ce guide.
- NVIDIA, documentation du Container Toolkit sur les plateformes prises en charge, la prise en charge de CDI et le dépannage.
NVIDIA, CUDA et DGX sont des marques commerciales et/ou des marques déposées de NVIDIA Corporation aux États-Unis et dans d'autres pays. Docker, Kubernetes, Podman et les autres noms sont des marques de leurs propriétaires respectifs.