GPU sunucu kurulumu: Ubuntu 24.04'te NVIDIA sürücüsü, CUDA ve NVIDIA Container Toolkit ile ilk hazırlık

Yeni teslim aldığınız bir GPU sunucuda kart donanım olarak görünür. Ama yapay zeka işlerinde kullanılabilmesi için sürücü, CUDA ve Docker katmanlarının doğru sırayla kurulması gerekir. Sıra karışırsa ya da sürümler birbirini ezerse ilk çekirdek güncellemesinde nvidia-smi hata verir. Bu rehber, Ubuntu 24.04 üzerinde GPU sunucu kurulumu yapacak sistem yöneticileri için hazırlandı. Ön kontrolü, sürücü seçimini, CUDA Toolkit'i, sürüm sabitlemeyi, NVIDIA Container Toolkit'i ve doğrulama adımlarını kapsar.

Ön koşullar

• Ubuntu 24.04 LTS kurulu, sudo yetkili bir kullanıcı ve SSH erişimi. Temel sıkılaştırmayı henüz yapmadıysanız önce Linux sunucu ilk kurulum betiği yazısındaki adımları uygulayın.
• Sağlayıcı panelinden ya da IPMI/iKVM üzerinden konsol erişimi. Sürücü kurulumundan sonra sunucu açılmazsa SSH işe yaramaz, konsol gerekir.
• Kartın gerçekten size ayrılmış fiziksel bir GPU olduğundan emin olun. Paylaşımlı vGPU dilimlerinde sürücü kurulumu sağlayıcının belirlediği şekilde yapılır. Farkı APU, vGPU ve ayrılmış GPU karşılaştırması yazısında bulabilirsiniz.
• Docker Engine kurulu olmalı. Kurulu değilse Docker'ın Ubuntu kurulum belgesini izleyin.

GPU sunucu kurulumuna başlamadan önce: kart, Ubuntu sürümü ve nouveau kontrolü

İlk iş, sunucunun mevcut durumunu değiştirmeden okumaktır. Bazı imajlarda sağlayıcı sürücüyü önceden kurmuş olabilir. Üstüne ikinci bir sürücü kurmak en sık görülen bozulma nedenidir.

Aşağıdaki betik Ubuntu 24.04 için hazırlandı ve yalnız okuma yapar. Sistemde hiçbir şeyi değiştirmez, bu yüzden geri alınacak bir adım yoktur.

#!/usr/bin/env bash
# gpu-onkontrol.sh: GPU sunucu ön kontrolü. Yalnız okur, hiçbir ayarı değiştirmez.
set -u

echo "== İşletim sistemi ve çekirdek =="
. /etc/os-release && echo "$PRETTY_NAME"
uname -r

echo "== NVIDIA aygıtları (PCI) =="
lspci -nn | grep -i nvidia || echo "NVIDIA aygıtı görünmüyor"

echo "== nouveau modülü =="
if lsmod | grep -q '^nouveau'; then echo "nouveau YÜKLÜ"; else echo "nouveau yüklü değil"; fi

echo "== Secure Boot =="
if command -v mokutil >/dev/null; then mokutil --sb-state; else echo "mokutil kurulu değil"; fi

echo "== Kurulu NVIDIA ve CUDA paketleri =="
dpkg-query -W -f='${db:Status-Abbrev} ${Package} ${Version}\n' 2>/dev/null \
  | awk '$1=="ii" && $2 ~ /nvidia|cuda/ {print $2, $3}'

echo "== Ubuntu'nun önerdiği sunucu sürücüleri =="
if command -v ubuntu-drivers >/dev/null; then
  ubuntu-drivers list --gpgpu 2>/dev/null
else
  echo "ubuntu-drivers-common kurulu değil (sudo apt install ubuntu-drivers-common)"
fi

Çıktıyı şu ölçütlerle okuyun:

• PCI listesinde kart yoksa sürücü kurmanın anlamı yok. Sorun donanım ya da sanallaştırma katmanındadır, sağlayıcıyla görüşün.
• nouveau yüklüyse endişelenmeyin. Ubuntu'nun NVIDIA paketleri nouveau'yu kara listeye ekler ve yeniden başlatmadan sonra devre dışı kalır. Elle blacklist dosyası yazmanız gerekmez.
• Secure Boot açıksa Ubuntu deposundaki önceden derlenmiş ve imzalı çekirdek modüllerini kullanmak işinizi kolaylaştırır. Aşağıdaki sürücü seçiminde bu yüzden ubuntu-drivers önerilir.
• Kurulu NVIDIA paketi varsa önce bunların hangi kaynaktan geldiğini öğrenin. Var olan kurulumu bozmadan devam etmek genellikle sıfırdan kurmaktan daha güvenlidir.

NVIDIA sürücüsü: ubuntu-drivers mi, nvidia-open mı, server sürümü mü?

Ubuntu 24.04'te sürücüyü üç yoldan kurabilirsiniz. Kararı vermeden önce artı ve eksilerine bakın.

Sunucu için önerilen yol ilk satırdır. Bu yolda iki seçim daha yaparsınız:

Server dalı mı, masaüstü dalı mı? Adında -server geçen paketler NVIDIA'nın veri merkezi için uzun süre desteklenen dallarını izler. Hesaplama amaçlı sunucuda bunları seçin.

Açık modül mü, kapalı modül mü? Adında -open geçen paketler NVIDIA'nın açık kaynak çekirdek modülünü kullanır. NVIDIA, Turing ve sonrası mimariler için açık modülü öneriyor ve en yeni mimarilerde yalnız açık modül destekleniyor. H100 ve H200 gibi Hopper kartlarda -server-open varyantını seçmek mantıklı bir varsayılandır. Kartınızın durumunu NVIDIA'nın sürücü belgesinden kontrol edin.

Aşağıdaki komutlar Ubuntu 24.04 için hazırlandı. ORNEK_SURUM yerine ubuntu-drivers list --gpgpu çıktısında gördüğünüz sürüm numarasını yazın. Sürüm uydurmayın, listedekini kullanın.

# Paket listesini güncelle ve aracı kur (zaten kuruluysa değişiklik yapmaz)
sudo apt update
sudo apt install -y ubuntu-drivers-common pciutils

# Sunucu (gpgpu) sürücülerini listele
sudo ubuntu-drivers list --gpgpu

# Listede gördüğünüz ana sürümü yazın, örneğin listede
# "nvidia-driver-ORNEK_SURUM-server-open" varsa yalnız sayıyı alın
SURUM=ORNEK_SURUM

# Sürücüyü ve önceden derlenmiş çekirdek modülünü kur
sudo ubuntu-drivers install --gpgpu "nvidia:${SURUM}-server-open"

# --gpgpu kurulumu nvidia-smi aracını otomatik getirmez, ayrıca kurun
sudo apt install -y "nvidia-utils-${SURUM}-server"

# Modülün yüklenmesi için yeniden başlat
sudo reboot

Geri almak için önce kurulan paketleri görün: dpkg -l | grep -E "nvidia.*${SURUM}". Ardından yalnız bu paketleri sudo apt purge ile kaldırıp sudo apt autoremove çalıştırın ve yeniden başlatın. Joker karakterle toplu silme yapmayın, listeyi gözle kontrol edin.

Çok kartlı sunucularda Fabric Manager ve persistence

NVLink ve NVSwitch ile bağlı çok GPU'lu (HGX tipi) sunucularda kartların birbirini görmesi için nvidia-fabricmanager servisi gerekir. Bu servisin sürümü sürücüyle birebir aynı olmalıdır. Tek kartlı ya da PCIe kartlı sunucularda bu adımı atlayın.

# Yalnız NVSwitch'li çok GPU'lu sunucular için. SURUM, sürücüyle aynı olmalı.
sudo apt install -y "nvidia-fabricmanager-${SURUM}"
sudo systemctl enable --now nvidia-fabricmanager

# Kartların sürekli hazır kalması için persistence servisi (tüm GPU sunucularda önerilir)
sudo systemctl enable --now nvidia-persistenced

Geri almak için sudo systemctl disable --now nvidia-fabricmanager komutunu, aynı şekilde nvidia-persistenced için de çalıştırmanız yeterlidir.

CUDA Toolkit'i NVIDIA deposundan kurma ve PATH ayarı

Önemli bir ayrım var. Docker içinde çalışan PyTorch, vLLM ya da Ollama gibi araçlar CUDA kütüphanelerini kendi imajlarında taşır. Sunucuya CUDA Toolkit kurmanız yalnız konteyner dışında nvcc ile derleme yapacaksanız gerekir. Yalnız konteyner kullanacaksanız bu bölümü atlayabilirsiniz.

Toolkit'i NVIDIA'nın deposundan kurarken en kritik kural şudur: cuda ya da cuda-drivers meta paketini kurmayın. Bu paketler sürücüyü de getirir ve az önce Ubuntu deposundan kurduğunuz sürücünün üstüne yazar. Yalnız cuda-toolkit-X-Y biçimindeki paketi kurun.

Aşağıdaki adımlar Ubuntu 24.04 x86_64 için hazırlandı. Keyring paketinin adı zamanla değişebilir. Güncel adı NVIDIA CUDA Linux kurulum belgesinden kontrol edin.

# NVIDIA CUDA deposunun anahtarını ve kaynak tanımını ekleyen paket
cd /tmp
wget -q 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 update

# Depodaki toolkit sürümlerini listele
apt-cache search --names-only '^cuda-toolkit-[0-9]+-[0-9]+$'

# Listeden seçtiğiniz sürümü yazın (ör. listede cuda-toolkit-X-Y görünüyorsa "X-Y")
CUDA_SURUM=ORNEK_X-Y
sudo apt install -y "cuda-toolkit-${CUDA_SURUM}"

# nvcc'nin PATH'te bulunması için tüm kullanıcılara geçerli ayar (dosyayı her seferinde yeniden yazar)
echo 'export PATH=/usr/local/cuda/bin${PATH:+:${PATH}}' | sudo tee /etc/profile.d/cuda.sh >/dev/null

Oturumu kapatıp açtıktan sonra nvcc --version çalışmalıdır. Geri almak için sudo apt purge "cuda-toolkit-${CUDA_SURUM}" ve sudo apt autoremove çalıştırın, /etc/profile.d/cuda.sh dosyasını silin. Depoyu kullanmayacaksanız sudo apt purge cuda-keyring da çalıştırın.

Toolkit sürümünü seçerken sürücünün desteklediği en yüksek CUDA sürümünü aşmayın. nvidia-smi çıktısının sağ üstündeki "CUDA Version" alanı kurulu toolkit'i değil, sürücünün desteklediği en yüksek sürümü gösterir. Toolkit bu değere eşit ya da ondan düşük olmalıdır.

Sürücü ve CUDA sürümünü apt-mark hold ile sabitleme

Üretimdeki bir GPU sunucuda sürücünün kendiliğinden güncellenmesini istemezsiniz. Güncellemeden sonra yeniden başlatılmayan sunucuda kullanıcı alanı kütüphanesi ile çekirdek modülü farklı sürümlerde kalır ve tüm GPU işleri durur.

Burada bir tuzak var. Yalnız NVIDIA paketlerini sabitleyip çekirdeği serbest bırakırsanız yeni çekirdek gelir, ama ona uygun NVIDIA modülü gelmez. Bu yüzden çekirdek meta paketlerini de birlikte sabitleyin ve hepsini bakım penceresinde birlikte güncelleyin.

Aşağıdaki betik Ubuntu 24.04 için hazırlandı ve tekrar çalıştırılabilir. Zaten sabitlenmiş paketleri yeniden sabitlemek bir şey değiştirmez.

#!/usr/bin/env bash
# gpu-sabitle.sh: NVIDIA, CUDA ve çekirdek meta paketlerini birlikte sabitler.
set -euo pipefail

PAKETLER=$(dpkg-query -W -f='${db:Status-Abbrev} ${Package}\n' \
  | awk '$1=="ii" && ($2 ~ /nvidia|libnvidia|^cuda-toolkit-/ || $2 ~ /^linux-(generic|image-generic|headers-generic)$/) {print $2}')

echo "Sabitlenecek paketler:"
echo "$PAKETLER"

# Paketleri hold durumuna al
echo "$PAKETLER" | xargs -r sudo apt-mark hold

# Sonucu göster
apt-mark showhold

Geri almak için aynı listeyi sudo apt-mark unhold ile serbest bırakın. Bakım penceresinde güncelleme şu sırayla yapılmalı: unhold, sudo apt update && sudo apt full-upgrade, yeniden başlatma, doğrulama bölümündeki kontroller ve son olarak betiği yeniden çalıştırarak hold.

NVIDIA Container Toolkit ile Docker'da GPU kullanımı

NVIDIA Container Toolkit, Docker'ın konteynerlere GPU aygıtlarını ve sürücü kütüphanelerini bağlamasını sağlar. Konteyner içine sürücü kurulmaz. Sürücü her zaman sunucudadır.

Paket, NVIDIA'nın ayrı bir apt deposundan gelir. Depo anahtarını ve kaynak tanımını eklemek için NVIDIA Container Toolkit kurulum belgesindeki "With apt: Ubuntu, Debian" bölümünde yer alan güncel komutları kullanın. Depo adresi ve anahtar yolu zamanla değişebildiği için bu komutları buraya kopyalamak yerine belgeden almak daha güvenlidir. Belgedeki adımlar sonunda /etc/apt/sources.list.d/nvidia-container-toolkit.list dosyası oluşur.

Depo eklendikten sonraki adımlar aşağıdadır. Betik Ubuntu 24.04 ve Docker Engine için hazırlandı. Tekrar çalıştırılabilir: paket kuruluysa apt değişiklik yapmaz, yedek dosyası varsa üstüne yazılmaz. nvidia-ctk komutu /etc/docker/daemon.json dosyasını değiştirdiği için önce yedek alınıyor.

#!/usr/bin/env bash
# nvidia-ctk-kur.sh: Container Toolkit'i kurar ve Docker'a nvidia runtime'ını tanıtır.
set -euo pipefail

# Depo tanımı yoksa dur: önce NVIDIA belgesindeki depo ekleme adımlarını uygulayın
if [ ! -f /etc/apt/sources.list.d/nvidia-container-toolkit.list ]; then
  echo "NVIDIA Container Toolkit deposu tanımlı değil. Önce resmi belgedeki depo adımlarını uygulayın."
  exit 1
fi

sudo apt update
sudo apt install -y nvidia-container-toolkit

# Docker ayar dosyasının yedeği (dosya yoksa ya da yedek zaten varsa adım atlanır)
if [ -f /etc/docker/daemon.json ] && [ ! -f /etc/docker/daemon.json.yedek ]; then
  sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.yedek
fi

# Docker'a nvidia runtime'ını tanıt ve Docker'ı yeniden başlat
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Kurulan sürümü göster
nvidia-ctk --version

Geri almak için yedeği geri koyun (sudo cp /etc/docker/daemon.json.yedek /etc/docker/daemon.json). Yedek yoksa nvidia-ctk'nın eklediği runtimes bölümünü dosyadan elle çıkarın. Ardından Docker'ı yeniden başlatın ve sudo apt purge nvidia-container-toolkit çalıştırın. Docker'ın yeniden başlatılması çalışan konteynerleri durdurur. Bu adımı canlı iş varken yapmayın.

Docker Compose'da GPU tanımı ve birden fazla kartta kart seçimi

Önce kartların sırasını ve UUID'lerini görün:

nvidia-smi -L

Tek bir docker run için kart seçimi:

# Tüm kartlar
docker run --rm --gpus all ubuntu nvidia-smi -L
# Yalnız 0 ve 1 numaralı kartlar
docker run --rm --gpus '"device=0,1"' ubuntu nvidia-smi -L

Compose dosyasında GPU tanımı deploy.resources.reservations.devices altında yapılır. Aşağıdaki örnek, servisi yalnız 0 numaralı karta bağlar:

services:
  model-servisi:
    image: ubuntu
    command: ["nvidia-smi"]
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ["0"]      # tüm kartlar için bu satır yerine: count: all
              capabilities: [gpu]

Birden fazla modeli aynı sunucuda çalıştıracaksanız her servise ayrı kart vermek, bellek çakışmasını önlemenin en basit yoludur. Sıra numarası yerine nvidia-smi -L çıktısındaki UUID'yi yazarsanız, sunucu yeniden başladığında kart sırası değişse bile servis aynı karta bağlanır. Hangi modelin kaç GB bellek isteyeceğini önceden hesaplamak için LLM VRAM hesaplama yazısına bakabilirsiniz.

Kurulumu doğrulama: nvidia-smi, nvcc ve test konteyneri

Her yeniden başlatmadan ve her bakım penceresinden sonra aynı üç kontrolü yapın.

1. Sürücü ve kartlar:

nvidia-smi --query-gpu=index,name,uuid,driver_version,memory.total,persistence_mode --format=csv

Beklenen: her kart için bir satır, tüm satırlarda aynı sürücü sürümü, kartın belirtilen kapasitesine yakın bir bellek değeri ve persistence_mode alanında Enabled. Satır sayısı sözleşmedeki kart sayısından azsa durun ve sağlayıcıyla görüşün.

Çok kartlı sunucularda bağlantı topolojisini de görün:

nvidia-smi topo -m

NVLink ile bağlı kartlar arasında NV ile başlayan değerler görünmelidir. NVSwitch'li sistemde bunun yerine yalnız PCIe yolları görünüyorsa Fabric Manager çalışmıyor olabilir. systemctl status nvidia-fabricmanager ile kontrol edin.

2. CUDA Toolkit (kurduysanız):

nvcc --version

Beklenen: kurduğunuz cuda-toolkit sürümüyle uyumlu bir "release" satırı. command not found alıyorsanız PATH ayarı oturuma yansımamıştır. Oturumu yeniden açın.

3. Konteyner içinden GPU erişimi:

docker run --rm --gpus all ubuntu nvidia-smi

Beklenen: sunucuda gördüğünüz tabloyla aynı kartlar ve aynı sürücü sürümü. Bu çıktıyı görüyorsanız sürücü, Container Toolkit ve Docker katmanı birlikte çalışıyor demektir.

Sık hatalar: Secure Boot, çekirdek güncellemesi sonrası kaybolan sürücü, sürüm uyumsuzluğu

"NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver": Modül yüklenmemiştir. Önce uname -r ile çalışan çekirdeği, sonra dpkg -l | grep linux-modules-nvidia ile bu çekirdeğe ait modül paketinin olup olmadığını kontrol edin. Çekirdek güncellenmiş ama modül gelmemişse sabitleme bölümündeki tuzağa düşülmüştür. Çekirdek ve NVIDIA paketlerini birlikte güncelleyin. DKMS kullanan kurulumlarda dkms status çıktısında yeni çekirdek için "installed" satırı olmalıdır.

Secure Boot açıkken modül yüklenmiyor: mokutil --sb-state "enabled" diyor ve dmesg | grep -i nvidia çıktısında imza hatası görüyorsanız modül imzasızdır. Bu genellikle NVIDIA deposundan DKMS ile kurulan sürücüde olur. En temiz çözüm, Ubuntu deposundaki imzalı modüllere dönmektir. Alternatif olarak MOK anahtarı kaydı yapılabilir, ama bu adım yeniden başlatma sırasında konsoldan onay ister.

"Failed to initialize NVML: Driver/library version mismatch": Kullanıcı alanı kütüphanesi güncellenmiş, çekirdek modülü eski sürümde kalmıştır. Çözüm yeniden başlatmaktır. Tekrarlamaması için paketleri sabitleyin ve otomatik güncellemenin NVIDIA paketlerine dokunmadığından emin olun.

"could not select device driver "" with capabilities: [[gpu]]": Docker, NVIDIA runtime'ını tanımıyor. nvidia-ctk runtime configure --runtime=docker adımı atlanmış ya da Docker yeniden başlatılmamıştır.

İki kaynaktan sürücü: Ubuntu deposundan sürücü kurulduktan sonra NVIDIA deposundan cuda meta paketinin kurulması, iki farklı sürücü paketinin çakışmasına yol açar. dpkg -l | grep nvidia-driver çıktısında tek bir sürücü paketi görmelisiniz.

Toolkit sürücüden yeni: Konteyner ya da uygulama "CUDA driver version is insufficient" benzeri bir hata veriyorsa, kullandığınız CUDA sürümü sürücünün desteklediği sürümden yenidir. Ya daha eski CUDA tabanlı bir imaj seçin ya da bakım penceresinde sürücüyü yükseltin.

Sık sorulan sorular

Docker kullanacaksam sunucuya CUDA Toolkit kurmam gerekir mi?

Hayır. Konteyner imajları CUDA kütüphanelerini kendi içinde taşır, sunucuda yalnız sürücü ve NVIDIA Container Toolkit gerekir. Toolkit'i yalnız konteyner dışında derleme yapacaksanız kurun.

nvidia-smi'deki CUDA sürümü ile nvcc'nin gösterdiği sürüm neden farklı?

nvidia-smi sürücünün desteklediği en yüksek CUDA sürümünü, nvcc ise kurulu toolkit sürümünü gösterir. Toolkit sürümünün sürücü değerine eşit ya da ondan düşük olması normaldir.

Açık (open) modül mü seçmeliyim, kapalı mı?

Turing ve sonrası kartlarda NVIDIA açık modülü öneriyor, en yeni mimarilerde ise yalnız açık modül destekleniyor. H100 ve H200 gibi veri merkezi kartlarında -server-open varyantı iyi bir varsayılandır. Eski bir kartınız varsa NVIDIA'nın destek listesine bakın.

Otomatik güncellemeleri tamamen kapatmalı mıyım?

Gerek yok. Güvenlik güncellemeleri açık kalsın, ama NVIDIA, CUDA ve çekirdek meta paketlerini apt-mark hold ile sabitleyin. Bu paketleri bakım penceresinde birlikte güncelleyip doğrulama adımlarını tekrarlayın.

Çok kartlı sunucuda kartlardan biri nvidia-smi'de görünmüyorsa ne yapmalıyım?

Önce lspci -nn | grep -i nvidia ile kartın PCI seviyesinde görünüp görünmediğini kontrol edin. PCI'da görünüyor ama nvidia-smi'de yoksa dmesg | grep -i nvrm çıktısını sağlayıcıya iletin. PCI'da da yoksa sorun donanım tarafındadır.

Bu işi hazır yapmak isterseniz

Sürücü, CUDA ve Container Toolkit'i kendiniz kurmak yerine hazır bir ortamla başlamak isterseniz Frankfurt'taki (AB) GPU sunucu seçeneklerine bakabilirsiniz. Katalogda NVIDIA H200 var, başka kart modelleri için sayfadaki formdan talep iletebilirsiniz. Teslimden sonra yukarıdaki doğrulama komutlarını yine kendiniz çalıştırmanızı öneririz.

Sonuç

Sağlam bir GPU sunucu kurulumu şu sırayla yapılır: önce mevcut durumu okuyun, sürücüyü Ubuntu deposundan server ve uygunsa open varyantıyla kurun, CUDA Toolkit'i yalnız gerekiyorsa ve sürücüye dokunmadan ekleyin, NVIDIA ile çekirdek paketlerini birlikte sabitleyin, en son Container Toolkit ile Docker'a GPU erişimi verin. Her bakımdan sonra nvidia-smi, nvcc ve test konteyneri kontrollerini tekrarlarsanız sürücü sorunlarını iş durmadan önce yakalarsınız.