Docker GPU Pass­th­rough ein­rich­ten: NVIDIA-GPU in Docker-Con­tai­nern nutzen

Docker GPU Pass­th­rough be­zeich­net die Wei­ter­ga­be einer NVIDIA-Gra­fik­kar­te vom Linux-Host an einen iso­lier­ten Docker-Container. Das NVIDIA Container Toolkit bindet dafür die be­nö­tig­ten Ge­rä­te­da­tei­en und Be­stand­tei­le des Host-Treibers über die NVIDIA Container Runtime ein, sodass An­wen­dun­gen wie KI-Modelle oder Da­ten­ana­ly­sen nahezu ohne zu­sätz­li­chen Vir­tua­li­sie­rungs-Overhead auf der GPU laufen.

Häufige Fehler beim Docker GPU Pass­th­rough

Ein häufiger Irrtum besteht darin, dass NVIDIA-Treiber und Container Toolkit dieselbe Ver­si­ons­num­mer besitzen müssten. Ent­schei­dend ist vielmehr, dass der Host-Treiber die vom Container benötigte CUDA-Version un­ter­stützt und dass die NVIDIA Runtime korrekt in Docker ein­ge­bun­den wurde.

Schritt 1: Den Linux-Host und den NVIDIA-Treiber vor­be­rei­ten

Bevor ein Docker-Container die GPU verwenden kann, muss Linux die Gra­fik­kar­te erkennen und ein funk­ti­ons­fä­hi­ger NVIDIA-Treiber in­stal­liert sein. Das NVIDIA Container Toolkit ersetzt diesen Treiber nicht. Es stellt lediglich die Ver­bin­dung zwischen dem vor­han­de­nen Host-Treiber, Docker und dem Container her.

Prüfen Sie zunächst, ob das System eine NVIDIA-Gra­fik­kar­te erkennt:

lspci | grep -i nvidia

Wird eine NVIDIA-GPU angezeigt, prüfen Sie im nächsten Schritt den Treiber:

nvidia-smi

Bei einem funk­tio­nie­ren­den Treiber erscheint eine Tabelle mit In­for­ma­tio­nen zur Gra­fik­kar­te, zur Trei­ber­ver­si­on, zum Gra­fik­spei­cher und zu den aktuell laufenden GPU-Prozessen. Ist diese Ausgabe bereits vorhanden, können Sie direkt mit Schritt 2 fort­fah­ren.

NVIDIA-Treiber unter Ubuntu in­stal­lie­ren

Ubuntu empfiehlt für die au­to­ma­ti­sche Trei­ber­aus­wahl das Werkzeug ubuntu-drivers. Für einen Server oder ein System, das haupt­säch­lich für Machine Learning und andere GPU-Be­rech­nun­gen verwendet wird, können Sie folgende Befehle ausführen:

sudo apt update
sudo apt install -y ubuntu-drivers-common
sudo ubuntu-drivers install --gpgpu
sudo reboot

Bei einer normalen Linux-Work­sta­tion mit gra­fi­scher Desktop-Ober­flä­che verwenden Sie statt­des­sen:

sudo ubuntu-drivers install
sudo reboot

Das Werkzeug wählt einen Treiber aus, der zur erkannten Hardware und zur Ubuntu-Version passt. Es be­rück­sich­tigt außerdem signierte Treiber, was ins­be­son­de­re bei ak­ti­vier­tem Secure Boot hilfreich ist.

Prüfen Sie die In­stal­la­ti­on nach dem Neustart erneut:

nvidia-smi

Funk­tio­niert nvidia-smi auf dem Host nicht, sollten Sie noch nicht mit der Docker-Kon­fi­gu­ra­ti­on fort­fah­ren. Ein Container kann nur auf eine GPU zugreifen, die bereits vom Host-System korrekt erkannt wird.

Docker prüfen

Kon­trol­lie­ren Sie außerdem, ob Docker in­stal­liert ist und der Docker-Dienst läuft:

docker --version
sudo systemctl is-active docker

Der zweite Befehl sollte active ausgeben. Ist Docker in­stal­liert, aber nicht gestartet, ak­ti­vie­ren Sie den Dienst mit:

sudo systemctl enable --now docker

Schritt 2: NVIDIA-Re­po­si­to­ry und Container Toolkit in­stal­lie­ren

Das NVIDIA Container Toolkit besteht aus mehreren Werk­zeu­gen und Bi­blio­the­ken, die Docker den kon­trol­lier­ten Zugriff auf die GPU er­mög­li­chen. Die er­for­der­li­chen Be­stand­tei­le sind im Paket nvidia-container-toolkit enthalten. Verwenden Sie nur das stabile NVIDIA-Re­po­si­to­ry. Das ex­pe­ri­men­tel­le Re­po­si­to­ry ist für eine pro­duk­ti­ve ML-Ops-Umgebung nor­ma­ler­wei­se nicht er­for­der­lich.

In­stal­la­ti­on mit APT unter Ubuntu oder Debian

In­stal­lie­ren Sie zunächst die Programme, die zum Ein­rich­ten des Re­po­si­to­rys benötigt werden:

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
    ca-certificates \
    curl \
    gnupg2

Im­por­tie­ren Sie an­schlie­ßend den Si­gna­tur­schlüs­sel und legen Sie die Pa­ket­quel­le an:

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

Ak­tua­li­sie­ren Sie danach die Pa­ket­lis­te:

sudo apt-get update

In­stal­lie­ren Sie nun alle Be­stand­tei­le des Toolkits in derselben Version:

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.20.0-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}

Durch die feste Ver­si­ons­an­ga­be werden alle zu­sam­men­ge­hö­ren­den Pakete mit einem ein­heit­li­chen Ver­si­ons­stand in­stal­liert (hier: 1.20.0-1).

In­stal­la­ti­on mit DNF oder YUM unter RPM-Linux

Für aktuelle Versionen von RHEL, Rocky Linux, CentOS, Fedora oder Amazon Linux verwenden Sie in der Regel dnf. In­stal­lie­ren Sie zunächst curl:

sudo dnf install -y curl

Richten Sie danach das NVIDIA-Re­po­si­to­ry ein:

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

In­stal­lie­ren Sie an­schlie­ßend das Toolkit:

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.20.0-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}

Verwendet Ihre Dis­tri­bu­ti­on weiterhin den Befehl yum, können Sie ent­spre­chend ausführen:

sudo yum install -y nvidia-container-toolkit

In­stal­la­ti­on kon­trol­lie­ren

Prüfen Sie, ob die zentralen Programme vorhanden sind:

nvidia-ctk --version
which nvidia-container-runtime
which nvidia-container-cli

Die Befehle sollten eine Ver­si­ons­num­mer be­zie­hungs­wei­se einen Pro­gramm­pfad ausgeben.

Schritt 3: NVIDIA Runtime in Docker ein­rich­ten

Nach der In­stal­la­ti­on kennt Docker die NVIDIA Runtime noch nicht au­to­ma­tisch. Dafür muss die Docker-Daemon-Kon­fi­gu­ra­ti­on angepasst werden. Verwenden Sie dazu den von NVIDIA be­reit­ge­stell­ten Befehl:

sudo nvidia-ctk runtime configure --runtime=docker

nvidia-ctk be­ar­bei­tet die Datei /etc/docker/daemon.json und trägt die NVIDIA Container Runtime dort ein. Der Vorteil gegenüber einer manuellen Be­ar­bei­tung besteht darin, dass bereits vor­han­de­ne Docker-Ein­stel­lun­gen nicht einfach über­schrie­ben werden.

Sie können die Datei an­schlie­ßend anzeigen:

sudo cat /etc/docker/daemon.json

Die genaue Dar­stel­lung kann je nach Docker- und Toolkit-Version un­ter­schied­lich aussehen. Ent­schei­dend ist, dass unter den ver­füg­ba­ren Runtimes ein Eintrag für nvidia vorhanden ist.

Bevor Sie Docker neu starten, können Sie die Kon­fi­gu­ra­ti­on prüfen:

sudo dockerd --validate --config-file=/etc/docker/daemon.json

Bei einer gültigen Datei erscheint:

configuration OK

Docker bietet diese Prüfung aus­drück­lich an, damit Kon­fi­gu­ra­ti­ons­feh­ler erkannt werden können, bevor der laufende Dienst neu gestartet wird. Starten Sie nun den Docker-Dienst neu:

sudo systemctl restart docker

Kon­trol­lie­ren Sie danach, ob Docker wieder läuft:

sudo systemctl status docker --no-pager

Prüfen Sie außerdem die re­gis­trier­ten Runtimes:

docker info | grep -i runtimes

In der Ausgabe sollte neben der normalen Runtime runc auch nvidia er­schei­nen. Es ist in der Regel nicht notwendig, NVIDIA als Standard-Runtime für sämtliche Container fest­zu­le­gen. Geben Sie die GPU besser nur den Con­tai­nern frei, die sie tat­säch­lich benötigen. Dadurch bleibt die Kon­fi­gu­ra­ti­on nach­voll­zieh­bar und normale Webserver-, Datenbank- oder Hilfs­con­tai­ner erhalten keinen unnötigen Zugriff auf die GPU.

Schritt 4: GPU-Be­schleu­ni­gung mit nvidia-smi im Container va­li­die­ren

Zum Abschluss starten Sie einen kurz­le­bi­gen Test­con­tai­ner. Der folgende Befehl gibt dem Container Zugriff auf alle erkannten NVIDIA-GPUs und führt darin nvidia-smi aus:

sudo docker run --rm \
    --runtime=nvidia \
    --gpus all \
    ubuntu \
    nvidia-smi

Docker lädt dabei ge­ge­be­nen­falls zunächst das Ubuntu-Image herunter. Das NVIDIA Container Toolkit bindet an­schlie­ßend die be­nö­tig­ten GPU-Geräte und Trei­ber­bi­blio­the­ken des Hosts in den Container ein. Das Ubuntu-Image selbst muss deshalb keinen voll­stän­di­gen NVIDIA-Treiber enthalten. NVIDIA verwendet diesen Befehl auch in der of­fi­zi­el­len Bei­spiel­kon­fi­gu­ra­ti­on. Die Ausgabe sollte ähnlich wie beim Befehl nvidia-smi auf dem Host aussehen. Sie sollte min­des­tens folgende Angaben enthalten:

• den Namen der NVIDIA-GPU,
• die auf dem Host in­stal­lier­te Trei­ber­ver­si­on,
• den ver­füg­ba­ren Gra­fik­spei­cher,
• die aktuelle GPU-Aus­las­tung
• und die vom Treiber un­ter­stütz­te CUDA-Version.

Wichtig ist, dass der Befehl innerhalb des Con­tai­ners eine GPU anzeigt und nicht mit einer Runtime-, Treiber- oder Be­rech­ti­gungs­feh­ler­mel­dung beendet wird.

Nur eine bestimmte GPU freigeben

Besitzt der Host mehrere NVIDIA-GPUs, sollten Sie einem Container nur die tat­säch­lich benötigte GPU zuweisen. Für die erste GPU mit dem Index 0 lautet der Befehl:

sudo docker run --rm \
    --runtime=nvidia \
    --gpus '"device=0"' \
    ubuntu \
    nvidia-smi

Mehrere aus­ge­wähl­te GPUs können Sie bei­spiels­wei­se so freigeben:

sudo docker run --rm \
    --runtime=nvidia \
    --gpus '"device=0,1"' \
    ubuntu \
    nvidia-smi

Die gezielte Auswahl ver­hin­dert, dass ein einzelner Container un­be­ab­sich­tigt sämtliche GPU-Res­sour­cen des Hosts belegt. NVIDIA un­ter­stützt die Auswahl über Ge­rä­te­in­dex oder GPU-UUID.

Best Practices für Docker und NVIDIA-GPUs

Container-Images eindeutig ver­sio­nie­ren

Verwenden Sie für pro­duk­ti­ve Machine-Learning-An­wen­dun­gen keine un­be­stimm­ten Image-Tags wie latest. Geben Sie statt­des­sen eine konkrete CUDA-, Framework- und Be­triebs­sys­tem­ver­si­on an. Dadurch lässt sich später nach­voll­zie­hen, welche Soft­ware­stän­de getestet und ein­ge­setzt wurden.

Host-Treiber und CUDA-Version auf­ein­an­der abstimmen

Der NVIDIA-Treiber läuft auf dem Host, während sich die CUDA-Laufzeit nor­ma­ler­wei­se im Container befindet. Der Host-Treiber muss min­des­tens die An­for­de­run­gen des ver­wen­de­ten CUDA-Images erfüllen. Neuere Treiber können in vielen Fällen ältere CUDA-An­wen­dun­gen ausführen, ein zu alter Treiber kann jedoch den Start eines aktuellen CUDA-Con­tai­ners ver­hin­dern.

In­stal­lie­ren Sie nicht vor­sorg­lich mehrere CUDA-Versionen auf dem Host. Für den normalen Con­tai­ner­be­trieb benötigt der Host vor allem einen funk­tio­nie­ren­den NVIDIA-Treiber und das NVIDIA Container Toolkit.

GPU-Zugriff bewusst begrenzen

Verwenden Sie --gpus all nur, wenn ein Container wirklich alle Gra­fik­kar­ten benötigt. In gemeinsam genutzten ML-Ops-Um­ge­bun­gen ist eine gezielte Zuweisung über device=0, eine GPU-UUID oder eine Or­ches­trie­rungs­platt­form besser kon­trol­lier­bar.

Nach Updates erneut testen

Führen Sie nach einem Update des Kernels, NVIDIA-Treibers, Docker-Daemons oder NVIDIA Container Toolkits erneut beide Prüfungen aus:

nvidia-smi

und:

sudo docker run --rm \
    --runtime=nvidia \
    --gpus all \
    ubuntu \
    nvidia-smi

Die erste Prüfung testet den Host-Treiber. Die zweite Prüfung testet zu­sätz­lich das Toolkit, die Docker-Kon­fi­gu­ra­ti­on und die Wei­ter­ga­be der GPU an den Container.

Trei­ber­ak­tua­li­sie­run­gen mit einem Neustart ab­schlie­ßen

Nach einem Treiber- oder Kernel-Update kann im laufenden Kernel weiterhin die alte Version des NVIDIA-Moduls aktiv sein. Ein geplanter Neustart ver­hin­dert Ver­si­ons­kon­flik­te zwischen Ker­nel­mo­dul und Trei­ber­bi­blio­the­ken.

daemon.json nicht voll­stän­dig über­schrei­ben

Enthält /etc/docker/daemon.json bereits Ein­stel­lun­gen für Pro­to­kol­lie­rung, Speicher, Netzwerke oder Registry-Server, dürfen diese nicht verloren gehen. Verwenden Sie deshalb nvidia-ctk runtime configure und va­li­die­ren Sie die Datei vor dem Docker-Neustart mit dockerd --validate.

Fazit

Für Docker GPU Pass­th­rough unter Linux werden drei funk­tio­nie­ren­de Ebenen benötigt: ein korrekt in­stal­lier­ter NVIDIA-Treiber auf dem Host, das NVIDIA Container Toolkit und eine in Docker re­gis­trier­te NVIDIA Runtime. Sobald nvidia-smi sowohl auf dem Host als auch im Test­con­tai­ner funk­tio­niert, steht die GPU für CUDA-, Machine-Learning- und andere re­chen­in­ten­si­ve Container-An­wen­dun­gen zur Verfügung. Durch fest ver­sio­nier­te Container-Images, eine gezielte GPU-Zuweisung und erneute Tests nach Sys­tem­up­dates bleibt die Kon­fi­gu­ra­ti­on auch in pro­duk­ti­ven ML-Ops-Um­ge­bun­gen stabil und nach­voll­zieh­bar.