Dynamo Troubleshoot

Objectif

Transformer une défaillance Dynamo en classe de problème claire, signal le plus fort et action suivante. Commencer par des preuves en lecture seule, éviter les secrets et corriger une couche à la fois.

Prérequis

Python 3.10+ sur la machine opérateur.
kubectl configuré avec accès en lecture à l'espace de noms cible.
Permission de lire les pods, événements, jobs, PVC et ressources DynamoGraphDeployment (PAS les secrets).
Connectivité réseau au serveur API du cluster.

Instructions

1. Collecter un bundle en lecture seule

Exécuter :

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

Si l'utilisateur nomme un déploiement, l'inclure :

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

Ne pas collecter les secrets Kubernetes. Ne pas afficher les tokens Hugging Face.

2. Classifier la défaillance

Utiliser references/failure-decision-tree.md et classifier dans un bucket principal :

cluster/platform
namespace/secret
model cache/PVC/download
image pull/runtime image
GPU scheduling/resources
operator/DynamoGraphDeployment reconciliation
frontend/router
worker/backend
endpoint/API
benchmark/perf job

3. Déboguer de haut en bas

Vérifier dans cet ordre :

espace de noms, classe de stockage, nœuds GPU et existence du secret HF
PVC et job de téléchargement de modèle
statut DynamoGraphDeployment et événements
statut des pods, describe pod et logs des conteneurs
service frontend et port-forward
/v1/models
/v1/chat/completions
job benchmark seulement après que le test de fumée de l'endpoint réussisse

4. Corriger une couche à la fois

Préférer le plus petit changement réversible :

créer un espace de noms manquant ou un secret HF
patcher storageClassName
patcher la balise d'image ou le secret de tirage d'image
réduire la requête GPU seulement si la recette peut rester valide
basculer le routeur KV en mode approximatif seulement si les workers ne publient pas d'événements
redémarrer les jobs échoués après correction de la configuration sous-jacente

Après chaque correction, réexécuter la vérification de disponibilité pertinente avant d'aller plus loin.

Scripts disponibles

Script	Objectif	Arguments
`scripts/collect_dynamo_debug_bundle.py`	Collecter un bundle de débogage en lecture seule (pods, événements, jobs, PVC, statut CR)	`--namespace`, `--deployment-name`, `--output-dir`

Invoquer via le protocole run_script() d'agentskills.io :

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

Exemples

Collecter tout dans un espace de noms pour triage :

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

Limiter à un seul déploiement défaillant :

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

Équivalent via le protocole agent :

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

Contrat de sortie

Retourner :

classe de problème
preuves vérifiées
signal le plus fort
cause probable
commande exacte ou patch suivant
ce qui a été écarté
si c'est sûr de continuer le déploiement ou le benchmark

Limitations

Lecture seule. Ne mute jamais le cluster ; les commandes de remédiation sont retournées, non exécutées.
Ne collectera pas les secrets ni n'affichera les tokens Hugging Face ; certains modes de défaillance (authentification) peuvent nécessiter une inspection côté utilisateur.
La taille du bundle augmente avec la taille du déploiement ; sur très grands espaces de noms, limiter avec --deployment-name.
Ne valide pas le transport disagg — utiliser dynamo-interconnect-check pour cela.

Dépannage

Symptôme	Cause probable	Étape suivante
`kubectl` retourne Forbidden sur events/pods	Le compte de service manque RBAC en lecture	Demander à l'opérateur une liaison de rôle en lecture seule sur l'espace de noms
Bundle manquant `DynamoGraphDeployment` status	Opérateur non installé ou espace de noms différent	Vérifier que l'opérateur `dynamo-platform` est installé et surveille l'espace de noms
Job model-download en `Pending`	PVC non lié ou secret HF manquant	Corriger la liaison PVC ou créer le secret HF nommé, puis réexécuter le job
Pods worker en `CrashLoopBackOff`	Incompatibilité image/runtime ou GPU non disponible	Inspecter les logs du conteneur ; vérifier `nvidia.com/gpu` allouable sur les nœuds

Benchmark

Voir BENCHMARK.md pour le rapport de performance NVCARPS-EVAL (généré automatiquement par le pipeline NVSkills CI). Pour actualiser, réexécuter /nvskills-ci sur une PR upstream touchant cette skill.

Références

Lire references/failure-decision-tree.md pour les vérifications spécifiques à chaque bucket.
Utiliser scripts/collect_dynamo_debug_bundle.py pour la collecte de bundle en lecture seule.

dynamo-troubleshoot