Dépannage de la configuration et de la mise à niveau d'etcd dans Kubernetes : guide pratique de terrain

Introduction

etcd est la source de vérité de votre cluster Kubernetes. Lorsque etcd se comporte mal, l'ensemble du plan de contrôle peut devenir indisponible et les applications peuvent cesser de se planifier ou de se mettre à l'échelle. Le dépannage de la configuration et des mises à niveau d'etcd nécessite une approche méthodique : observer l'état actuel, comprendre la topologie de déploiement, vérifier les prérequis et effectuer une modification ciblée à la fois. Ce guide fournit un flux de travail pratique, piloté par des commandes, pour le dépannage de la configuration et de la mise à niveau d'etcd dans Kubernetes. Il s'adresse aux développeurs, aux consultants DevOps et aux équipes techniques de startups qui doivent diagnostiquer rapidement et en toute sécurité les problèmes.

L'objectif est la sécurité opérationnelle. Nous suivrons un schéma : observer avant de modifier, limiter le rayon d'impact, utiliser des variables génériques plutôt que des secrets, vérifier le résultat et documenter les étapes de récupération avant qu'un incident ne force une décision. Chaque section comprend des commandes concrètes, les résultats attendus et les signaux d'échec pour les problèmes courants d'etcd.

Inventaire des versions et de l'environnement

Avant de toucher à etcd, vous devez savoir avec quoi vous travaillez. Collectez les informations de version, la topologie de déploiement et l'état de santé du cluster. Exécutez ces commandes depuis un nœud du plan de contrôle ou une machine disposant d'un accès kubectl au cluster.

Tout d'abord, vérifiez la version de Kubernetes et la version de l'image etcd exécutée dans le cluster :

kubectl version --short
kubectl get pods -n kube-system -l component=etcd -o jsonpath='{.items[*].spec.containers[*].image}{"\n"}'

Résultat attendu :

Client Version: v1.27.3
Server Version: v1.27.3
registry.k8s.io/etcd:3.5.9-0

Si etcd s'exécute en tant que pod statique géré par kubelet, vous pouvez également inspecter directement le manifeste :

sudo cat /etc/kubernetes/manifests/etcd.yaml | grep image:

Résultat attendu :

    image: registry.k8s.io/etcd:3.5.9-0

Ensuite, identifiez la topologie du cluster etcd. Pour un plan de contrôle empilé (etcd s'exécute sur les mêmes nœuds que le plan de contrôle Kubernetes), listez les membres etcd :

sudo crictl ps | grep etcd

Le résultat attendu affiche un conteneur etcd par nœud du plan de contrôle. Alternativement, si etcdctl est disponible :

ETCDCTL_API=3 etcdctl --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 member list

Le résultat attendu liste les membres avec leurs ID, URL de pair et URL de client. Par exemple :

8211f1d0f64f3269, started, node1, https://192.168.1.10:2380, https://192.168.1.10:2379, false
91bc3c398fb3c146, started, node2, https://192.168.1.11:2380, https://192.168.1.11:2379, false
fd422379fda50e48, started, node3, https://192.168.1.12:2380, https://192.168.1.12:2379, false

Vérifiez la santé du cluster etcd :

ETCDCTL_API=3 etcdctl --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 endpoint health

Résultat attendu pour un cluster sain :

https://127.0.0.1:2379 is healthy: successfully committed proposal: took = 2.1ms

Si la sortie affiche des points de terminaison non sains ou des délais d'attente, notez l'erreur exacte. Les échecs courants incluent des incohérences de certificats, des partitions réseau ou un espace disque insuffisant.

Vérification Kubernetes pratique pour l'inventaire des versions et de l'environnement : commencez par kubectl get pods -n kube-system -o wide pour voir l'état du pod etcd. Utilisez ensuite kubectl describe pod <etcd-pod-name> -n kube-system pour les événements, et kubectl logs <etcd-pod-name> -n kube-system --previous pour les détails de la boucle de crash. Si le pod etcd est en boucle de crash, inspectez les journaux de kubelet sur le nœud du plan de contrôle :

sudo journalctl -u kubelet -n 100 --no-pager

Recherchez les lignes mentionnant etcd, telles que failed to start etcd ou etcd exited with status 1.

Limitez le test local. Si vous soupçonnez une mauvaise configuration d'etcd, vérifiez la connectivité du kube-apiserver vers etcd. Sur le nœud du plan de contrôle, exécutez :

sudo ss -tunlp | grep 2379

Le résultat attendu montre etcd écoutant sur le port 2379 (client) et 2380 (pair). Si ce n'est pas le cas, vérifiez le manifeste du pod statique etcd et assurez-vous que les drapeaux --listen-client-urls et --listen-peer-urls sont corrects.

Chemin de configuration sécurisé

Modifier la configuration d'etcd est risqué. Sauvegardez toujours d'abord, puis modifiez un paramètre à la fois, et vérifiez après chaque modification. Le répertoire de données etcd (par défaut /var/lib/etcd) contient la base de données. Avant toute modification, prenez un instantané.

Créez un instantané avec etcdctl :

sudo ETCDCTL_API=3 etcdctl --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 snapshot save /tmp/etcd-snapshot-$(date +%Y%m%d%H%M).db

Résultat attendu :

Snapshot saved at /tmp/etcd-snapshot-20250320.db

Vérifiez l'instantané :

sudo ETCDCTL_API=3 etcdctl snapshot status /tmp/etcd-snapshot-20250320.db

Le résultat attendu affiche le hachage, la révision, le nombre total de clés et la taille totale.

Considérons maintenant un changement de configuration courant : ajuster la valeur de quota-backend-bytes d'etcd pour gérer un ensemble de données croissant. La valeur par défaut est de 2 Go. Supposons que votre etcd atteigne le quota et renvoie etcdserver: mvcc: database space exceeded. Vous décidez d'augmenter le quota.

Localisez le manifeste du pod statique etcd :

sudo ls /etc/kubernetes/manifests/etcd.yaml

Faites une copie de sauvegarde du manifeste avant de le modifier :

sudo cp /etc/kubernetes/manifests/etcd.yaml /tmp/etcd.yaml.backup

Ouvrez le manifeste avec un éditeur de texte (par exemple, sudo vi /etc/kubernetes/manifests/etcd.yaml) et ajoutez ou modifiez le drapeau --quota-backend-bytes. Par exemple, fixez-le à 4 Go :

    - --quota-backend-bytes=4294967296

Enregistrez le fichier. Le kubelet détecte automatiquement le changement et redémarre le pod etcd. Attendez quelques secondes et vérifiez l'état du pod :

kubectl get pods -n kube-system -l component=etcd

Résultat attendu :

NAME        READY   STATUS    RESTARTS   AGE
etcd-node1  1/1     Running   1          2m

Vérifiez à nouveau la santé d'etcd :

ETCDCTL_API=3 etcdctl --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 endpoint health

Si le pod ne démarre pas, vérifiez les journaux :

kubectl logs etcd-node1 -n kube-system

Les erreurs courantes incluent des valeurs de drapeau invalides ou des problèmes de permissions. Si la modification provoque des échecs répétés, restaurez le manifeste de sauvegarde et redémarrez kubelet :

sudo cp /tmp/etcd.yaml.backup /etc/kubernetes/manifests/etcd.yaml
sudo systemctl restart kubelet

Un autre problème de configuration courant est la rotation des certificats. Si etcd ne démarre pas après le renouvellement des certificats, vérifiez leur validité :

sudo openssl x509 -in /etc/kubernetes/pki/etcd/server.crt -noout -dates

Résultat attendu :

notBefore=Mar 20 10:00:00 2025 GMT
notAfter=Mar 20 10:00:00 2026 GMT

Si le certificat est expiré, régénérez-le à l'aide de kubeadm ou de votre outil de gestion des certificats.

Vérification et diagnostic

Après toute modification ou lors du diagnostic d'un problème, vous devez vérifier la santé d'etcd et diagnostiquer les problèmes. etcd fournit plusieurs points de terminaison et commandes de diagnostic.

Vérifiez la liste des membres etcd et leur statut :

ETCDCTL_API=3 etcdctl --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 endpoint status --write-out=table

Le résultat attendu inclut le point de terminaison, l'ID, la version, la taille de la base de données, le leader, le terme de raft, etc.

Surveillez l'état du leader etcd. Dans un cluster sain, il doit y avoir exactement un leader. Exécutez :

ETCDCTL_API=3 etcdctl --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 endpoint status | grep -i leader

Si vous voyez plusieurs leaders ou aucun, cela indique un problème de consensus raft.

Vérifiez les métriques etcd via le point de terminaison des métriques. Activez les métriques si ce n'est pas déjà fait. Sur un nœud du plan de contrôle, interrogez le point de terminaison des métriques :

sudo curl -s https://127.0.0.1:2379/metrics --cacert /etc/kubernetes/pki/etcd/ca.crt --cert /etc/kubernetes/pki/etcd/server.crt --key /etc/kubernetes/pki/etcd/server.key | grep etcd_server_leader_changes_seen_total

Résultat attendu :

etcd_server_leader_changes_seen_total 2

Un nombre élevé de changements de leader indique une instabilité.

Examinez les problèmes de performance. etcd peut être lent si la latence du disque est élevée. Vérifiez les E/S du disque :

sudo iostat -x 1 5

Recherchez des valeurs élevées de await ou %util. etcd nécessite des disques rapides (SSD). Si les disques sont lents, envisagez de déplacer les données etcd vers un stockage plus rapide.

Vérifiez la fragmentation de la base de données :

ETCDCTL_API=3 etcdctl --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 defrag --cluster

Résultat attendu :

Finished defragmenting etcd member[https://127.0.0.1:2379]

Exécutez la défragmentation pendant les fenêtres de maintenance pour éviter l'impact sur les performances.

Vérification Kubernetes pratique pour la vérification et le diagnostic : utilisez la séquence suivante pour vérifier systématiquement etcd.

1. Vérifiez l'état des pods : kubectl get pods -n kube-system -l component=etcd
2. Vérifiez les journaux : kubectl logs -n kube-system etcd-node1 --tail=100
3. Vérifiez les événements : kubectl describe pod etcd-node1 -n kube-system | grep Events -A 10
4. Vérifiez la santé des points de terminaison etcd comme indiqué ci-dessus.
5. Vérifiez la connectivité du kube-apiserver vers etcd : kubectl get --raw /healthz?verbose et recherchez les messages liés à etcd.

Le résultat attendu pour un serveur API sain inclut etcd: ok ou similaire.

Modes de défaillance et récupération

etcd peut échouer de différentes manières. Examinons les modes de défaillance courants et les procédures de récupération.

Mode de défaillance 1 : boucle de crash du pod etcd en raison d'une configuration invalide

Si etcd plante immédiatement après un changement de configuration, vérifiez les journaux.

kubectl logs etcd-node1 -n kube-system --previous

Erreur typique : invalid value for --quota-backend-bytes: ... ou flag provided but not defined.

Récupération : restaurez le manifeste précédent à partir de la sauvegarde et redémarrez kubelet.

Mode de défaillance 2 : corruption du répertoire de données etcd

Si etcd ne démarre pas et que les journaux affichent panic: failed to open data directory ou corrupt file, vous devrez peut-être restaurer à partir d'un instantané.

Tout d'abord, arrêtez etcd et kube-apiserver (s'il s'agit de pods statiques, déplacez temporairement les fichiers manifeste) :

sudo mv /etc/kubernetes/manifests/etcd.yaml /tmp/
sudo mv /etc/kubernetes/manifests/kube-apiserver.yaml /tmp/

Restaurez l'instantané :

sudo ETCDCTL_API=3 etcdctl snapshot restore /tmp/etcd-snapshot-20250320.db --data-dir=/var/lib/etcd-restore --name=node1 --initial-cluster=node1=https://192.168.1.10:2380 --initial-advertise-peer-urls=https://192.168.1.10:2380

Remplacez ensuite le répertoire de données :

sudo mv /var/lib/etcd /var/lib/etcd.broken
sudo mv /var/lib/etcd-restore /var/lib/etcd

Replacez les manifestes :

sudo mv /tmp/etcd.yaml /etc/kubernetes/manifests/
sudo mv /tmp/kube-apiserver.yaml /etc/kubernetes/manifests/

Attendez que les pods redémarrent et vérifiez la santé.

Mode de défaillance 3 : perte du quorum du cluster etcd

Si plus de la moitié des membres etcd échouent, le cluster perd le quorum. Le cluster ne peut plus servir les lectures ou les écritures. La récupération nécessite de rétablir le quorum en supprimant les membres défaillants et éventuellement en restaurant à partir d'un instantané.

Tout d'abord, identifiez les membres survivants. Sur un nœud sain, exécutez :

ETCDCTL_API=3 etcdctl --endpoints=https://192.168.1.10:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key member list

Si cela échoue en raison de l'absence de quorum, vous devrez peut-être forcer un nouveau cluster à partir d'un instantané sur un seul membre.

Par exemple, pour récupérer en utilisant node1 comme source de vérité, arrêtez etcd sur tous les nœuds, restaurez l'instantané sur node1 avec --initial-cluster contenant uniquement node1, puis démarrez etcd sur node1. Une fois qu'il est opérationnel, ajoutez les autres membres.

Cette opération est complexe ; reportez-vous à la documentation Kubernetes pour les étapes détaillées.

Mode de défaillance 4 : etcd à court d'espace disque

Si les journaux etcd affichent etcdserver: mvcc: database space exceeded, vous devez libérer de l'espace.

Options :

• Défragmentez la base de données : etcdctl defrag
• Compactez les anciennes révisions : etcdctl compact <revision>
• Augmentez le quota et redimensionnez le disque.

Compaction à une révision (par exemple, les 1000 derniers changements) :

revision=$(ETCDCTL_API=3 etcdctl --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 endpoint status --write-out="json" | jq -r '.[0].Status.header.revision')
compact_to=$((revision-1000))
ETCDCTL_API=3 etcdctl --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 compact $compact_to

Défragmentez ensuite.

Vérification Kubernetes pratique pour les modes de défaillance et la récupération : ayez toujours un instantané récent. Planifiez des instantanés réguliers à l'aide d'une tâche cron. Testez la procédure de restauration dans un environnement non productif.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour vous assurer de couvrir tous les aspects lors du dépannage de la configuration et des mises à niveau d'etcd.

Avant d'effectuer des modifications

• [ ] Confirmez la compatibilité des versions d'etcd et de Kubernetes. Par exemple, Kubernetes 1.27 prend en charge etcd 3.5.x.
• [ ] Prenez un instantané etcd : sudo ETCDCTL_API=3 etcdctl snapshot save /tmp/etcd-snapshot-$(date +%Y%m%d%H%M).db
• [ ] Enregistrez la liste actuelle des membres etcd et l'état de santé.
• [ ] Sauvegardez le manifeste etcd : sudo cp /etc/kubernetes/manifests/etcd.yaml /tmp/etcd.yaml.backup
• [ ] Assurez-vous d'avoir un accès console aux nœuds du plan de contrôle au cas où kubectl échouerait.

Pendant les modifications

• [ ] Modifiez un seul paramètre de configuration à la fois.
• [ ] Après chaque modification, attendez que le pod etcd soit prêt : kubectl wait --for=condition=Ready pod/etcd-node1 -n kube-system --timeout=60s
• [ ] Vérifiez immédiatement la santé d'etcd : etcdctl endpoint health
• [ ] Surveillez les journaux : kubectl logs -f etcd-node1 -n kube-system

Après les modifications

• [ ] Vérifiez que tous les membres etcd sont sains.
• [ ] Vérifiez que le kube-apiserver peut communiquer avec etcd : kubectl get --raw /healthz?verbose
• [ ] Vérifiez que les opérations du cluster fonctionnent : kubectl get nodes, kubectl create deployment test --image=nginx, puis supprimez-le.
• [ ] Supprimez les sauvegardes temporaires seulement après quelques jours de stabilité.

Vérifications spécifiques à la mise à niveau

Lors de la mise à niveau d'etcd dans le cadre d'une mise à niveau de Kubernetes :

• [ ] Lisez les notes de mise à niveau de Kubernetes pour les changements d'etcd.
• [ ] Sauvegardez etcd et tous les manifestes du plan de contrôle.
• [ ] Mettez à niveau un nœud du plan de contrôle à la fois.
• [ ] Après la mise à niveau d'etcd sur un nœud, vérifiez que le membre rejoint le cluster et que la santé est bonne avant de passer au nœud suivant.
• [ ] Ne continuez pas si un membre est non sain.

Vérification Kubernetes pratique pour la liste de contrôle des opérations : automatisez ces vérifications lorsque c'est possible à l'aide de scripts. Par exemple :

#!/bin/bash
# etcd-health-check.sh
ETCDCTL_API=3 etcdctl --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 endpoint health
kubectl get pods -n kube-system -l component=etcd

Conclusion

Le dépannage et les modifications de configuration d'etcd nécessitent une planification et une exécution soigneuses. En suivant l'approche structurée de ce guide — inventaire, configuration sécurisée, vérification et récupération — vous pouvez minimiser les temps d'arrêt et prévenir la perte de données. Commencez toujours par l'observation, apportez de petites modifications réversibles et vérifiez chaque étape avec des commandes concrètes et des résultats attendus. N'oubliez pas de conserver des sauvegardes, de documenter vos procédures de récupération et de les tester avant d'en avoir besoin. Avec ces pratiques, vous pouvez maintenir un cluster etcd sain et garder votre plan de contrôle Kubernetes fiable.