Dépannage de l'architecture Kubeadm : Guide pratique avec commandes concrètes

Introduction

Le dépannage d'un cluster Kubernetes déployé avec kubeadm exige une approche systématique qui relie les symptômes observés aux correctifs vérifiés. Ce guide parcourt l'architecture des clusters basés sur kubeadm, les modes de défaillance courants et les commandes exactes nécessaires pour diagnostiquer et résoudre les problèmes en toute sécurité. À la fin, vous disposerez d'un flux de travail reproductible qui limite le rayon d'impact, protège les données sensibles et vérifie chaque modification avant de déclarer le succès.

Kubeadm est l'outil officiel pour amorcer les clusters Kubernetes, mais il ne gère pas le cycle de vie du cluster après l'initialisation. Les opérateurs doivent donc comprendre comment kubeadm assemble le plan de contrôle et les nœuds de travail, et comment inspecter ces composants lorsque les choses tournent mal. Nous couvrons les inventaires de versions, les chemins de configuration, les techniques de diagnostic, les modes de défaillance et une liste de contrôle opérationnelle, le tout avec des exemples concrets.

Inventaire des versions et de l'environnement

Avant de toucher à quoi que ce soit, vous devez savoir exactement ce que vous exécutez. Commencez par collecter la version de Kubernetes, la version de kubeadm, le runtime de conteneurs et l'état des nœuds. Ces commandes en lecture seule jettent les bases de toutes les décisions ultérieures.

# Version du serveur Kubernetes
kubectl version --short

# Version de kubeadm
kubeadm version

# Runtime de conteneurs (exemple avec containerd)
ctr version

# État et détails des nœuds
kubectl get nodes -o wide

La sortie attendue doit montrer une version cohérente sur tous les nœuds, par exemple v1.29.1. Si vous constatez une discordance entre le client et le serveur kubectl version, notez-le ; des différences mineures sont souvent acceptables, mais des écarts de version majeurs peuvent entraîner des incompatibilités d'API. Pour les clusters de production, figez les versions et planifiez soigneusement les mises à niveau.

Saisissez la topologie du déploiement : s'agit-il d'un plan de contrôle unique, d'un etcd empilé ou d'un etcd externe ? Utilisez kubectl get pods -n kube-system pour lister les pods système et voir lesquels s'exécutent sur quels nœuds. Cette étape d'inventaire est en lecture seule et sûre à exécuter à tout moment. N'utilisez jamais de véritables identifiants dans les commandes ; remplacez-les par des espaces réservés dans toute documentation partagée.

Chemin de configuration sûr

Les modifications de configuration sont à l'origine de la plupart des pannes. Kubeadm stocke la configuration du cluster dans une ConfigMap et utilise un fichier de configuration pour l'initialisation et les mises à niveau. Lorsque vous devez modifier un composant, suivez un chemin qui minimise les risques : observez, sauvegardez, modifiez un seul élément, vérifiez et ayez un plan de retour en arrière.

Identification des sources de configuration

Kubeadm écrit la configuration du cluster dans kubeadm-config dans l'espace de noms kube-system. Affichez-la avec :

kubectl get configmap kubeadm-config -n kube-system -o yaml

Cela montre la ClusterConfiguration et le ClusterStatus. Avant de modifier quoi que ce soit, exportez-la vers un fichier pour sauvegarde :

kubectl get configmap kubeadm-config -n kube-system -o jsonpath='{.data.ClusterConfiguration}' > cluster-config-backup.yaml

Application d'un changement de configuration ciblé

Supposons que vous deviez augmenter le délai d'expiration des requêtes du serveur API. Modifiez directement la ConfigMap à l'aide de kubectl edit, mais sachez que les modifications apportées à la ConfigMap ne redémarrent pas automatiquement les composants du plan de contrôle. Les pods statiques gérés par kubeadm ne prennent en compte les modifications qu'après leur redémarrage. L'approche sûre consiste à déplacer temporairement le manifeste du pod statique, à laisser le kubelet redémarrer le composant et à vérifier.

Exemple : Modifier le manifeste du serveur API.

# Sauvegarder le manifeste
cp /etc/kubernetes/manifests/kube-apiserver.yaml /tmp/kube-apiserver.yaml.bak

# Modifier le manifeste pour ajouter --request-timeout=60s
vi /etc/kubernetes/manifests/kube-apiserver.yaml

# Le kubelet détecte le changement et redémarre automatiquement le serveur API

Vérifiez ensuite que le serveur API est sain :

kubectl get pods -n kube-system | grep kube-apiserver
kubectl get --raw='/readyz?verbose'

La deuxième commande doit renvoyer ok pour tous les contrôles si le serveur API est prêt. Si le nouveau paramètre provoque une défaillance, restaurez le manifeste de sauvegarde et le kubelet reviendra à la configuration précédente.

Vérification et diagnostics

Lorsqu'un cluster se comporte mal, vous avez besoin d'un moyen méthodique pour cerner la cause. Cette section couvre les commandes de diagnostic clés et la manière d'interpréter leur sortie.

Santé du plan de contrôle

Vérifiez la santé des composants du plan de contrôle (etcd, serveur API, gestionnaire de contrôleurs, planificateur) à l'aide de la commande kubectl get pods -n kube-system. Comme ceux-ci s'exécutent en tant que pods statiques, leurs noms se terminent par le nom du nœud. Pour un nœud de plan de contrôle unique, attendez-vous à ce que les quatre soient en cours d'exécution (Running).

Si un pod est en CrashLoopBackOff, inspectez ses journaux :

kubectl logs -n kube-system kube-apiserver-<node-name> --tail=50

Recherchez les erreurs courantes telles que des certificats mal configurés, un etcd inaccessible ou des drapeaux invalides. Le serveur API ne démarrera pas s'il ne peut pas atteindre etcd, vérifiez donc toujours la santé d'etcd en premier.

Problèmes de kubelet et de runtime de conteneurs

Le kubelet est l'agent de nœud qui démarre les pods statiques et communique avec le serveur API. Vérifiez son état :

systemctl status kubelet
journalctl -u kubelet -n 50 --no-pager

Si le kubelet ne peut pas démarrer, cela peut être dû à un point de terminaison de runtime de conteneurs manquant. Vérifiez que le socket du runtime est correct dans /var/lib/kubelet/config.yaml et que le runtime est en cours d'exécution.

Pour containerd :

systemctl status containerd
ctr images list

Si le runtime est sain mais que le kubelet échoue toujours, vérifiez la configuration du kubelet pour les chemins et l'authentification corrects.

Diagnostics réseau

Les problèmes de mise en réseau des pods se manifestent souvent par des services inaccessibles ou des pods incapables de communiquer. Les plugins CNI courants incluent Calico, Flannel et Cilium. Vérifiez les pods CNI :

kubectl get pods -n kube-system | grep -E 'calico|flannel|cilium'

Si un pod CNI ne fonctionne pas, inspectez ses journaux. Vérifiez également que le nœud dispose des binaires CNI requis dans /opt/cni/bin et de la configuration dans /etc/cni/net.d/.

Utilisez kubectl describe pod pour voir les événements qui pourraient indiquer des échecs de configuration réseau.

Modes de défaillance et récupération

Les clusters Kubeadm peuvent échouer de manière prévisible. Cette section couvre certains des modes de défaillance les plus courants et la manière de s'en remettre avec un temps d'arrêt minimal.

Échec de kubeadm init

Un kubeadm init peut échouer pour diverses raisons : prérequis manquants, blocages du pare-feu ou restes d'un cluster existant. Si l'initialisation échoue, exécutez kubeadm reset pour nettoyer avant de réessayer. Cette commande supprime tous les fichiers liés à Kubernetes et restaure le nœud à un état pré-initialisation.

kubeadm reset

Après la réinitialisation, vérifiez que les ports requis sont ouverts et que les exigences système sont satisfaites. Ensuite, relancez l'initialisation avec le même fichier de configuration, le cas échéant.

Expiration des certificats

Les certificats Kubernetes ont une validité d'un an par défaut. S'ils expirent, le serveur API ne démarrera pas. Vérifiez l'expiration des certificats :

kubeadm certs check-expiration

Si les certificats sont expirés, renouvelez-les :

kubeadm certs renew all

Redémarrez ensuite les composants du plan de contrôle (ou redémarrez le nœud) pour prendre en compte les nouveaux certificats. Pour éviter une expiration future, configurez une tâche cron de renouvellement ou utilisez kubeadm certs renew avant l'expiration.

Corruption des données etcd

etcd est le magasin de données de tout l'état du cluster. Une corruption peut entraîner une perte de données du serveur API ou un échec complet. Ayez toujours une sauvegarde etcd :

# Instantané etcd
ETCDCTL_API=3 etcdctl snapshot save /backup/etcd-snapshot.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

Pour restaurer à partir d'un instantané, arrêtez etcd, restaurez les données et redémarrez. Ce processus est complexe et doit être pratiqué d'abord dans un environnement hors production.

Nœud NotReady

Un nœud peut afficher NotReady pour de nombreuses raisons : kubelet arrêté, partition réseau ou épuisement des ressources. Tout d'abord, vérifiez l'état du kubelet sur ce nœud :

systemctl status kubelet

Si le kubelet est en cours d'exécution, décrivez le nœud pour voir les conditions :

kubectl describe node <node-name>

Recherchez les conditions MemoryPressure, DiskPressure ou NetworkUnavailable. Corrigez le problème sous-jacent (libérez de l'espace disque, réparez le réseau, etc.) et le nœud devrait revenir à l'état Ready.

Pièges courants et comment les éviter

Même les opérateurs expérimentés tombent dans des pièges. Voici quelques erreurs fréquentes et comment les éviter.

• Ignorer le décalage de version : Les composants Kubernetes ont une politique de décalage de version prise en charge. Exécuter un kubectl plus récent contre un serveur API plus ancien peut provoquer des erreurs. Alignez toujours les versions du client et du serveur dans la plage prise en charge. Consultez la politique officielle de décalage de version Kubernetes avant les mises à niveau.

• Modifier directement etcd : Manipuler directement les données etcd sans sauvegarde appropriée peut corrompre le cluster. Utilisez toujours kubeadm ou l'API Kubernetes pour les modifications, et conservez des instantanés etcd.

• Désactiver le swap après l'installation : Le kubelet exige que le swap soit désactivé. Si le swap est activé après la création du cluster, le kubelet échouera. Assurez-vous que le swap est définitivement désactivé dans /etc/fstab et que le système est redémarré si nécessaire.

• Négliger le renouvellement des certificats : Comme mentionné, les certificats expirent chaque année. Définissez des rappels et automatisez le renouvellement à l'aide de kubeadm certs renew dans une tâche cron sur le plan de contrôle.

• Utiliser le mauvais socket de runtime de conteneurs : Les valeurs par défaut de kubeadm peuvent ne pas correspondre à votre configuration de runtime. Vérifiez toujours le chemin du socket dans la configuration du kubelet et l'installation du runtime.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour la maintenance courante et le dépannage. Pour chaque élément, attribuez un responsable unique (par exemple, Priya Shah, responsable de l'ingénierie) et définissez une fréquence de révision (hebdomadaire, mensuelle ou avant chaque version).

Conclusion

Le dépannage de l'architecture kubeadm est une compétence fondée sur l'observation attentive, la connaissance des versions et les modifications contrôlées. Chaque commande de ce guide est en lecture seule ou réversible lorsque cela est possible, et comprend des étapes de vérification pour confirmer que le cluster est à nouveau sain. Commencez par le diagnostic le moins invasif, enregistrez l'état actuel et ne modifiez qu'un seul composant à la fois. Documentez vos étapes de récupération et testez-les régulièrement dans un environnement de préproduction.

Pour des approfondissements, consultez la documentation officielle Kubernetes sur kubeadm et les guides de dépannage pour des composants spécifiques comme etcd et les plugins CNI. Avec les pratiques décrites ici, vous pouvez gérer la plupart des problèmes de cluster et maintenir votre environnement Kubernetes résilient.

Prochaine étape : choisissez une vérification à faible risque dans la liste de contrôle, exécutez-la sur votre cluster et comparez le résultat avec la sortie attendue. Ensuite, passez en revue vos procédures de sauvegarde et de récupération pour etcd et les certificats.