Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// installation

NVIDIA / GPU

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Treiber, CUDA-Runtime, Container Toolkit und GPU Operator; MIG, wo die Referenzkonfiguration es nutzt; wie Sie prüfen, dass der Knoten die erwarteten GPU-Ressourcen anbietet. Dieser Schritt gilt nur für Hosts, die GPU-Workloads ausführen – ein reiner CPU-Anwendungsserver überspringt ihn.

Offizielle Dokumentation: CUDA Installation Guide for Linux · NVIDIA Container Toolkit · GPU Operator · MIG User Guide

1. GPUs identifizieren

Bevor Sie etwas installieren, halten Sie fest, welche GPU welche Rolle bekommt – anhand stabiler Identität, nicht anhand von Indexnummern:

lspci | grep -i nvidia
nvidia-smi -L          # nach der Treiberinstallation: UUID je GPU
nvidia-smi topo -m     # Interconnect zwischen den GPUs (NVLink, PCIe)

Notieren Sie UUID, PCI-Adresse und NUMA-Knoten je GPU sowie die geplante Rolle (Inferenz oder Service-Modelle). Für tensor-parallele Inferenz wählen Sie das Paar mit dem schnellsten Peer-Pfad.

2. Treiber

sudo ubuntu-drivers autoinstall
sudo reboot
nvidia-smi

Erwartet: Treiber 550+ (geprüft: 580.126.09), CUDA-Version 13.0+ in der Ausgabe, alle GPUs gelistet. Fehlerbilder stehen unten unter „Häufige Fehlerbilder“.

3. CUDA Toolkit

CUDA 13.0 installieren, Umgebungsvariablen setzen und mit nvcc --version prüfen:

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get install -y cuda-toolkit-13-0

echo 'export PATH=/usr/local/cuda-13.0/bin${PATH:+:${PATH}}' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-13.0/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' >> ~/.bashrc
source ~/.bashrc
nvcc --version

Ist CUDA 13.0 in Ihrem Repository nicht verfügbar, nutzen Sie 12.9 als Rückfalloption:

sudo apt-get install -y cuda-toolkit-12-9
echo 'export PATH=/usr/local/cuda-12.9/bin${PATH:+:${PATH}}' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.9/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' >> ~/.bashrc
source ~/.bashrc

4. Container-Runtime für GPUs

Zwei Wege:

Mit Kubernetes und GPU Operator (Standard): Der GPU Operator installiert und konfiguriert das NVIDIA Container Toolkit auf den Knoten selbst. Schritt 5 überspringt dann die manuelle Toolkit-Installation.
Nur Docker (Entwicklung/Test): NVIDIA Container Toolkit manuell installieren, Docker für die NVIDIA-Runtime konfigurieren, Docker neu starten und prüfen:

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 | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
sudo docker run --rm --gpus all nvidia/cuda:12.9.0-base-ubuntu22.04 nvidia-smi

5. GPU Operator

Nach der Kubernetes-Installation (Kubernetes) den GPU Operator per Helm installieren. Auf einem Einzelknoten mit Control-Plane-Taint braucht der Operator Tolerations in der Values-Datei gpu-operator-values.yaml:

# gpu-operator-values.yaml
node-feature-discovery:
  master:
    tolerations:
      - key: node-role.kubernetes.io/control-plane
        operator: Exists
        effect: NoSchedule
  worker:
    tolerations:
      - key: node-role.kubernetes.io/control-plane
        operator: Exists
        effect: NoSchedule
  gc:
    tolerations:
      - key: node-role.kubernetes.io/control-plane
        operator: Exists
        effect: NoSchedule
operator:
  tolerations:
    - key: node-role.kubernetes.io/control-plane
      operator: Exists
      effect: NoSchedule

Installation:

helm repo add nvidia https://helm.ngc.nvidia.com/nvidia
helm repo update
helm install --wait --timeout 15m --generate-name \
  -n gpu-operator --create-namespace \
  -f gpu-operator-values.yaml \
  nvidia/gpu-operator
kubectl get pods -n gpu-operator

Auf Multi-Node-Clustern mit dedizierten Worker-Knoten ohne Control-Plane-Taint installieren Sie ohne -f gpu-operator-values.yaml.

Sind Treiber bereits auf dem Host installiert (Schritt 2), konfigurieren Sie den Operator so, dass er keine Treiber-Container ausrollt; die Optionen dazu stehen in der GPU-Operator-Dokumentation. Für Sonderfälle – abgeschottete Umgebungen, vorinstallierte Treiber, MIG – wenden Sie sich bei Unklarheit an support@basebox.ai.

6. MIG einrichten, wo die Konfiguration es vorsieht

Die Validated-Konfigurationen teilen eine Service-GPU per MIG auf: 2 × H200 nutzt vier 1g.35gb-Instanzen auf einer H200; 4 × H100 SXM je zwei 3g.40gb auf zwei H100. Die Inferenz-GPUs bleiben komplett, MIG deaktiviert.

Ablauf (adressiert über die UUID der Service-GPU):

MIG-Modus auf der Service-GPU aktivieren; die Inferenz-GPU(s) unangetastet lassen.
GPU-Instanzen im vorgesehenen Profil anlegen (1g.35gb bzw. 3g.40gb) und die zugehörigen Compute-Instanzen.
Den GPU Operator für gemischte MIG-Erkennung konfigurieren (MIG-Strategie mixed), damit komplette GPUs und MIG-Instanzen gemeinsam angeboten werden; die GPU-Erkennungskomponenten neu laden.
Prüfen, dass Kubernetes die Ressourcen unter Capacity und Allocatable anbietet.

Die genauen nvidia-smi mig-Befehle und Profilnamen stehen im MIG User Guide; welche Profile eine GPU unterstützt, listet nvidia-smi mig -lgip. Die NVIDIA-GPU-Systemkomponenten können für die gemischte Erkennung erhöhte Host-Rechte benötigen.

7. Prüfen

nvidia-smi -L
kubectl describe node <node-name> | grep -A8 -E "Capacity|Allocatable"

Erwartete Ressourcen je Konfiguration:

Konfiguration	`nvidia.com/gpu`	MIG-Ressource
2 × H200	1	`nvidia.com/mig-1g.35gb: 4`
4 × H100 SXM	2	`nvidia.com/mig-3g.40gb: 4`
Konfigurationen mit dedizierter Service-GPU ohne MIG	Anzahl aller GPUs	–

Testlauf im Cluster:

kubectl run gpu-test --image=nvidia/cuda:12.9.0-base-ubuntu22.04 --rm -it --restart=Never -- nvidia-smi

Häufige Fehlerbilder

Symptom	Ursache	Lösung
`nvidia-smi: command not found`	Treiber nicht installiert	Schritt 2
„couldn't communicate with the NVIDIA driver"	Installation unvollständig	`sudo apt-get purge nvidia-*`, erneut `ubuntu-drivers autoinstall`, Neustart
GPU-Operator-Pods `Pending`, „untolerated taint"	Control-Plane-Taint auf Einzelknoten	Tolerations in den Values (Schritt 5)
`helm install` „context deadline exceeded"	Große Images, langsamer Download	Namespace löschen und neu anlegen, `--timeout 15m`, Pods beobachten
Knoten bietet keine `nvidia.com/gpu` an	Operator nicht bereit oder Treiber-Konflikt	`kubectl get pods -n gpu-operator`, Logs, Knoten-Labels prüfen
MIG-Ressourcen fehlen	Erkennung nicht auf `mixed`, Komponenten nicht neu geladen	MIG-Strategie prüfen, Device-Plugin/GFD neu starten

Ausführliche Entscheidungsbäume (GPU nicht erkannt, CUDA-Versionskonflikt, GPU Operator): Server vorbereiten → Troubleshooting und Troubleshooting.

Festhalten

Treiberversion, CUDA-Version, GPU-Operator-Version, GPU-UUIDs mit Rolle, MIG-Layout. Das gehört ins Manifest der Installation.

Zurück: Server vorbereiten · Weiter: Kubernetes