etcd en production : le composant qui décide si votre cluster Kubernetes tient debout

Quand un cluster Kubernetes part en vrille sans raison apparente, que l'API server répond en plusieurs secondes ou renvoie des timeouts en rafale, le réflexe est de regarder le kube-apiserver, le réseau, la charge des nœuds. Neuf fois sur dix, le vrai coupable est plus bas dans la pile : etcd. C'est le seul composant réellement stateful du control plane, le registre où vit l'intégralité de l'état désiré du cluster. S'il ralentit, tout ralentit. S'il perd le quorum, le cluster gèle. Et contrairement à un nœud worker qu'on remplace en cinq minutes, un etcd corrompu sans sauvegarde restaurable, c'est un cluster à reconstruire de zéro.

etcd s'appuie sur l'algorithme de consensus Raft pour répliquer un magasin clé-valeur ordonné sur plusieurs nœuds, avec un leader qui sérialise toutes les écritures et garantit la cohérence forte. Cette mécanique impose des contraintes d'exploitation très précises, souvent ignorées jusqu'au premier incident. Voici ce qui compte réellement sur le terrain.

Raft fonctionne par majorité. Pour valider une écriture, il faut que la moitié des nœuds plus un, soit (n/2)+1, l'acceptent. Ce sous-ensemble s'appelle le quorum. Sans quorum, etcd refuse toute écriture et le control plane se fige : plus de scheduling, plus de mise à jour de ressources, le cluster devient un musée.

La conséquence sur le dimensionnement est contre-intuitive. Un cluster de 3 nœuds tolère la perte d'1 nœud (quorum de 2 sur 3). Un cluster de 4 nœuds tolère lui aussi la perte d'1 seul nœud (quorum de 3 sur 4). Le quatrième nœud n'apporte aucune tolérance de panne supplémentaire, mais il ajoute une machine de plus susceptible de tomber et une réplique de plus à synchroniser à chaque écriture. Un nombre pair dégrade donc la disponibilité réelle tout en coûtant plus cher. La règle est sans appel : 3, 5 ou 7 nœuds, jamais un nombre pair.

Le tableau de tolérance, pour fixer les idées :

• 3 nœuds : quorum 2, tolère 1 panne.
• 5 nœuds : quorum 3, tolère 2 pannes.
• 7 nœuds : quorum 4, tolère 3 pannes.

Au-delà de 7, on s'arrête. Chaque écriture doit être répliquée et confirmée par la majorité ; plus il y a de nœuds, plus la latence d'écriture monte et plus le débit d'écriture chute. La documentation etcd recommande de ne pas dépasser 7 nœuds. Google fait tourner son service de verrouillage Chubby, cousin technique d'etcd, sur 5 nœuds depuis des années. Pour la quasi-totalité des cas, 3 nœuds suffisent ; on passe à 5 quand on veut survivre à la perte simultanée de deux nœuds, typiquement une panne de rack pendant une maintenance.

Détail qui sauve : répartissez les nœuds etcd sur des zones de défaillance distinctes (racks, alimentations, switchs), mais gardez la latence réseau inter-nœuds basse. Raft est bavard. Étaler un cluster etcd entre deux datacenters distants, c'est injecter de la latence dans chaque écriture et fragiliser le quorum au moindre incident de lien.

C'est le point que la plupart des équipes découvrent trop tard. etcd est extrêmement sensible à la latence d'écriture disque, parce que Raft impose la durabilité avant de confirmer quoi que ce soit. Concrètement, avant qu'une écriture soit considérée comme committée, etcd doit la persister dans son journal d'écriture anticipée, le WAL (Write-Ahead Log), avec un fsync qui force réellement les données sur le support. Tant que ce fsync n'est pas revenu, le client attend.

Si le disque sous-jacent met 50 ou 100 millisecondes à confirmer un fsync, chaque écriture etcd traîne cette latence. Et comme l'API server passe par etcd pour la moindre opération d'écriture, cette lenteur remonte mécaniquement : le kube-apiserver devient lent, les contrôleurs prennent du retard, les health checks commencent à échouer, et le cluster donne l'impression de s'effondrer alors que le seul problème est un disque trop lent. Le piège vicieux, c'est qu'un disque mécanique ou un stockage réseau peut très bien tenir une charge applicative classique tout en étant catastrophique pour etcd.

Les seuils à connaître, mesurés sur le 99e percentile :

• etcd_disk_wal_fsync_duration_seconds doit rester sous les 10 millisecondes.
• etcd_disk_backend_commit_duration_seconds doit rester sous les 25 millisecondes.

Au-delà, vous êtes en zone rouge. La règle qu'on applique : etcd tourne sur du SSD, idéalement du NVMe, avec une faible latence et un IOPS élevé. Pas de disque mécanique, pas de NAS, pas de SAN, pas de RBD Ceph pour le datastore etcd. Tout ce qui ajoute de la latence réseau imprévisible entre etcd et son stockage est disqualifié. Sur du write-intensive, les SSD SLC tiennent mieux la distance que le grand public. Et le datastore etcd a son disque dédié : le partager avec les logs ou d'autres écritures, c'est s'exposer à des pics de latence qui n'ont rien à voir avec etcd.

Cette sensibilité disque est une des raisons pour lesquelles on traite le control plane comme un sujet d'exploitation à part entière, au même titre que la conception d'un control plane Kubernetes hautement disponible. Le quorum etcd et la redondance des nœuds maîtres vont de pair.

etcd conserve un historique versionné de chaque clé. Chaque modification crée une nouvelle révision, et les anciennes versions s'accumulent. Sans entretien, la base grossit indéfiniment jusqu'à saturer son quota. Deux opérations distinctes maintiennent la base en forme, et on les confond souvent.

La compaction supprime les anciennes révisions de l'historique, en ne gardant que ce qui est nécessaire. Sur un cluster Kubernetes, le kube-apiserver déclenche par défaut une compaction automatique toutes les cinq minutes, donc ce point est généralement couvert. Mais la compaction ne rend pas l'espace disque au système : elle marque les pages comme libres à l'intérieur du fichier de base, sans le réduire.

C'est là qu'intervient la défragmentation. La commande etcdctl defrag réécrit le fichier de base pour récupérer l'espace libéré par la compaction et le rendre au système de fichiers. C'est une opération lourde : pendant la défragmentation, le nœud concerné est bloquant et ne répond plus aux requêtes. La règle qu'on applique : défragmenter un nœud à la fois, jamais tout le cluster simultanément, et idéalement en dehors des pics de charge. Sur un cluster avec leader, on garde le leader pour la fin.

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

etcd protège son stockage par un quota. Par défaut, la limite est de 2 Go (2147483648 octets), ajustable via le flag --quota-backend-bytes. La documentation suggère de ne pas dépasser 8 Go comme valeur cible : etcd, via boltDB, mappe le fichier de base directement en mémoire, donc plus le quota est grand, plus la consommation mémoire grimpe.

Quand la base dépasse le quota, etcd déclenche une alarme à l'échelle du cluster : NOSPACE. À partir de là, etcd refuse toute nouvelle écriture et bascule en mode maintenance à opérations limitées. On voit alors remonter l'erreur etcdserver: mvcc: database space exceeded. Le control plane Kubernetes, qui dépend des écritures etcd, se retrouve paralysé pour les modifications.

Le piège classique : croire qu'augmenter le quota suffit à débloquer la situation. Non. Une fois l'alarme NOSPACE levée, elle ne disparaît pas automatiquement, même si vous augmentez la limite ou faites de la place. Il faut d'abord libérer de l'espace (compaction puis défragmentation), puis désarmer explicitement l'alarme :

ETCDCTL_API=3 etcdctl alarm list
ETCDCTL_API=3 etcdctl alarm disarm

Tant que l'alarme reste armée, le cluster reste en mode dégradé. C'est typiquement le genre d'incident qui survient en pleine nuit sur un cluster laissé sans supervision de la taille de sa base.

Un snapshot etcd, c'est l'image complète de l'état du cluster à un instant T. La prise de sauvegarde est triviale :

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 /backup/etcd-snapshot.db

La partie triviale s'arrête là. Une sauvegarde jamais restaurée n'est pas une sauvegarde, c'est une supposition. Le seul moment où on découvre qu'un snapshot est illisible, que la procédure a changé de version, ou que personne ne sait remonter un cluster à partir de ce fichier, c'est pendant l'incident. Trop tard.

Côté restauration, attention au piège de version : depuis etcd v3.5, la restauration via etcdctl snapshot restore est dépréciée et destinée à disparaître en v3.6. L'outil recommandé est désormais etcdutl, conçu pour opérer directement sur les fichiers de données hors ligne. La restauration reconstruit un nouveau répertoire de données à partir du snapshot :

etcdutl snapshot restore /backup/etcd-snapshot.db \
  --data-dir /var/lib/etcd-restored

La règle qu'on applique : un snapshot programmé à fréquence fixe, stocké hors du cluster, et une restauration jouée grandeur nature à intervalle régulier sur un environnement isolé. On vérifie que le cluster remonte, que l'état est cohérent, que les workloads reviennent. Cette discipline rejoint la logique d'une sauvegarde immutable et restaurable avec Proxmox Backup Server : le RPO et le RTO ne se déclarent pas, ils se mesurent en condition réelle. Sur les distributions légères comme un cluster K3s en production, le datastore peut différer, mais le principe de restauration testée reste identique.

On ne pilote pas etcd à l'aveugle. Il expose des métriques Prometheus, et quelques-unes méritent une alerte dédiée :

• etcd_disk_wal_fsync_duration_seconds et etcd_disk_backend_commit_duration_seconds : la latence disque, le signal avancé d'une dégradation. Une dérive ici précède toujours la chute de l'API server.
• etcd_server_leader_changes_seen_total : le nombre de changements de leader. Un leader stable doit le rester. Des élections répétées trahissent un problème réseau, un nœud surchargé ou un disque qui décroche, et chaque réélection suspend brièvement les écritures.
• etcd_server_has_leader : à zéro, le cluster n'a plus de leader et n'accepte plus rien. Alerte critique immédiate.
• La taille de la base par rapport au quota, pour anticiper le NOSPACE bien avant qu'il ne tombe.

Le scénario catastrophe se déroule toujours dans le même ordre : un disque commence à ralentir, les fsync s'allongent, le leader devient instable et perd des élections, les écritures s'empilent, l'API server timeout, et l'équipe passe une heure à débuguer Kubernetes alors que le problème est un I/O disque parti en vrille trente minutes plus tôt. Une supervision correcte de la latence fsync aurait sonné l'alarme avant le premier timeout client. C'est exactement le type de signal faible qu'on instrumente en priorité, au même titre que pour une montée de version Kubernetes maîtrisée, où la santé d'etcd conditionne tout le reste.

etcd n'est pas un détail d'implémentation de Kubernetes, c'est le point de défaillance unique de tout le control plane. Trois disciplines non négociables : un nombre impair de nœuds sur du stockage NVMe dédié à faible latence, un entretien régulier de la base (compaction automatique vérifiée, défragmentation maîtrisée, quota surveillé), et une sauvegarde dont la restauration est jouée pour de vrai et pas seulement planifiée. Le reste, c'est de la supervision : surveillez la latence fsync et les changements de leader, et vous verrez l'incident venir avant qu'il ne fasse tomber l'API server.

Quand un cluster Kubernetes critique repose sur un etcd jamais audité, sans supervision de la latence disque et sans restauration testée, on reprend le control plane à la base : dimensionnement du quorum, stockage adapté, runbook de restauration éprouvé, alerting sur les bonnes métriques. C'est ce qu'on fait au quotidien sur les infrastructures qu'on opère. Si la santé de votre etcd repose sur de la chance plutôt que sur une procédure, on peut auditer votre control plane et le mettre au niveau.

• etcd FAQ : taille de cluster et quorum : documentation officielle sur le nombre impair de nœuds, la formule de quorum et la limite recommandée de 7 nœuds.
• etcd System limits : quota de stockage : référence officielle pour le quota par défaut de 2 Go et le maximum suggéré de 8 Go.
• etcd Maintenance : compaction, défragmentation et alarme : référence officielle pour l'alarme NOSPACE et les opérations d'entretien.
• etcd Disaster recovery : snapshot save et restore : procédure officielle de sauvegarde et de restauration, avec la bascule vers etcdutl.
• Operating etcd clusters for Kubernetes : guide Kubernetes pour la sauvegarde, la restauration et la défragmentation d'etcd en contexte cluster.
• Etcd High Fsync Durations : runbook kube-prometheus avec les seuils de latence fsync et backend commit.