tao-setup-nvidia-gpu-host

NVIDIA GPU ホストのセットアップ

TAO ワークフローを docker、local-docker、または kubernetes バックエンドで実行する前に、このセットアップスキルを使用してください。ホストの GPU ランタイムを以下の構成に統一します。

• NVIDIA ドライバーブランチ 580（オープンカーネルモジュールを推奨）
• CUDA Toolkit パッケージ cuda-toolkit-13-0
• NVIDIA Container Toolkit 1.19.0
• Docker エンジン — docker／local-docker バックエンドの場合のみ、かつ Docker がインストールされていない場合に限りインストールします。選択されるパッケージはディストリビューションのファミリーによって異なります（Debian 系ではデフォルトで docker.io、RHEL 系では download.docker.com の moby-engine／docker-ce、SUSE 系では docker）。インストールをスキップするには --skip-docker-install を渡してください。

デフォルトでは安全な読み取り専用チェックです。nvidia-smi、CUDA Toolkit のパス、インストール済みの Container Toolkit パッケージのバージョン（dpkg／rpm／nvidia-ctk バイナリのバージョンで確認）、Docker デーモンの NVIDIA ランタイムのみを調べるため、あらゆる Linux ディストリビューションで動作します。

インストールにはユーザーによる明示的な承認が必要です。再実行時に --install を指定してください。以下のディストリビューションファミリーではインストールが自動化されています。

ファミリー	テスト済みのディストリビューション	パッケージマネージャー	備考
debian	Ubuntu 22.04／24.04、Debian 12（および UBUNTU_CODENAME／VERSION_CODENAME 経由の派生版 Pop!_OS、Mint、Zorin、Raspbian、KDE Neon など）	apt-get	NVIDIA の cuda-keyring と Container Toolkit の .list を追加します。Docker は docker.io を使用します（$DOCKER_PACKAGE_DEBIAN で上書き可能）。
rhel	Fedora 39 以降、RHEL／Rocky／AlmaLinux 9 および 10	dnf（または yum）	NVIDIA の cuda-<distro>.repo と Container Toolkit の .repo を追加します。Docker は、利用可能な場合は Fedora の moby-engine、それ以外の場合は download.docker.com の docker-ce を使用します。
suse	openSUSE Leap 15、SLES 15	zypper	同じ NVIDIA の .repo ファイルを追加します。Docker はディストリビューションの docker パッケージを使用します。
other（Arch、Alpine、Gentoo、NixOS、FreeBSD など）	該当なし	該当なし	--install を実行すると、対象バージョンと NVIDIA のインストールガイド URL を示す明確なエラーで終了します。手動でインストールしてから、--check-only を再実行してください。

クイックスタート

スキルバンクのルートから実行します。

# Check the local Docker backend host.
bash skills/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend docker --check-only

# Install or repair after user approval (prompts for confirmation; see the note below for non-interactive runs).
bash skills/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend docker --install

# Check a Kubernetes GPU worker host.
bash skills/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend kubernetes --check-only

⚠️ 注 — 非対話形式での実行（エージェント／スキルの実行）： スキルの実行時にはターミナルがないため、インストーラーの Continue? [y/N] 確認に応答できません。--check-only を実行して不足しているものを確認し、ユーザーから明示的な承認を得た後、--install コマンドに「はい」を自動指定するフラグ（--yes）を追加すると、プロンプトなしで処理が進みます。このフラグはシステムパッケージ（NVIDIA ドライバーブランチ 580、CUDA Toolkit 13.0、NVIDIA Container Toolkit、および Docker バックエンドの場合は Docker）のインストールを自動的に承認し、ホストを変更します。NVIDIA パッケージリポジトリの追加、Docker の再起動、実行ユーザーの docker グループへの追加が行われる場合があるため、自分が管理し、変更する権限のあるホストでのみ実行してください。ユーザーがターミナルで --install を直接実行した場合は、スクリプトが変更を加える前に、正確なパッケージ一覧を表示して確認を求めます。

skills/ を公開しているインストール済みプラグインのコピーでは、次を使用します。

bash skills/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend docker --check-only

ワークフローの要件

Docker および Kubernetes のワークフローでは、GPU 処理を送信する前にチェックを実行する必要があります。

SETUP_SCRIPT="${TAO_SKILL_BANK_ROOT:-$PWD}/skills/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh"
[ -x "$SETUP_SCRIPT" ] || SETUP_SCRIPT="${TAO_SKILL_BANK_ROOT:-$PWD}/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh"

bash "$SETUP_SCRIPT" --backend docker --check-only || {
  echo "MISSING: TAO GPU host runtime is not ready."
  echo "After user approval, run (append --yes for non-interactive agent runs):"
  echo "  bash \"$SETUP_SCRIPT\" --backend docker --install"
  exit 1
}

黙ってインストールしてはいけません。チェックに失敗した場合は、不足しているものを説明し、修正の承認をユーザーに求めてから、インストールコマンドを実行し、チェックを再実行してください。

インストーラーの処理内容

インストーラーは、検出されたディストリビューションファミリーに応じて処理を振り分けます。サポート対象のすべてのファミリーで、NVIDIA の CUDA リポジトリと Container Toolkit リポジトリが未登録の場合は追加し、固定バージョンのランタイムパッケージをインストールします。必要に応じて Docker をインストールし、NVIDIA Docker ランタイムを設定して、実行ユーザーを docker グループに追加します。

共通の手順（すべてのファミリー）：

1. NVIDIA の CUDA リポジトリが未登録の場合は追加します（apt の cuda-keyring deb、dnf/zypper の cuda-<distro>.repo）。
2. NVIDIA の Container Toolkit リポジトリが未登録の場合は追加します（apt の .list、dnf/zypper の .repo）。
3. 実行中のカーネルに対応するカーネルヘッダー／devel パッケージをインストールします。
4. ドライバーのブランチ 580 のパッケージ、cuda-toolkit-13-0、および 1.19.0 に固定された Container Toolkit をインストールします（dpkg のサフィックス付き 1.19.0-1 は、apt 向けに表記された同じアップストリームバージョンです）。
5. Docker バックエンドを使用し、Docker が未インストールの場合は Docker をインストールします（下記のオーバーライド／オプトアウト用フラグを参照）。デーモンを有効化して起動し、systemctl が利用可能な場合は nvidia-ctk runtime configure --runtime=docker を実行して Docker を再起動します。
6. 実行ユーザー（$SUDO_USER が利用可能な場合はそのユーザー、そうでなければ $USER）を docker グループに追加し、以降のシェルで sudo なしで docker を実行できるようにします。オプトアウトするには --skip-docker-group を指定します。新しいグループメンバーシップは現在のシェルには反映されません。ログアウトして再度ログインするか、新しいシェルごとに newgrp docker を実行してください。
7. 再起動前に検証を通過できるよう、modprobe nvidia の実行を試みます。

ファミリーごとのパッケージ選択：

手順	debian-family	rhel-family	suse-family
カーネルヘッダー	linux-headers-$(uname -r)	kernel-devel-$(uname -r)、kernel-headers-$(uname -r)	kernel-default-devel
ドライバー	nvidia-driver-pinning-580、nvidia-open-580（オーバーライド：$NVIDIA_DRIVER_PACKAGE_DEBIAN）	nvidia-driver-cuda、kmod-nvidia-open-dkms（オーバーライド：$NVIDIA_DRIVER_PACKAGE_RHEL、$NVIDIA_DRIVER_KMOD_RHEL）	nvidia-open-driver-G06-signed-kmp-default（オーバーライド：$NVIDIA_DRIVER_PACKAGE_SUSE）
CUDA ツールキット	cuda-toolkit-13-0	cuda-toolkit-13-0	cuda-toolkit-13-0
Container Toolkit	nvidia-container-toolkit=1.19.0-1 + base/tools/libs	nvidia-container-toolkit-1.19.0 + base/tools/libs	rhel と同じ
Docker	docker.io（オーバーライド：$DOCKER_PACKAGE_DEBIAN）	利用可能な場合は Fedora の moby-engine+moby-cli、それ以外は download.docker.com の docker-ce docker-ce-cli containerd.io	docker

検証

インストール後、次のように検証します。

nvidia-smi
/usr/local/cuda-13.0/bin/nvcc --version
docker info --format '{{json .Runtimes}}' | grep nvidia
sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

nvidia-smi の出力にドライバー 580.x と CUDA Version 13.0 が含まれていることを確認します。 nvcc の出力に release 13.0 が含まれていることを確認します。

Kubernetes に関する注意事項

セルフマネージド Kubernetes クラスターでは、すべての GPU ワーカーノードでホストインストーラーを実行するか、NVIDIA GPU Operator またはデバイスプラグインをインストールする前に、同じパッケージ一式をノードイメージに組み込んでください。

ワークフローチェックでは、kubectl が利用可能であるにもかかわらず、クラスターから nvidia.com/gpu の割り当て可能な容量が報告されない場合も警告します。その場合は、ワーカーホストのランタイムの準備ができてから NVIDIA GPU Operator をインストール／設定してください。

helm repo add nvidia https://helm.ngc.nvidia.com/nvidia
helm repo update
helm install --wait gpu-operator -n gpu-operator --create-namespace nvidia/gpu-operator

マネージド Kubernetes プロバイダーでは、ノードイメージまたは GPU Operator のポリシーを通じてドライバーのインストールを管理している場合があります。ユーザーの承認とロールバック計画なしに、プロバイダーが管理する GPU ノードを上書きしないでください。

失敗するケース

サポート対象外のディストリビューション系統：--install は Debian 系、RHEL 系、SUSE 系のホストへのインストールを自動化します。Arch、Alpine、Gentoo、NixOS、FreeBSD、または /etc/os-release がない環境（macOS など）では、スクリプトは 4 つのバージョンターゲットと NVIDIA の公式インストールガイドの URL を示す明確なエラーを表示して終了します。

• https://docs.nvidia.com/cuda/cuda-installation-guide-linux/
• https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
• https://docs.docker.com/engine/install/

これら 4 つのコンポーネントをディストリビューションのパッケージマネージャーでインストールし、スクリプトを --check-only 付きで再実行して確認してください。チェックはどの環境でも実行でき、バイナリ／パッケージデータベースを照会するだけです。そのため、ランタイムを導入すれば、基盤となるディストリビューションにかかわらずワークフローの要件を満たせます。

サポート対象外の Ubuntu／Debian 派生ディストリビューション：ID が pop、mint、zorin、raspbian など、または Debian 系の別の派生ディストリビューションの場合、スクリプトは UBUNTU_CODENAME／VERSION_CODENAME に基づいてホストを公式 Ubuntu／Debian CUDA リポジトリに対応付けます（focal／jammy／noble → Ubuntu 20.04／22.04／24.04、bullseye／bookworm／trixie → Debian 11／12／12）。ホストのコードネームが既知の公式リリースと一致しない場合、--install は上記と同じ手動インストールの案内を表示して終了します。

Docker がインストールされていない：--check-only は MISSING: Docker is not installed と報告し、検出されたディストリビューション系統に応じた正確な再実行コマンドを表示します。既定の --install の処理では、Docker（系統に応じて docker.io／moby-engine／docker-ce／docker）をインストールし、デーモンを有効化して起動し、NVIDIA ランタイムを設定して、実行ユーザーを docker グループに追加します。Docker を自分で管理する場合は、スクリプトを再実行する前にインストールするか、--skip-docker-install を渡してください。

Docker はインストールされているが、docker run にまだ sudo が必要：スクリプトは実行ユーザーを docker グループに追加しますが、Linux でグループメンバーシップが更新されるのは、新しいログインセッションの開始時のみです。ログアウトして再ログインするか、新しいグループメンバーシップが有効になるまで、新しいシェルで newgrp docker を実行してください。

Docker ランタイムがまだ見つからない：Docker を再起動してから、nvidia-ctk runtime configure --runtime=docker を再実行してください。

検出されたドライバーブランチが 580 と異なる：ドライバーブランチは Debian 系では nvidia-open-580 に固定されます。RHEL 系／SUSE 系では、スクリプトは検出されたディストリビューション向けに NVIDIA の CUDA 13.0 リポジトリで提供されている最新のオープンドライバーをインストールします。これは常に 580 以上です。ホストでさらに厳密な固定が必要な場合は、--install の実行前に $NVIDIA_DRIVER_PACKAGE_RHEL／$NVIDIA_DRIVER_KMOD_RHEL／$NVIDIA_DRIVER_PACKAGE_SUSE に使用するパッケージ名を設定してください。

ドライバーはインストールされているが、nvidia-smi が失敗する：sudo modprobe nvidia でモジュールを読み込むか、再起動してください。Secure Boot が有効なシステムでは、MOK の登録が必要になる場合があります。

Kubernetes に GPU の空き容量がない：各 GPU ノードで nvidia-smi を実行してドライバーが動作することを確認し、GPU Operator／デバイスプラグインのポッドとノードラベルを確認してください。