Deze technische notitie is bedoeld voor engineers die GPU's in containers nodig hebben: platform- en MLOps-teams, Kubernetes-beheerders en iedereen die een nieuwe GPU-server krijgt met de vraag Docker erop werkend te krijgen. Ze behandelt wat de NVIDIA Container Toolkit doet, hoe u hem installeert op Debian-, Ubuntu-, RHEL- en SUSE-systemen, hoe u Docker, rootless Docker, containerd, nerdctl, CRI-O en Podman configureert, hoe u hem test en wat er misgaat. De commando's volgen de installatiehandleiding van NVIDIA voor toolkitversie 1.20.1, de actuele release toen wij dit schreven. De uitleg, controles, probleemoplossing en het advies voor vloten zijn van onszelf, op basis van het bouwen en ondersteunen van GPU-servers.
Inhoud
- Wat de toolkit doet
- Voordat u begint
- Installeren op Ubuntu en Debian (apt)
- Installeren op RHEL, Rocky, Fedora en Amazon Linux (dnf)
- Installeren op openSUSE en SLES (zypper)
- Versies vastzetten en upgrades plannen
- Docker configureren
- Rootless Docker configureren
- containerd configureren voor Kubernetes
- nerdctl
- CRI-O configureren
- Podman en de Container Device Interface (CDI)
- De eigen instellingen van de toolkit veilig wijzigen
- GPU-toegang in een container testen
- Probleemoplossing
- Uitrol over een vloot
- Hoe Workstation kan helpen
1. Wat de toolkit doet
Een containerimage hoort geen GPU-driver te bevatten. De driver is gekoppeld aan de kernelmodule op de host, en een image die voor de ene driverversie is gebouwd, zou bij de volgende breken. De NVIDIA Container Toolkit lost dit op: wanneer een container om een GPU vraagt, zoekt de toolkit de driverbibliotheken, device nodes en hulpprogramma's van de host, zoals nvidia-smi, en mount die in de container vlak voordat die start. De image heeft alleen de CUDA-user-spacebibliotheken nodig waarmee de applicatie is gebouwd.
De toolkit is een kleine set pakketten die samenwerken:
| Pakket of tool | Wat het doet |
|---|---|
libnvidia-container1 en libnvidia-container-tools | De bibliotheek en CLI die de drivercomponenten op de host vinden en ze in de container inrichten. |
nvidia-container-toolkit-base | De nvidia-container-runtime, een dunne wrapper rond runc (of crun) die de GPU-inrichting aan de containerspecificatie toevoegt, en het commando nvidia-ctk. |
nvidia-container-toolkit | De hook die container-engines aanroepen wanneer een container start, plus al het bovenstaande als afhankelijkheden. |
nvidia-ctk | Het commando waarmee u container-engines configureert, de instellingen van de toolkit bewerkt en CDI-specificaties genereert. |
U hebt de CUDA Toolkit niet nodig op de host. De host heeft de NVIDIA-driver nodig; de CUDA-versie zit in de containerimage. De enige regel is dat de hostdriver nieuw genoeg moet zijn voor de CUDA-versie in de image. Een nieuwere driver draait images die voor oudere CUDA-versies zijn gebouwd.
2. Voordat u begint
- Een ondersteunde distributie. NVIDIA publiceert de lijst met ondersteunde platforms. In de praktijk: actuele Ubuntu LTS- en Debian-releases, RHEL en de rebuilds daarvan (Rocky, AlmaLinux), Fedora, Amazon Linux, openSUSE en SLES, op x86_64 of arm64.
- Een werkende NVIDIA-driver. Installeer die via de pakketbeheerder van uw distributie, zoals NVIDIA aanbeveelt, of met de
.run-installer van NVIDIA. Controleer hem voordat u verdergaat:
Als dit uw GPU's niet toont, stop dan en los eerst het driverprobleem op. De toolkit kan niet zonder. Op servers met Secure Boot moet de kernelmodule ondertekend zijn, anders wordt de driver wel geïnstalleerd maar niet geladen.$ nvidia-smi - Een container-engine voor de configuratiestappen: Docker, containerd, CRI-O of Podman. U kunt eerst de toolkit installeren en daarna de engine.
- Root- of sudo-toegang, en uitgaand HTTPS naar
nvidia.github.io, of een lokale mirror van de repository van NVIDIA op air-gapped locaties.
Een bekend probleem om rekening mee te houden. Op hosts waar de container-engine de systemd-cgroupdriver gebruikt, kan het uitvoeren van systemctl daemon-reload ervoor zorgen dat draaiende containers de toegang tot hun GPU's verliezen. Ze melden dan Failed to initialize NVML: Unknown Error. Pakketupgrades veroorzaken vaak een daemon-reload, dus dit verschijnt meestal pas dagen na de installatie. De troubleshootinghandleiding van NVIDIA behandelt het; de gebruikelijke oplossingen zijn CDI gebruiken (sectie 12) of de /dev/char-symlinks aanmaken die de driverdevices nodig hebben:
$ sudo nvidia-ctk system create-dev-char-symlinks --create-all
3. Installeren op Ubuntu en Debian (apt)
Deze stappen werken op de meeste van Debian afgeleide distributies.
Stap 1: installeer de tools die de repository-inrichting nodig heeft.
$ sudo apt-get update && sudo apt-get install -y --no-install-recommends \
ca-certificates curl gnupg2
Stap 2: voeg de ondertekeningssleutel van NVIDIA en de productierepository toe. De sleutel komt in een eigen keyring en de repository wordt daartoe beperkt met signed-by, zodat deze sleutel geen pakketten uit een andere repository kan ondertekenen.
$ 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 publiceert ook een experimenteel kanaal. Laat dat uit op productiemachines; om het voor tests in te schakelen, haalt u het commentaarteken weg:
$ sudo sed -i -e '/experimental/ s/^#//g' /etc/apt/sources.list.d/nvidia-container-toolkit.list
Stap 3: ververs de pakketlijsten.
$ sudo apt-get update
Stap 4: installeer de vier pakketten op één versie. Door de versie te noemen blijft elke host in een vloot identiek, en blijven de vier pakketten onderling gelijk.
$ 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}
Controleer wat u hebt geïnstalleerd:
$ nvidia-ctk --version
4. Installeren op RHEL, Rocky, Fedora en Amazon Linux (dnf)
Deze stappen werken op de meeste RPM-gebaseerde distributies die dnf gebruiken.
Stap 1: zorg dat curl aanwezig is.
$ sudo dnf install -y curl
Stap 2: voeg de productierepository toe.
$ 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
Om experimentele pakketten op een testmachine te proberen:
$ sudo dnf config-manager --enable nvidia-container-toolkit-experimental
Stap 3: installeer de pakketten op één versie. Let op: dnf verbindt naam en versie met een koppelteken, niet met een isgelijkteken.
$ 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 vraagt u de eerste keer de ondertekeningssleutel van NVIDIA te accepteren. Controleer de fingerprint tegen de door NVIDIA gepubliceerde sleutel voordat u die accepteert.
5. Installeren op openSUSE en SLES (zypper)
Stap 1: voeg de productierepository toe.
$ sudo zypper ar https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo
Om experimentele pakketten te proberen:
$ sudo zypper modifyrepo --enable nvidia-container-toolkit-experimental
Stap 2: installeer de pakketten op één versie.
$ 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 vertrouwt de sleutel van de repository zonder te vragen. Dat past bij automatisering; op een enkele server importeert en controleert u de sleutel misschien liever eerst met de hand.
6. Versies vastzetten en upgrades plannen
Een automatische upgrade die de toolkit bijwerkt, of de driver bijwerkt zonder de toolkit, is een veelvoorkomende oorzaak van GPU-containers die 's nachts uitvallen. Zet de pakketten vast en upgrade ze bewust:
| Distributie | De toolkitpakketten vastzetten |
|---|---|
| Ubuntu, Debian | sudo apt-mark hold nvidia-container-toolkit nvidia-container-toolkit-base libnvidia-container-tools libnvidia-container1 |
| RHEL-familie, Fedora | sudo dnf versionlock add nvidia-container-toolkit nvidia-container-toolkit-base libnvidia-container-tools libnvidia-container1 (vereist de versionlock-plugin) |
| openSUSE, SLES | sudo zypper addlock nvidia-container-toolkit nvidia-container-toolkit-base libnvidia-container-tools libnvidia-container1 |
Upgrade bij een upgrade alle vier de pakketten samen, eerst op één testhost, en volg daarna de volgorde uit sectie 16.
7. Docker configureren
Stap 1: registreer de NVIDIA-runtime bij Docker.
$ sudo nvidia-ctk runtime configure --runtime=docker
Dit bewerkt /etc/docker/daemon.json en voegt een nvidia-runtime toe. Bestaande instellingen in het bestand blijven behouden. Het resultaat ziet er zo uit:
{
"runtimes": {
"nvidia": {
"args": [],
"path": "nvidia-container-runtime"
}
}
}
Stap 2: herstart Docker.
$ sudo systemctl restart docker
Een herstart van Docker stopt draaiende containers, tenzij live restore is ingeschakeld, dus doe dit op een drukke host in een onderhoudsvenster. Als u daemon.json met configuratiebeheer beheert, voeg de runtime dan daar toe, anders verwijdert uw tool hem bij de volgende run.
De vlag --gpus van Docker werkt zodra de runtime is geregistreerd. Als u wilt dat elke container standaard de NVIDIA-runtime gebruikt, bijvoorbeeld op een dedicated GPU-host, voeg dan --set-as-default toe aan het configuratiecommando.
8. Rootless Docker configureren
Rootless Docker draait de daemon als gewone gebruiker, met een eigen configuratiebestand. Drie stappen:
Stap 1: registreer de runtime in de Docker-configuratie van de gebruiker (zonder sudo):
$ nvidia-ctk runtime configure --runtime=docker --config=$HOME/.config/docker/daemon.json
Stap 2: herstart de Docker-daemon van de gebruiker.
$ systemctl --user restart docker
Stap 3: geef de toolkit opdracht geen cgroups te beheren, wat een rootless daemon niet mag. Dit is een instelling voor de hele host, dus er is sudo voor nodig:
$ sudo nvidia-ctk config --set nvidia-container-cli.no-cgroups --in-place
Die instelling geldt voor elke engine op de host. Pas hem niet toe op een host die ook rootful containers draait die voor de cgroup-inrichting op de toolkit vertrouwen.
9. containerd configureren voor Kubernetes
Stap 1: registreer de runtime bij containerd.
$ sudo nvidia-ctk runtime configure --runtime=containerd
Standaard schrijft dit een drop-inbestand, /etc/containerd/conf.d/99-nvidia.toml, en voegt het dat toe aan de imports-lijst in /etc/containerd/config.toml, waarbij dat bestand wordt aangemaakt als het nog niet bestaat. Door de NVIDIA-instellingen in een drop-in te houden, blijft uw eigen config.toml leesbaar en is de wijziging eenvoudig te verwijderen.
Stap 2: herstart containerd.
$ sudo systemctl restart containerd
Kubernetes moet daarna van de GPU's weten. De meeste clusters gebruiken de NVIDIA GPU Operator, die de toolkit en de device plugin voor u kan installeren, of alleen de NVIDIA device plugin. Pods kiezen de runtime via een RuntimeClass met de naam nvidia, of gebruiken die standaard als u hem instelt als standaardruntime van containerd. Als u de GPU Operator met de ingebouwde toolkit gebruikt, installeer de toolkit dan niet ook nog met de hand op de nodes, anders vechten de twee om dezelfde configuratie.
Distributies die hun eigen containerd meeleveren, zoals k3s en RKE2, bewaren de configuratie ervan op een andere plek en detecteren de NVIDIA-runtime vaak automatisch. Volg hun GPU-documentatie in plaats van /etc/containerd te bewerken.
10. nerdctl
nerdctl, de commandline in Docker-stijl voor containerd, heeft geen configuratie nodig. Zodra de toolkit is geïnstalleerd, werkt nerdctl run --gpus=all met of zonder root. Voor nerdctl op zich hebt u de containerd-configuratie uit sectie 9 niet nodig.
11. CRI-O configureren
Stap 1: registreer de runtime bij CRI-O.
$ sudo nvidia-ctk runtime configure --runtime=crio
Dit schrijft een drop-inbestand, /etc/crio/conf.d/99-nvidia.toml, zodat CRI-O de NVIDIA-runtime kan gebruiken.
Stap 2: herstart CRI-O.
$ sudo systemctl restart crio
12. Podman en de Container Device Interface (CDI)
Voor Podman raadt NVIDIA de Container Device Interface aan. CDI is een open specificatie: een YAML-bestand beschrijft elk device en alles wat een container nodig heeft om het te gebruiken, en elke engine die CDI ondersteunt, leest dat bestand. Er hoeft bij het opstarten niets in de engine te haken.
Stap 1: genereer de CDI-specificatie voor de GPU's in deze host:
$ sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
Stap 2: controleer de devicenamen die zijn aangemaakt:
$ nvidia-ctk cdi list
nvidia.com/gpu=0
nvidia.com/gpu=1
nvidia.com/gpu=all
...
Stap 3: draai een container met een GPU.
$ podman run --rm --device nvidia.com/gpu=all --security-opt=label=disable \
ubuntu nvidia-smi -L
--security-opt=label=disable is nodig op SELinux-systemen zoals RHEL, waar het standaardlabel voorkomt dat de container de devicebestanden leest.
De specificatie legt de driverversie en bestandspaden vast op het moment van genereren. Genereer haar opnieuw na elke driverupgrade, en na het toevoegen of verwijderen van GPU's of het wijzigen van MIG-partities. Recente toolkitreleases kunnen dit automatisch doen via een systemd-unit; controleer of uw versie die bevat voordat u erop vertrouwt. Docker en containerd kunnen ook CDI gebruiken, en het voorkomt het cgroupprobleem uit sectie 2.
13. De eigen instellingen van de toolkit veilig wijzigen
De toolkit bewaart zijn instellingen in /etc/nvidia-container-runtime/config.toml. Bewerk die met nvidia-ctk config in plaats van met de hand. Zonder --in-place of --output drukt het commando alleen het resultaat af, wat u een veilige preview geeft.
Bekijk een wijziging vooraf:
$ sudo nvidia-ctk config --set nvidia-container-runtime.log-level=debug
Pas haar toe zodra u tevreden bent met de uitvoer:
$ sudo nvidia-ctk config --in-place --set nvidia-container-runtime.log-level=debug
Stel meerdere waarden in één keer in door --set te herhalen. Dit schakelt debuglogging in en stuurt die naar een bestand:
$ sudo nvidia-ctk config --in-place \
--set nvidia-container-runtime.log-level=debug \
--set nvidia-container-runtime.debug=/var/log/nvidia-container-runtime.log
Scheid bij een lijstinstelling de items met dubbele punten. Dit maakt crun de eerste low-level runtime die wordt geprobeerd, met runc als terugvaloptie:
$ sudo nvidia-ctk config --in-place --set nvidia-container-runtime.runtimes=crun:runc
Instellingen die u niet noemt, blijven behouden. Als dezelfde sleutel twee keer wordt opgegeven, wint de laatste waarde. Schakel debuglogging weer uit als u klaar bent: het log groeit snel op een drukke host.
14. GPU-toegang in een container testen
Draai nvidia-smi in een kale Ubuntu-container. De image bevat geen NVIDIA-software; de toolkit mount het hulpprogramma erin.
$ docker run --rm --gpus all ubuntu nvidia-smi
U zou dezelfde GPU-tabel moeten zien als op de host. Controleer daarna de gevallen die u in productie gaat gebruiken:
| Wat te controleren | Commando |
|---|---|
| Alle GPU's | docker run --rm --gpus all ubuntu nvidia-smi -L |
| Specifieke GPU's op index | docker run --rm --gpus '"device=0,1"' ubuntu nvidia-smi -L |
| Een aantal GPU's | docker run --rm --gpus 2 ubuntu nvidia-smi -L |
| Rechtstreeks via de 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 |
| Een echte CUDA-workload | Draai een CUDA-sample of de GPU-controle van uw framework (bijvoorbeeld torch.cuda.is_available()) in de image die u daadwerkelijk gaat uitrollen. |
Let op de aanhalingstekens in het tweede voorbeeld: de devicelijst heeft beide sets aanhalingstekens nodig, anders splitst Docker haar bij de komma.
Containers krijgen standaard een beperkte set driverfuncties: compute en utility. Graphics, video-encoding en -decoding en display vereisen meer. Stel ze in met de omgevingsvariabele NVIDIA_DRIVER_CAPABILITIES, bijvoorbeeld -e NVIDIA_DRIVER_CAPABILITIES=compute,utility,video voor een transcodeercontainer.
15. Probleemoplossing
| Symptoom | Waarschijnlijke oorzaak | Oplossing |
|---|---|---|
could not select device driver "" with capabilities: [[gpu]] | Docker kent de NVIDIA-runtime niet. | Voer nvidia-ctk runtime configure --runtime=docker uit en herstart Docker. Controleer of configuratiebeheer daemon.json niet heeft overschreven. |
Failed to initialize NVML: Unknown Error in een container die eerder werkte | Het systemd-cgroupprobleem na systemctl daemon-reload. | Herstart de container. Om herhaling te voorkomen, gebruikt u CDI of maakt u de /dev/char-symlinks aan (sectie 2). |
Failed to initialize NVML: Driver/library version mismatch op de host | Het driverpakket is geüpgraded, maar de oude kernelmodule is nog geladen. | Herstart, of ontlaad en herlaad de module in een onderhoudsvenster. |
nvidia-smi werkt op de host maar niet in de container | De container is gestart zonder GPU-verzoek, of de capabilities sluiten utility uit. | Voeg --gpus of een CDI-device toe, en controleer NVIDIA_DRIVER_CAPABILITIES. |
| CUDA-fout die meldt dat de driver te oud is | De CUDA-versie van de image vereist een nieuwere driver dan de host heeft. | Upgrade de hostdriver, of gebruik een image die voor een oudere CUDA-versie is gebouwd. |
| CDI-device niet gevonden na een driverupgrade | De CDI-specificatie beschrijft de oude driver. | Genereer haar opnieuw met nvidia-ctk cdi generate. |
Permission denied op /dev/nvidia* met Podman | SELinux-labeling. | Voeg --security-opt=label=disable toe, of gebruik een policy die de devices toestaat. |
| Fouten van de hook met rootless Docker | De toolkit probeert cgroups te beheren. | Stel nvidia-container-cli.no-cgroups in (sectie 8). |
Voor al het andere: schakel debuglogging in (sectie 13), reproduceer de fout en lees het log. Het legt elk bestand en elk device vast dat de toolkit probeerde te mounten.
16. Uitrol over een vloot
- Automatiseer het. Zet de repository, de vastgezette pakketten, de engineconfiguratie en het genereren van CDI in Ansible, Salt of uw imagebuild, niet in een runbook dat iemand met de hand intypt.
- Upgrade in ringen. Upgrade driver en toolkit op één testhost, draai uw echte workloads en de controles uit sectie 14, ga daarna naar een kleine groep productiehosts en vervolgens naar de rest. Onze eigen Ring Promoter werkt zo voor softwarereleases.
- Houd driver- en toolkitwijzigingen gescheiden. Wijzig er één tegelijk, zodat u weet welke wijziging een probleem heeft veroorzaakt.
- Genereer CDI-specificaties opnieuw als onderdeel van elke driverupgrade.
- Mirror de repository voor air-gapped of gereguleerde locaties, en onderteken of checksum wat u mirrort.
- Monitor de GPU's, niet alleen de containers. NVIDIA DCGM en de Prometheus-exporter ervan tonen GPU-gezondheid, fouten en gebruik, zodat u een falende GPU kunt onderscheiden van een kapotte container.
- Leg versies vast. Houd per host de versies van driver, toolkit, CUDA-image en engine bij in uw inventaris. Dat is het eerste waar iemand naar vraagt als er iets kapotgaat.
17. Hoe Workstation kan helpen
Elke AI-server en -workstation die wij bouwen, wordt geleverd met de NVIDIA-driver, de Container Toolkit en de container-engine geïnstalleerd, geconfigureerd en getest, met vastgezette en vastgelegde versies. Wij kunnen ook:
- Kubernetes met de GPU Operator op uw servers inrichten, met upgrades die in ringen worden uitgerold;
- de Ansible- of imagepipeline bouwen die een GPU-vloot consistent houdt;
- geleasede GPU-capaciteit vinden als u de hardware liever niet zelf bezit (zie GPU Leasing);
- het platform daarna ondersteunen, inclusief driver- en toolkitupgrades.
Bekijk onze AI-workstations en GPU-clusters, of neem contact met ons op om met een engineer te spreken.
Bronnen
- NVIDIA, Installing the NVIDIA Container Toolkit, toolkitversie 1.20.1. De installatie- en configuratiecommando's volgen deze handleiding.
- NVIDIA, documentatie van de Container Toolkit over ondersteunde platforms, CDI-ondersteuning en probleemoplossing.
NVIDIA, CUDA en DGX zijn handelsmerken en/of geregistreerde handelsmerken van NVIDIA Corporation in de VS en andere landen. Docker, Kubernetes, Podman en andere namen zijn handelsmerken van hun respectieve eigenaren.