dynamo-troubleshoot

Dynamo のトラブルシューティング

目的

Dynamo の障害を、明確な問題分類、最も強い兆候、次のアクションに結び付けます。まず読み取り専用の証拠から確認し、シークレットを避け、一度に一つのレイヤーを修正します。

前提条件

• 操作マシンに Python 3.10 以降がインストールされていること。
• 対象の名前空間への読み取りアクセス権を持つように kubectl が設定されていること。
• ポッド、イベント、ジョブ、PVC、DynamoGraphDeployment リソースを読み取る権限（シークレットは対象外）。
• クラスター API サーバーへのネットワーク到達性があること。

手順

1. 読み取り専用バンドルを収集する

次を実行します。

python3 scripts/collect_dynamo_debug_bundle.py \
  --namespace "${NAMESPACE}"

ユーザーがデプロイメントを指定した場合は、それも含めます。

python3 scripts/collect_dynamo_debug_bundle.py \
  --namespace "${NAMESPACE}" \
  --deployment-name <deployment-name>

Kubernetes のシークレットは収集しないでください。Hugging Face トークンを出力しないでください。

2. 障害を分類する

references/failure-decision-tree.md を使用し、次のいずれかを主要な分類として選びます。

• クラスター／プラットフォーム
• 名前空間／シークレット
• モデルキャッシュ／PVC／ダウンロード
• イメージのプル／ランタイムイメージ
• GPU のスケジューリング／リソース
• オペレーター／DynamoGraphDeployment の調整
• フロントエンド／ルーター
• ワーカー／バックエンド
• エンドポイント／API
• ベンチマーク／パフォーマンスジョブ

3. 上位レイヤーから順にデバッグする

次の順番で確認します。

1. 名前空間、ストレージクラス、GPU ノード、HF シークレットの有無
2. PVC とモデルダウンロードジョブ
3. DynamoGraphDeployment のステータスとイベント
4. ポッドのステータス、describe pod、コンテナログ
5. フロントエンドサービスとポートフォワード
6. /v1/models
7. /v1/chat/completions
8. エンドポイントのスモークテストに合格した後に限り、ベンチマークジョブを実行

4. 一度に一つのレイヤーだけを修正する

最小限で、元に戻せる変更を優先します。

• 不足している名前空間または HF シークレットを作成する
• storageClassName を修正する
• イメージタグまたはイメージプルシークレットを修正する
• レシピの有効性を維持できる場合に限り、GPU リクエストを減らす
• ワーカーがイベントを公開していない場合に限り、KV ルーターを近似モードに切り替える
• 根本原因となる設定を修正してから、失敗したジョブを再起動する

修正するたびに、次のレイヤーに進む前に、該当するレディネスチェックを再実行します。

利用可能なスクリプト

スクリプト	目的	引数
scripts/collect_dynamo_debug_bundle.py	読み取り専用のデバッグバンドルを収集します（ポッド、イベント、ジョブ、PVC、CR のステータス）	--namespace、--deployment-name、--output-dir

agentskills.io の run_script() プロトコル経由で呼び出します。

run_script("scripts/collect_dynamo_debug_bundle.py", args=["--namespace", "dynamo-demo"])

使用例

トリアージのため、名前空間内のすべての情報を収集します。

python3 scripts/collect_dynamo_debug_bundle.py --namespace dynamo-demo

失敗している単一のデプロイメントに絞り込みます。

python3 scripts/collect_dynamo_debug_bundle.py \
  --namespace dynamo-demo \
  --deployment-name qwen-vllm-disagg

エージェントプロトコル経由での同等の実行方法です。

run_script("scripts/collect_dynamo_debug_bundle.py", args=["--namespace", "dynamo-demo", "--deployment-name", "qwen-vllm-disagg"])

出力要件

次の内容を返します。

• 問題分類
• 確認した証拠
• 最も強い兆候
• 考えられる原因
• 次に実行する正確なコマンドまたは適用するパッチ
• 除外できた原因
• デプロイメントまたはベンチマークを続行しても安全かどうか

制限事項

• 読み取り専用です。クラスターを変更することはありません。修復コマンドは実行せず、提示します。
• シークレットの収集や Hugging Face トークンの出力は行いません。一部の障害モード（認証）では、ユーザー側での確認が必要になる場合があります。
• バンドルのサイズはデプロイメントの規模に応じて大きくなります。非常に大きな名前空間では、--deployment-name で範囲を絞り込んでください。
• 分離トランスポートの検証は行いません。その場合は dynamo-interconnect-check を使用してください。

トラブルシューティング

症状	考えられる原因	次の手順
イベントまたはポッドに対して kubectl が Forbidden を返す	サービスアカウントに読み取り RBAC 権限がない	オペレーターに、名前空間で読み取り専用のロールバインディングを設定するよう依頼してください
バンドルに DynamoGraphDeployment のステータスが含まれていない	オペレーターがインストールされていないか、名前空間が異なる	dynamo-platform オペレーターがインストールされ、その名前空間を監視していることを確認してください
モデルダウンロードジョブが Pending になっている	PVC がバインドされていないか、HF シークレットがない	PVC のバインドを修正するか、指定された HF シークレットを作成してから、ジョブを再実行してください
ワーカーポッドが CrashLoopBackOff になっている	イメージ／ランタイムの不一致、または GPU を利用できない	コンテナログを確認し、ノードで nvidia.com/gpu の割り当て可能数を確認してください

ベンチマーク

NVCARPS-EVAL のパフォーマンスレポート（NVSkills CI パイプラインにより自動生成）については、BENCHMARK.md を参照してください。更新するには、このスキルに関係する上流 PR で /nvskills-ci を再実行してください。

参考資料

• 分類ごとの確認項目については、references/failure-decision-tree.md を参照してください。
• 読み取り専用バンドルの収集には、scripts/collect_dynamo_debug_bundle.py を使用してください。