etcd 3.7.1 : préparer une migration sans perdre le quorum

etcd 3.7 est la nouvelle branche stable du magasin clé-valeur qui conserve l'état critique de nombreux clusters Kubernetes. La version apporte RangeStream, des lectures de clés plus efficaces, des améliorations sur les leases et un important nettoyage des dépendances historiques. Le correctif 3.7.1 est disponible depuis le 23 juillet 2026.

Une mise à niveau d'etcd ne ressemble pourtant pas à celle d'une application sans état. Une mauvaise séquence peut retirer trop de membres simultanément, faire perdre le quorum ou transformer un retour arrière en restauration complète. Le projet documente un rolling upgrade sans interruption depuis 3.6, à condition de respecter des prérequis précis.

La réponse rapide

Les utilisateurs d'un Kubernetes managé ne doivent pas remplacer eux-mêmes les binaires du plan de contrôle. La responsabilité appartient généralement au fournisseur. L'article concerne surtout les clusters autogérés et les applications qui exploitent etcd directement.

Pourquoi la version 3.7 est importante

RangeStream répond à un problème de mémoire et de latence sur les résultats volumineux. Jusqu'à etcd 3.6, une requête de plage importante devait être entièrement mise en mémoire avant d'être renvoyée. La nouvelle RPC transmet les résultats par fragments, ce qui rend la consommation côté serveur et client plus prévisible.

Les requêtes keys_only peuvent désormais s'appuyer principalement sur l'index en mémoire sans charger chaque valeur depuis bbolt, sauf lorsqu'un tri par valeur l'impose. Les systèmes qui parcourent de grands espaces de clés devraient mesurer une baisse des lectures backend et de l'allocation mémoire.

Les leases reçoivent aussi plusieurs ajustements. La révocation devient prioritaire en période de surcharge et une option de renouvellement rapide évite certaines attentes. Pour Kubernetes, où les leases participent notamment à la coordination et à l'élection, le comportement sous pression est aussi important que le débit nominal.

Une dette historique disparaît

etcd 3.7 démarre entièrement depuis le stockage v3 et supprime plusieurs restes de l'ancien v2store. L'API HTTP v2, l'émulation v2-sur-v3, le service de découverte v2 et le client v2 ont disparu. Les installations modernes ne devraient plus en dépendre, mais une plateforme ancienne ou un outil interne peut encore révéler cette dette.

Tous les anciens paramètres --experimental-* dépréciés sont également retirés. En 3.6, leurs remplaçants existaient déjà sous forme de paramètres stables ou de feature gates. Si une unité systemd, un manifeste statique ou un chart transmet encore l'ancien nom, le processus 3.7 refusera de démarrer.

L'audit des arguments doit donc être réalisé avant la fenêtre de maintenance. Il faut examiner les manifests Kubernetes, les fichiers de configuration, les variables d'environnement et les scripts d'amorçage, pas seulement la commande visible dans la documentation d'exploitation.

Le prérequis 3.6.11 n'est pas facultatif

Le guide officiel exige que chaque membre du cluster tourne au minimum sous etcd 3.6.11 avant le passage à 3.7. Les versions correctives antérieures de 3.6 peuvent être incompatibles avec le rolling upgrade.

Une équipe encore en 3.5 doit donc d'abord migrer vers 3.6, stabiliser le cluster, puis planifier séparément le passage à 3.7. Cumuler deux changements mineurs dans la même intervention supprime un palier de diagnostic et complique le retour arrière.

Avant toute action, etcdctl endpoint status doit confirmer la version de chaque membre et etcdctl endpoint health la capacité à valider une proposition. Une réponse du port TCP ne suffit pas : le cluster doit réellement accepter une écriture via Raft.

Le snapshot est une condition, pas une case à cocher

Le guide recommande de créer et télécharger un snapshot avant l'opération. Le fichier ne doit pas rester uniquement sur le nœud que l'on s'apprête à modifier. Il doit être copié vers un stockage séparé, accompagné de sa date, de la version d'etcd et des informations nécessaires à la restauration.

Une sauvegarde non testée est une hypothèse. En préproduction, l'équipe doit restaurer le snapshot dans un répertoire neuf, démarrer un cluster isolé et vérifier quelques clés représentatives. Cette répétition mesure aussi la durée réelle de restauration, souvent absente des objectifs de reprise.

Il faut conserver les certificats, la configuration des membres, les URLs peer et client, ainsi que la procédure pour reconstruire les manifests du plan de contrôle. Le fichier de données seul ne documente pas toute l'infrastructure.

Remplacer un membre à la fois

Dans un cluster à trois membres, le quorum est de deux. Arrêter deux membres simultanément rend le cluster indisponible, même si les données sont intactes. La procédure consiste à arrêter un membre 3.6, remplacer son binaire ou son image par 3.7 en conservant la configuration et le répertoire de données, puis attendre son retour complet.

Après chaque remplacement, l'équipe doit vérifier :

1. la santé de tous les endpoints ;
2. le statut et la version du membre redémarré ;
3. la présence d'un leader et un terme Raft cohérent ;
4. l'absence de retard ou d'alarme inattendue ;
5. les erreurs TLS, disque et corruption dans les journaux ;
6. le fonctionnement du serveur d'API Kubernetes ou de l'application cliente.

La migration ne continue que lorsque ces contrôles sont stables. Automatiser la séquence sans barrière de santé revient à accélérer une panne possible.

Le cluster reste au plus petit dénominateur

Pendant la migration, les membres 3.6 et 3.7 peuvent cohabiter. Le cluster fonctionne alors avec le protocole de la version commune la plus basse. Les fonctions propres à 3.7 ne sont disponibles qu'après la mise à niveau de tous les membres et le changement de version du cluster.

Cet état mixte constitue aussi la fenêtre de retour arrière la plus simple. Tant qu'au moins un membre reste en 3.6 et que le cluster n'a pas finalisé son passage, un membre 3.7 problématique peut être remis sur le binaire ou l'image 3.6 compatible.

Une fois le dernier membre migré et la version du cluster passée à 3.7, revenir uniquement aux anciens binaires n'est plus possible. Il faut restaurer le snapshot antérieur ou suivre la procédure officielle de downgrade. Ce moment doit être explicitement annoncé comme point de non-retour dans le runbook.

Images multiarchitecture et intégrations Go

Les images officielles etcd 3.7 sont publiées uniquement sous forme multiarchitecture. Les tags spécifiques à une architecture ne sont plus fournis. Les déploiements qui construisent une URL ou un nom d'image avec un suffixe amd64 ou arm64 doivent être adaptés.

La migration de bibliothèques protobuf historiques vers google.golang.org/protobuf et la modernisation des intercepteurs gRPC ne devraient pas affecter l'utilisation des binaires officiels. Elles peuvent en revanche casser une application Go qui embarque etcd, dépend de modules internes ou maintient ses propres intercepteurs.

Ces clients doivent compiler leur matrice contre etcd 3.7, exécuter les tests de sérialisation et vérifier les métriques OpenTelemetry. Une mise à niveau du serveur réussie ne garantit pas la compatibilité d'une intégration qui importe des packages internes.

Tester les gains sans modifier la production

Les promesses de baisse CPU et de mémoire doivent être mesurées sur une copie représentative. Il faut comparer le débit, les latences p95 et p99, la taille de base, les pauses de disque, le nombre de watchers et le coût des requêtes de plage.

RangeStream n'accélère pas automatiquement un client qui continue d'utiliser l'ancienne RPC. De même, l'optimisation keys_only concerne des requêtes spécifiques. Le protocole de test doit identifier quelles charges bénéficient réellement de chaque changement.

Pour Kubernetes, observer la latence du serveur d'API, les élections, les leases et les événements pendant une simulation de surcharge apporte davantage d'informations qu'un benchmark synthétique de lectures séquentielles.

Un runbook avant la fenêtre de maintenance

La procédure finale doit tenir dans un document exécutable :

1. propriétaires de l'intervention et canal de communication ;
2. versions exactes de départ et d'arrivée ;
3. commandes de santé avec résultats attendus ;
4. emplacement et validation du snapshot ;
5. ordre des membres et délais maximaux ;
6. critères d'arrêt après chaque nœud ;
7. point de non-retour avant le dernier membre ;
8. procédure de rollback puis de restauration ;
9. contrôles applicatifs après migration ;
10. durée d'observation avant de supprimer les anciens artefacts.

etcd 3.7.1 apporte des évolutions utiles et retire une dette devenue difficile à maintenir. La migration reste maîtrisable lorsqu'elle est traitée comme une opération de quorum, pas comme un simple changement de tag d'image. Le véritable indicateur de réussite n'est pas que les trois processus affichent 3.7, mais que l'équipe sache encore restaurer l'état du cluster si le dernier redémarrage révèle un problème.