Diagnostiquer l'état de la Add-on problèmes d'installation InferenceGatewayConfig ne pas être prêt Per-scheduler échecs L'état de déploiement du planificateur est dégradé Point de terminaison obsolète après le redémarrage d'un module modèle L'authentification JWT renvoie 401 ou 403 Métriques absentes des tableaux de bord Échec des demandes Sélection du point de terminaison de débogage Cycle de vie et nettoyage Collectez les journaux

Guide de dépannage d'Inference Gateway

Présentation : La passerelle d' HyperPod inférence achemine le trafic via trois couches : le Body-Based routeur (BBR), la passerelle avec HTTPRoute et le Endpoint Picker (EPP). Une mauvaise configuration à n'importe quelle couche peut entraîner l'échec des requêtes, le trafic atteignant le mauvais modèle ou une charge inégale entre les pods servant des modèles. Cette section couvre les problèmes liés à la passerelle, au BBR, à la passerelle et HTTPRoute à EPP, ainsi que tous les problèmes qui en découlent. InferencePool

Diagnostiquer l'état de la

Utilisez les commandes suivantes pour inspecter la passerelle et les ressources qu'elle gère.

Répertoriez toutes les InferenceGatewayConfig ressources dans les espaces de noms :


kubectl get inferencegatewayconfig -A

Afficher l'état détaillé, l'état de déploiement par planificateur et les messages de condition pour une passerelle spécifique :


kubectl describe inferencegatewayconfig <name> -n <namespace>

Vérifiez le contrôleur de passerelle et les modules Body-Based du routeur :


kubectl get pods -n hyperpod-inference-system

Vérifiez les ressources de routage en aval générées par le contrôleur :


kubectl get httproute,inferencepool,securitypolicy -A

Inspectez status.conditions et vérifiez celui de chaque planificateur rolloutState (PendingProgressing,Available, ouDegraded). Les raisons de défaillance exploitables figurent dans le message de condition correspondant.

Add-on problèmes d'installation

Problème : des ressources de passerelle sont manquantes ou ne GatewayClass sont pas acceptées après l'installation du module complémentaire HyperPod Inference Amazon EKS.

Symptômes et résolution : kubectl get gatewayclass inference-gateway renvoie NotFound ou affiche la ressourceACCEPTED=False. Cela indique que le module complémentaire n'est pas installé ou que l'installation n'est pas terminée. Réinstallez ou mettez à jour le module complémentaire :


aws eks update-addon --cluster-name $CLUSTER --region $REGION \
  --addon-name amazon-sagemaker-hyperpod-inference \
  --resolve-conflicts OVERWRITE

Vérifiez ensuite que le contrôleur de passerelle est en cours d'exécution :


kubectl rollout status deploy/inference-gateway-controller \
  -n hyperpod-inference-system --timeout=150s

InferenceGatewayConfig ne pas être prêt

Problème : Un InferenceGatewayConfig est créé, mais son status.conditions affichage Accepted=False ouReady=False, ou le, kubectl apply est purement et simplement rejeté par validation.

Symptômes et résolution :

kubectl applyéchoue avecbbr must be enabled when more than one scheduler is defined. Le Body-Based routeur est requis chaque fois que plus d'un planificateur est défini. Définissez spec.bbr.enabled sur true.
kubectl applyéchoue avecmodelName must be unique across schedulers. Deux planificateurs déclarent la même chose. modelName Renommez-en un pour que chaque planificateur ait un nom distinct. modelName
Accepted=False,Reason=InvalidLoraAdapters. Le nom d'un adaptateur LoRa déclaré sous spec.schedulers[].loraAdapters est un doublon entre les planificateurs ou entre en collision avec celui d'un planificateur. modelName Vérifiez le message de condition pour détecter le nom incriminé :
```
kubectl describe inferencegatewayconfig <name> -n <namespace>
```
Accepted=False,Reason=ResourceNamingViolation. Le nom concaténé <config-name>-<scheduler-name> dépasse la limite de 63 caractères des libellés de Kubernetes. Raccourcissez le nom de la configuration ou du planificateur.
Ready=False,Reason=GatewayNotProgrammed. La passerelle n'a pas encore provisionné l'équilibreur de charge. Inspectez la passerelle parent :
```
kubectl get gateway -n hyperpod-inference-system
kubectl describe gateway <name> -n hyperpod-inference-system
```
AdmissionBlocked=True,Reason=WebhookDenied. Un webhook d'admission au cluster rejette le module de passerelle. Le message de condition nomme le webhook incriminé. Supprimez ou corrigez le webhook, puis redémarrez le déploiement de la passerelle afin que le pod soit recréé immédiatement. Le nom du déploiement est généré, recherchez-le d'abord :
```
kubectl -n hyperpod-inference-system get deploy \
  -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name>
```
Puis redémarrez-le :
```
kubectl -n hyperpod-inference-system rollout restart deploy/<gateway-deployment>
```

Per-scheduler échecs

Problème : la condition d'un planificateur spécifique (BackendsReadyLoraSupported, ouPoolReady) indique que le planificateur n'est pas complètement prêt.

Symptômes et résolution :

BackendsReady=False, Reason=NoModelPods ouReason=NoReadyModelPods. Aucune capsule ne correspondspec.schedulers[].modelSelector, ou la capsule correspondante n'est pas encore prête. Comparez les étiquettes des capsules servant les modèles à celles du sélecteur du planificateur :
```
kubectl get pods -n <namespace> --show-labels
```
Déployez les modules servant le modèle et attendez qu'ils soient prêts avant d'appliquer le. InferenceGatewayConfig
BackendsReady=False,Reason=InvalidModelSelector. Le matchLabels ou le matchExpressions dessous modelSelector est mal formé. Corrigez le sélecteur dans la configuration.
LoraSupported=False,Reason=ModelServerLoraDisabled. Le serveur modèle qui soutient ce planificateur n'a pas été démarré avec la prise en charge de LoRa activée. Activez l'indicateur équivalent sur le serveur de modèles (par exemple, --enable-lora pour vLLM) et redémarrez les pods de modèle.
PoolReady=False, Reason=NotFound ouReason=NotAccepted. Le InferencePool ou ses éléments HTTPRoute n'ont pas encore été réconciliés ou acceptés par la passerelle. Inspectez les deux :
```
kubectl get inferencepool,httproute -n <namespace>
```
Si l'une ou l'autre est toujours manquante plusieurs minutes après l'application de la configuration, décrivez la passerelle parent pour vérifier les erreurs d'admission :
```
kubectl describe gateway -n hyperpod-inference-system
```

L'état de déploiement du planificateur est dégradé

Problème : le déploiement d'Endpoint Picker pour un planificateur est bloqué et n'est pas disponible.

Symptômes et résolution : la EPPReady condition sur le planificateur comporte une raison justifiant l'action. Les causes courantes incluent :

L'image du conteneur ne peut pas être extraite.
Les pods s'écrasent en boucle.
Le conteneur présente une erreur de configuration, telle qu'une variable d'environnement, un montage de volume ou une référence secrète non valide.
Le déploiement a dépassé sa date limite de progression.

Utilisez les commandes suivantes pour identifier le planificateur défaillant et inspecter son déploiement :


# List the schedulers reporting Degraded
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{range .status.schedulers[?(@.rolloutState=="Degraded")]}{.name}{"\n"}{end}'

# Describe the scheduler's Endpoint Picker Deployment for pod events and container errors
kubectl describe deploy -n <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>

Point de terminaison obsolète après le redémarrage d'un module modèle

Problème : Une fois qu'un module modèle est supprimé et qu'un module de remplacement est devenu prêt, Endpoint Picker continue à acheminer vers l'adresse IP du module supprimé. Les requêtes renvoient le protocole HTTP 503 ou la connexion est refusée, et la condition ne se rétablit pas d'elle-même.

Résolution : ajoutez une sonde de préparation au module modèle afin que Kubernetes le marque NotReady avant que son adresse IP ne soit supprimée du pool, et n'annonce le module de remplacement que lorsqu'il dessert l'intégralité du trafic. portRéglez sur le point de terminaison de santé du planificateur targetPort et path de votre serveur modèle :


readinessProbe:
  httpGet:
    path: /health
    port: 8000

Solution : si vous ne pouvez pas redéployer le module modèle immédiatement, redémarrez le sélecteur de points de terminaison du planificateur pour le forcer à reconstruire sa liste de points de terminaison à partir de l'ensemble de modules actuel :


kubectl rollout restart deploy -n <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>

L'authentification JWT renvoie 401 ou 403

Problème : spec.auth.jwt est configuré et les demandes sont rejetées avant d'atteindre un modèle, ou la passerelle ne devient jamais prête une fois l'authentification JWT activée.

Symptômes et résolution :

HTTP 401. Le jeton est manquant, a expiré, est mal formé ou sa iss réclamation ne correspond pas au fournisseur configuré. Vérifiez que le client envoie un Authorization: Bearer <token> en-tête et décodez le JWT pour comparer sa iss réclamation. spec.auth.jwt.provider.issuer
HTTP 403. La validation de la signature a échoué, aud ou le jeton requiredClaims ne correspond pas à la configuration du fournisseur. Inspectez la configuration du fournisseur et confirmez que le jeton aud et chaque entrée requiredClaims correspondent :
```
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.auth.jwt.provider}'
```
Gateway ne devient jamais prête lorsque JWT est activé. Un produit généré n'SecurityPolicyest pas accepté par la passerelle. Inspectez les SecurityPolicy ressources pour déterminer la raison de la panne :
```
kubectl get securitypolicy -A
kubectl describe securitypolicy <name> -n <namespace>
```
Une cause fréquente est qu'il spec.auth.jwt.provider.remoteJWKS.uri est inaccessible depuis la passerelle. Vérifiez que l'URI est résolu et renvoie un document JWKS valide.

Métriques absentes des tableaux de bord

Problème : les métriques Endpoint Picker ou Body-Based Router n'apparaissent pas dans votre tableau de bord de surveillance.

Symptômes et résolution : la collecte de métriques est activée par défaut, le side-car OpenTelemetry Collector est donc normalement présent. Vérifiez si le side-car fonctionne sur les deux types de pods et si les métriques ont été explicitement désactivées.

Vérifiez le sidecar sur les modules Body-Based Router :


kubectl -n hyperpod-inference-system get pods \
  -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel

Vérifiez le sidecar sur les pods Endpoint Picker :


kubectl -n <namespace> get pods \
  -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel

Vérifiez si les métriques ont été explicitement désactivées :


kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.observability.metrics.enabled}'

La sortie vide de la dernière commande signifie que le champ n'est pas défini et que les métriques sont activées. Seule une option explicite false désactive le sidecar. Si la valeur estfalse, définissez-la sur le champ true ou supprimez le champ, et le contrôleur injecte le side-car lors de la prochaine réconciliation.

Échec des demandes

Problème : la passerelle est prête, mais les demandes d'inférence échouent.

Symptômes et résolution :

HTTP 404 pour un modèle connu. La model valeur dans le corps de la demande ne correspond exactement à celle d'aucun planificateurmodelName, ou le modèle demandé est servi via un adaptateur LoRa qui n'est pas déclaré sous. spec.schedulers[].loraAdapters Si aucun planificateur ne correspond au modèle demandé et n'spec.bbr.defaultBackendest pas défini, la passerelle renvoie 404. Vérifiez les noms de modèle et les noms d'adaptateurs configurés :
```
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].modelName}'

kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].loraAdapters}'
```
Les demandes sont bloquées puis expirent. Model-serving les pods chargent toujours les poids du modèle ou n'InferencePoolont aucun point de terminaison Ready. Attendez que les modules du modèle soient prêts avant d'appeler le point de terminaison de la passerelle. Utilisez les modelSelector étiquettes du planificateur InferenceGatewayConfig que vous avez sélectionnées comme sélecteur :
```
kubectl get pods -n <namespace> -l <key>=<value>
kubectl logs <pod> -n <namespace>
```

Sélection du point de terminaison de débogage

Problème : le trafic est biaisé vers un petit nombre de modules modèles, ou une requête LoRa est acheminée vers un module qui n'héberge pas l'adaptateur.

Solution : augmentez temporairement la verbosité du journal du Endpoint Picker pour inspecter ses décisions de notation. Définissez logLevel sur le planificateur :


spec:
  schedulers:
    - name: <scheduler-name>
      logLevel: 4

Signification des niveaux de journalisation :

1- Demandez des événements du cycle de vie.
2- Par défaut. Avertissements et refus d'admission.
3- Résumés des résultats sélectionnés et par scoreur.
4- Per-endpoint, les scores par buteur et les totaux pondérés.
5- Protocol-level trace (verbeux).

Inspectez les journaux Endpoint Picker :


kubectl logs -n <namespace> -l app=<scheduler-name>-epp -c epp --tail=200 -f

Revenez logLevel à sa valeur par défaut lorsque l'enquête est terminée pour éviter un volume de log excessif.

Cycle de vie et nettoyage

Problème : la désinstallation ou la mise à niveau du module complémentaire HyperPod Inference Amazon EKS laisse des ressources orphelines dans le cluster ou bloque une installation ultérieure.

Solution : supprimez toujours toutes les InferenceGatewayConfig ressources avant de désinstaller ou de mettre à niveau le module complémentaire. La désinstallation du module complémentaire alors qu'un InferenceGatewayConfig est toujours présent supprime le contrôleur qui possède les finaliseurs de la ressource, ce qui laisse ces ressources bloquées. Terminating


kubectl delete inferencegatewayconfig --all -A
kubectl get inferencegatewayconfig -A

Vérifiez que la deuxième commande ne renvoie aucune ligne avant de poursuivre l'opération du module complémentaire.

Après avoir réinstallé le module complémentaire, répertoriez les ressources dans l'espace de noms de la passerelle et supprimez tout ce qui ne correspond plus à un live : InferenceGatewayConfig


kubectl get deploy,svc,httproute,inferencepool,gateway,configmap \
  -n hyperpod-inference-system

Les certificats ACM émis par le contrôleur ne sont pas supprimés par la désinstallation d'un module complémentaire. Pour les supprimer, filtrez les certificats ACM dans l'API de balisage AWS des groupes de ressources en fonction de la balise CreatedBy=HyperPodInference et supprimez les certificats dont vous n'avez plus besoin.

Collectez les journaux

Utilisez les commandes suivantes pour récupérer les journaux de chaque composant de passerelle :


# Gateway controller
kubectl logs -n hyperpod-inference-system deploy/inference-gateway-controller

# Body-Based Router (deployment name is <gateway-name>-bbr)
kubectl logs -n hyperpod-inference-system deploy/<gateway-name>-bbr -c bbr

# Endpoint Picker for a specific scheduler
kubectl logs -n <namespace> -l app=<scheduler-name>-epp -c epp

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Problèmes de déploiement du préremplissage et du décodage désagrégés (DPR)

Pondération des modèles et mise en cache des images