Guide de Débogage des Clusters HyperShift

Cette compétence fournit des workflows de débogage structurés pour les problèmes courants de clusters hébergés HyperShift.

Quand utiliser cette compétence

Cette compétence s'applique automatiquement quand :

• Vous investigez des problèmes de suppression de clusters hébergés
• Vous déboguez des ressources bloquées ou des finaliseurs
• Vous dépannez des problèmes de plan de contrôle
• Vous analysez des problèmes du cycle de vie NodePool
• Vous examinez les logs des opérateurs pour des problèmes de cluster

Dépannage spécifique au fournisseur

Pour les problèmes spécifiques au fournisseur et les étapes de dépannage détaillées, consultez ces sous-compétences :

• AWS: aws-troubleshooting.md - Problèmes CAPI spécifiques à AWS, nettoyage d'infrastructure et réinstallation

La compétence principale ci-dessous fournit des workflows de débogage indépendants du fournisseur. Quand vous rencontrez des problèmes spécifiques au fournisseur, consultez la sous-compétence pertinente pour les étapes de résolution détaillées.

Composants clés à comprendre

Hiérarchie des ressources

• HostedCluster (HC) : Ressource de cluster principal dans le cluster de gestion
• HostedControlPlane (HCP) : Représentation du plan de contrôle du HC dans l'espace de noms HCP
• NodePool (NP) : Ressources de pool de nœuds worker
• Ressources CAPI : Ressources Cluster API (Cluster, Machine, etc.) dans l'espace de noms HCP

Opérateurs

• hypershift-operator (HO) : Gère les ressources HC et NP
• control-plane-operator (CPO) : Gère les ressources HCP et les composants du plan de contrôle
• hosted-cluster-config-operator (HCCO) : Gère la configuration et les ressources dans le cluster pour les clusters hébergés

Espaces de noms

• Espace de noms HC : Où résident les ressources HostedCluster et NodePool (p. ex. default, clusters)
• Espace de noms HCP : Où les pods du plan de contrôle et les ressources CAPI s'exécutent (p. ex. clusters-<cluster-name>)

Scénarios de débogage courants

Scénario : Cluster hébergé bloqué lors de la suppression

Quand un cluster hébergé est bloqué en état de suppression, suivez ce processus de débogage systématique :

1. Suppression des NodePools

Vérifiez et confirmez que la suppression de NodePool progresse :

# Vérifiez les ressources NodePool dans l'espace de noms HC
kubectl get nodepool -n <hc-namespace>

# Vérifiez l'état de la ressource cluster CAPI dans l'espace de noms HCP
kubectl get cluster -n <hcp-namespace> -o yaml

# Vérifiez les logs du pod CAPI provider
kubectl logs -n <hcp-namespace> deployment/capi-provider

# Vérifiez l'état des machines CAPI dans l'espace de noms HCP
kubectl get machines -n <hcp-namespace>
kubectl describe machines -n <hcp-namespace>

# Examinez les logs de l'opérateur HyperShift pour les problèmes NodePool
kubectl logs -n hypershift deployment/operator --tail=100 | grep -i nodepool
kubectl logs -n hypershift deployment/operator --tail=100 | grep -i <cluster-name>

Éléments à rechercher :

• Finaliseurs bloquant la suppression de NodePool
• Machines CAPI qui ne se terminent pas
• Erreurs du fournisseur empêchant la suppression des machines
• Logs HO montrant des erreurs de réconciliation

2. Suppression de ressource HostedControlPlane

Vérifiez que la ressource HCP et les pods sont nettoyés :

# Vérifiez l'état de la ressource HCP
kubectl get hostedcontrolplane -n <hcp-namespace> -o yaml

# Vérifiez les pods dans l'espace de noms HCP
kubectl get pods -n <hcp-namespace>

# Vérifiez les pods bloqués
kubectl get pods -n <hcp-namespace> --field-selector=status.phase!=Running

# Examinez les logs du control-plane-operator
kubectl logs -n <hcp-namespace> deployment/control-plane-operator --tail=100

Éléments à rechercher :

• Finaliseurs HCP bloquant la suppression
• Pods avec des finaliseurs ou en état Terminating
• Logs CPO montrant des erreurs dans le nettoyage des ressources
• PVC ou autres ressources empêchant la suppression de l'espace de noms

3. Suppression de l'espace de noms HCP

Investiguer pourquoi l'espace de noms HCP n'est pas supprimé :

# Vérifiez l'état de l'espace de noms
kubectl get namespace <hcp-namespace> -o yaml

# Listez toutes les ressources restantes dans l'espace de noms
kubectl api-resources --verbs=list --namespaced -o name | \
  xargs -n 1 kubectl get --show-kind --ignore-not-found -n <hcp-namespace>

# Vérifiez les ressources avec des finaliseurs
kubectl get all -n <hcp-namespace> -o json | \
  jq '.items[] | select(.metadata.finalizers != null) | {kind: .kind, name: .metadata.name, finalizers: .metadata.finalizers}'

# Examinez les logs HO pour le nettoyage de l'espace de noms
kubectl logs -n hypershift deployment/operator --tail=100 | grep -i namespace

Éléments à rechercher :

• Ressources avec des finaliseurs empêchant la suppression
• Ressources API que HO aurait dû nettoyer
• Erreurs de webhook ou de contrôleur d'admission
• Espace de noms bloqué en état Terminating

4. Suppression de ressource HostedCluster

Vérification finale sur la ressource HostedCluster elle-même :

# Vérifiez l'état de HostedCluster
kubectl get hostedcluster -n <hc-namespace> <cluster-name> -o yaml

# Vérifiez les finaliseurs de HostedCluster
kubectl get hostedcluster -n <hc-namespace> <cluster-name> -o jsonpath='{.metadata.finalizers}'

# Examinez les logs HO pour la suppression de HostedCluster
kubectl logs -n hypershift deployment/operator --tail=200 | grep -i "hostedcluster.*<cluster-name>"

Éléments à rechercher :

• Finaliseurs bloquant la suppression de HostedCluster
• Erreurs HO dans la boucle de réconciliation
• Dépendances qui n'ont pas été nettoyées
• Ressources cloud qui n'ont pas pu être supprimées

Liste de vérification de débogage rapide

Lors de l'investigation de problèmes de suppression de cluster :

• [ ] Vérifiez l'état des ressources et les conditions
• [ ] Examinez les logs des opérateurs pertinents (HO, CPO)
• [ ] Inspectez les finaliseurs sur les ressources bloquées
• [ ] Vérifiez que les ressources CAPI se réconcilient
• [ ] Vérifiez les événements indiquant des défaillances
• [ ] Recherchez les erreurs du fournisseur
• [ ] Vérifiez la progression du nettoyage de l'espace de noms
• [ ] Vérifiez les erreurs de webhook ou d'admission

Problèmes courants et résolutions

Problème : NodePool refuse de se supprimer

• Cause : Machines CAPI bloquées en raison d'erreurs du fournisseur
• Résolution : Vérifiez les identifiants du fournisseur, investiguer les erreurs de suppression des machines dans les logs HO

Problème : Machines bloquées en phase « Deleting » avec « WaitingForInfrastructureDeletion »

• Cause : Ressource cluster supprimée avant les ressources machines, bloquant la réconciliation du contrôleur CAPI
• Cause racine : Les contrôleurs de machines CAPI nécessitent que la ressource cluster soit « prête » pour procéder à la suppression
• Symptômes :
  • Les machines montrent InfrastructureReady: 1 of 2 completed
  • Les logs CAPI montrent que la ressource cluster n'est pas prête
  • Les instances continuent de s'exécuter mais le contrôleur ne peut pas les terminer
• Résolution : Le nettoyage spécifique au fournisseur est requis. Consultez le dépannage spécifique au fournisseur :
  • AWS : Consultez aws-troubleshooting.md pour les étapes de résolution détaillées

Problème : Espace de noms HCP bloqué en état Terminating

• Cause : Ressources avec des finaliseurs ou webhooks défaillants
• Résolution : Listez toutes les ressources dans l'espace de noms, supprimez les finaliseurs des ressources orphelines, vérifiez la disponibilité des webhooks

Problème : HostedCluster bloqué avec des finaliseurs

• Cause : Dépendances non complètement nettoyées (NodePools, HCP, ressources cloud)
• Résolution : Vérifiez que toutes les ressources dépendantes sont supprimées, vérifiez les logs HO pour les erreurs de réconciliation

Problème : Pods du plan de contrôle non terminés

• Cause : PVC ou autres ressources avec des finaliseurs de protection
• Résolution : Vérifiez l'état des PVC, examinez les finaliseurs des classes de stockage, inspectez les logs CPO

Scénario : CRDs HyperShift manquantes ou corrompues

Quand les CRDs HyperShift sont supprimées accidentellement ou corrompues (p. ex. après utilisation de hypershift destroy infra), vous devez réinstaller HyperShift.

⚠️ AVERTISSEMENT : La réinstallation de HyperShift doit être un dernier recours. Ne procédez que si les CRDs sont véritablement manquantes ou corrompues et ne peuvent pas être récupérées par d'autres moyens. La réinstallation entraînera des interruptions de service et peut affecter les clusters hébergés existants.

Symptômes :

• Les commandes comme kubectl get hostedclusters échouent avec : error: the server doesn't have a resource type "hostedclusters"
• Les logs de l'opérateur HyperShift montrent des erreurs concernant les CRDs manquantes
• Les CRDs pour HostedCluster, NodePool ou les ressources CAPI sont manquantes

Vérifier les CRDs manquantes :

# Vérifiez si les CRDs critiques de HyperShift existent
kubectl get crd hostedclusters.hypershift.openshift.io
kubectl get crd nodepools.hypershift.openshift.io

# Comptez les CRDs HyperShift (devrait être environ 9)
kubectl get crd | grep hypershift | wc -l

# Comptez les CRDs CAPI (devrait être environ 50)
kubectl get crd | grep cluster.x-k8s.io | wc -l

Résolution : Réinstaller HyperShift

🤖 Note d'Assistant IA : Quand ce scénario est rencontré, Claude doit guider et suggérer les étapes de réinstallation à l'utilisateur mais NE JAMAIS exécuter les commandes de réinstallation lui-même. L'utilisateur doit explicitement exécuter ces commandes. Fournissez des instructions claires et des explications, mais n'utilisez pas l'outil Bash pour effectuer la réinstallation réelle.

Étape 1 : Rassembler les paramètres requis

# Vous aurez besoin de ceux-ci pour la réinstallation :
# - Configuration du fournisseur de stockage OIDC (spécifique au fournisseur, voir ci-dessous)
# - Identifiants du fournisseur (le cas échéant)
# - Tous les flags de configuration personnalisés utilisés dans l'installation d'origine

Paramètres spécifiques au fournisseur :

• AWS : Consultez aws-troubleshooting.md pour les paramètres AWS OIDC S3 spécifiques

Étape 2 : Désinstaller complètement HyperShift

hypershift install render | kubectl delete -f -

Cela va :

• Supprimer le déploiement de l'opérateur HyperShift
• Supprimer toutes les CRDs HyperShift (HostedCluster, NodePool, etc.)
• Nettoyer les ressources RBAC, webhooks et autres composants

Étape 3 : Réinstaller HyperShift

hypershift install \
  [provider-specific-flags] \
  --enable-defaulting-webhook true

Ajoutez tous les autres flags qui faisaient partie de votre installation d'origine.

Installation spécifique au fournisseur :

• AWS : Consultez aws-troubleshooting.md pour un exemple d'installation spécifique à AWS

Étape 4 : Vérifier l'installation

# Vérifiez que l'opérateur s'exécute
kubectl get deploy -n hypershift
kubectl get pods -n hypershift

# Vérifiez que les CRDs sont installées
kubectl get crd | grep hostedcluster
kubectl get crd | grep nodepool
kubectl get crd | grep cluster.x-k8s.io | wc -l

# Testez l'accessibilité de l'API
kubectl get hostedclusters -A

# Vérifiez les logs de l'opérateur pour les erreurs
kubectl logs -n hypershift deployment/operator --tail=50

# Vérifiez que les contrôleurs s'exécutent
kubectl logs -n hypershift deployment/operator --tail=100 | grep "Starting workers"

Résultats attendus après la réinstallation :

• Déploiement de l'opérateur : 2/2 READY
• CRD HostedCluster : Présente
• CRD NodePool : Présente
• CRDs CAPI : environ 50 installées
• CRDs HyperShift : environ 9 au total
• Contrôleurs : HostedCluster, NodePool et autres contrôleurs avec workers démarrés
• Webhooks : Webhook mutant configuré
• API : kubectl get hostedclusters -A retourne avec succès (même si aucun cluster n'existe)

Notes importantes :

• La réinstallation n'affecte PAS les clusters hébergés existants si leurs ressources existent toujours
• Si les CRDs ont été supprimées, toutes les ressources existantes HostedCluster/NodePool ont disparu
• Vous devrez peut-être recréer les clusters hébergés si leurs définitions ont été perdues
• Assurez-vous d'utiliser les mêmes flags de configuration que l'installation d'origine

Conseils de débogage général

Vérification des finaliseurs

# Listez tous les finaliseurs d'une ressource
kubectl get <resource-type> <name> -n <namespace> -o jsonpath='{.metadata.finalizers}'

# Supprimez un finaliseur spécifique (utilisez avec prudence !)
kubectl patch <resource-type> <name> -n <namespace> -p '{"metadata":{"finalizers":null}}' --type=merge

Logs des opérateurs

# Logs de l'opérateur HyperShift avec contexte
kubectl logs -n hypershift deployment/operator --tail=500 --timestamps

# Logs du control-plane-operator
kubectl logs -n <hcp-namespace> deployment/control-plane-operator --tail=500 --timestamps

# Suivez les logs en temps réel
kubectl logs -n hypershift deployment/operator -f

Événements des ressources

# Obtenir les événements pour une ressource spécifique
kubectl describe <resource-type> <name> -n <namespace>

# Obtenir tous les événements dans un espace de noms, triés par heure
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

Conditions et état

# Vérifiez les conditions des ressources
kubectl get <resource-type> <name> -n <namespace> -o jsonpath='{.status.conditions}' | jq .

# Vérifiez une condition spécifique
kubectl get hostedcluster <name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="Available")]}'

Ressources supplémentaires

• Code de l'opérateur HyperShift : hypershift-operator/controllers/hostedcluster/
• Code du control-plane-operator : control-plane-operator/controllers/
• Définitions d'API : api/hypershift/v1beta1/
• Exemples de tests E2E : test/e2e/