Listes de vérification pour la mise à jour vers une version antérieure
Différences notables entre v3.7 et v3.6 :
Différence entre les drapeaux
La version 3.7 n’introduit aucune nouvelle option, aussi un processus v3.6 accepte toutes les options d’une configuration v3.7, et aucune modification de configuration n’est requise lors d’une mise à jour rétrograde.
Note
La différence est basée sur les versions v3.7.0-rc.0 et v3.6.13. La différence réelle dépendra de votre version de correctif ; vérifiez d’abord avec diff <(etcd-3.7/bin/etcd -h | grep \\-\\-) <(etcd-3.6/bin/etcd -h | grep \\-\\-).
Les indicateurs --experimental-* obsolètes, supprimés à partir de la version v3.7, existent encore dans la version v3.6, mais ne les réinstallez pas après une mise à jour rétrograde ; utilisez leurs équivalents non expérimentaux ou les entrées --feature-gates, qui fonctionnent sur les deux versions.
Différence entre les métriques Prometheus
# metrics not available in v3.6
-etcd_server_request_duration_seconds
-etcd_debugging_server_watch_send_loop_control_stream_duration_seconds
-etcd_debugging_server_watch_send_loop_progress_duration_seconds
-etcd_debugging_server_watch_send_loop_watch_stream_duration_seconds
-etcd_debugging_server_watch_send_loop_watch_stream_duration_per_event_seconds
Liste de vérification pour la mise à jour vers une version antérieure du serveur
Exigences de mise à jour vers une version antérieure
Pour garantir une mise à jour descendante progressive sans incident, le cluster en cours d’exécution doit être sain. Vérifiez l’état du cluster à l’aide de la commande etcdctl endpoint health avant de poursuivre.
Préparation
Avant de procéder à une mise vers une version antérieure d’etcd, testez toujours les services dépendants d’etcd dans un environnement de préproduction avant de déployer la mise à jour vers l’environnement de production.
Avant de commencer, téléchargez l’instantané de sauvegarde
. Si une erreur survient lors de la rétrogradation, il sera possible d’utiliser cette sauvegarde pour annuler
la mise à jour et revenir à la version existante de etcd.
Avant de commencer, téléchargez la dernière version de etcd v3.6.
Versions mixtes
Lors d’une mise à jour vers une version inférieure, un cluster etcd prend en charge des versions mixtes de membres et fonctionne selon le protocole de la version commune la plus basse. Le cluster est considéré comme mis à jour vers une version inférieure une fois que la mise à jour vers une version inférieure est activée par etcdctl downgrade enable 3.6. Internement, la version globale du cluster est définie sur la version cible de la mise à jour vers une version inférieure, ce qui contrôle la version signalée et les fonctionnalités prises en charge.
Annuler
Avant de procéder à la mise à jour inférieure de votre cluster etcd, créez et téléchargez une sauvegarde sous forme d’instantané
de votre cluster etcd. Cet instantané peut être utilisé pour restaurer le cluster dans son état antérieur à la mise à jour, le cas échéant. Si des utilisateurs rencontrent des problèmes pendant la mise à jour inférieure, ils doivent d’abord identifier et résoudre la cause racine.
Si la désinstallation a commencé après l’exécution de etcdctl downgrade enable, et que le cluster est toujours dans un état de version mixte, où au moins un membre reste sur la version v3.7, les utilisateurs peuvent annuler le processus de mise à jour en cours en exécutant etcdctl downgrade cancel, puis en redémarrant tous les membres mis à jour avec les binaires d’origine v3.7.
Une fois que tous les membres ont été rétrogradés vers la version v3.6, le cluster est considéré comme entièrement rétrogradé. Si les utilisateurs souhaitent revenir à la version d’origine après avoir achevé un rétrogradation complète, ils doivent suivre le guide officiel d’mise à jour
afin d’assurer la cohérence et d’éviter toute corruption des données.
Procédure de rétrogradation
Cet exemple montre comment effectuer une mise à jour vers une version antérieure d’un cluster etcd à 3 membres en version v3.7, exécuté sur une machine locale. La sortie ci-dessous provient d’une exécution réelle contre etcd v3.7.0-rc.0 et etcd v3.6.13 sur un seul hôte, utilisant trois ports de boucle, sur un cluster qui a été mis à jour depuis v3.6.13 peu de temps auparavant.
Étape 1 : vérifier les conditions de rétrogradation
Le cluster est-il sain et en cours d’exécution sous la version 3.7.x ?
etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint health
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 1.052416ms
localhost:32379 is healthy: successfully committed proposal: took = 1.11625ms
localhost:22379 is healthy: successfully committed proposal: took = 1.114291ms
COMMENTcurl http://localhost:2379/version
<<COMMENT
{"etcdserver":"3.7.0-rc.0","etcdcluster":"3.7.0","storage":"3.7.0"}
COMMENTcurl http://localhost:22379/version
<<COMMENT
{"etcdserver":"3.7.0-rc.0","etcdcluster":"3.7.0","storage":"3.7.0"}
COMMENTcurl http://localhost:32379/version
<<COMMENT
{"etcdserver":"3.7.0-rc.0","etcdcluster":"3.7.0","storage":"3.7.0"}
COMMENTetcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint status -w=table
<<COMMENT
+-----------------+------------------+------------+-----------------+---------+--------+-----------------------+--------+-----------+------------+-----------+------------+--------------------+--------+--------------------------+-------------------+
| ENDPOINT | ID | VERSION | STORAGE VERSION | DB SIZE | IN USE | PERCENTAGE NOT IN USE | QUOTA | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS | DOWNGRADE TARGET VERSION | DOWNGRADE ENABLED |
+-----------------+------------------+------------+-----------------+---------+--------+-----------------------+--------+-----------+------------+-----------+------------+--------------------+--------+--------------------------+-------------------+
| localhost:2379 | 7339c4e5e833c029 | 3.7.0-rc.0 | 3.7.0 | 98 kB | 98 kB | 0% | 2.1 GB | true | false | 5 | 20 | 20 | | | false |
| localhost:22379 | 729934363faa4a24 | 3.7.0-rc.0 | 3.7.0 | 98 kB | 98 kB | 0% | 2.1 GB | false | false | 5 | 20 | 20 | | | false |
| localhost:32379 | b548c2511513015 | 3.7.0-rc.0 | 3.7.0 | 98 kB | 98 kB | 0% | 2.1 GB | false | false | 5 | 20 | 20 | | | false |
+-----------------+------------------+------------+-----------------+---------+--------+-----------------------+--------+-----------+------------+-----------+------------+--------------------+--------+--------------------------+-------------------+
COMMENT
Étape 2 : télécharger la sauvegarde instantané depuis le leader
etcdctl --endpoints=localhost:2379 snapshot save backup.db
<<COMMENT
{"level":"info","ts":"2026-07-02T06:48:11.091982+0300","caller":"snapshot/v3_snapshot.go:83","msg":"created temporary db file","path":"backup.db.part"}
{"level":"info","ts":"2026-07-02T06:48:11.092253+0300","logger":"client","caller":"v3/maintenance.go:236","msg":"opened snapshot stream; downloading"}
{"level":"info","ts":"2026-07-02T06:48:11.099884+0300","caller":"snapshot/v3_snapshot.go:96","msg":"fetching snapshot","endpoint":"localhost:2379"}
{"level":"info","ts":"2026-07-02T06:48:11.100394+0300","logger":"client","caller":"v3/maintenance.go:302","msg":"completed snapshot read; closing"}
{"level":"info","ts":"2026-07-02T06:48:11.103116+0300","caller":"snapshot/v3_snapshot.go:111","msg":"fetched snapshot","endpoint":"localhost:2379","size":"98 kB","took":"10.9815ms","etcd-version":"3.7.0"}
{"level":"info","ts":"2026-07-02T06:48:11.103296+0300","caller":"snapshot/v3_snapshot.go:121","msg":"saved","path":"backup.db"}
Snapshot saved at backup.db
Server version 3.7.0
COMMENT
Étape 3 : valider la version cible de la mise à jour vers une version antérieure
Validez la version cible de la rétrogradation avant d’activer la rétrogradation :
Nous ne supportons que le retour arrière d’une version mineure à la fois. Par exemple, le passage de la version v3.7 à la version v3.5 n’est pas autorisé.
Veuillez ne pas passer à l’étape suivante tant que la validation n’est pas réussie.
Après avoir activé la désinstallation, le cluster commencera à fonctionner avec le protocole v3.6, qui est la version cible de la désinstallation. En outre, etcd migrera automatiquement le schéma vers la version cible de la désinstallation, ce qui se produit généralement très rapidement. Vérifiez que la version de stockage de tous les serveurs a bien été migrée vers la v3.6 en consultant l’état des points de terminaison avant de passer à l’étape suivante.
Une fois la désinstallation autorisée, le cluster continuera à fonctionner avec le protocole v3.6, même si tous les serveurs exécutent encore le binaire v3.7, à moins que la désinstallation ne soit annulée à l’aide de etcdctl downgrade cancel
Étape 5 : arrêter un serveur etcd existant
Avant d’arrêter le serveur, vérifiez s’il est le leader. Nous recommandons de mettre hors service le leader en dernier. Si le serveur à arrêter est le leader, vous pouvez réduire une partie de la durée d’indisponibilité en move-leader vers un autre serveur avant d’arrêter ce serveur.
etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 move-leader 729934363faa4a24
<<COMMENT
Leadership transferred from 7339c4e5e833c029 to 729934363faa4a24
COMMENT
Lorsque chaque processus etcd est arrêté, les autres membres du cluster enregistrent des erreurs attendues. Cela est normal, car la connexion avec un membre du cluster a été (temporairement) interrompue :
{"level":"warn","ts":"2026-07-02T06:48:14.518460+0300","caller":"rafthttp/stream.go:227","msg":"lost TCP streaming connection with remote peer","stream-writer-type":"stream Message","local-member-id":"7339c4e5e833c029","remote-peer-id":"729934363faa4a24"}{"level":"warn","ts":"2026-07-02T06:48:15.913169+0300","caller":"etcdserver/cluster_util.go:261","msg":"failed to reach the peer URL","address":"http://localhost:22380/version","remote-member-id":"729934363faa4a24","error":"Get \"http://localhost:22380/version\": dial tcp [::1]:22380: connect: connection refused"}{"level":"warn","ts":"2026-07-02T06:48:15.913364+0300","caller":"etcdserver/cluster_util.go:162","msg":"failed to get version","remote-member-id":"729934363faa4a24","error":"Get \"http://localhost:22380/version\": dial tcp [::1]:22380: connect: connection refused"}{"level":"warn","ts":"2026-07-02T06:48:16.856521+0300","caller":"version/monitor.go:212","msg":"remotes server has mismatching etcd version","remote-member-id":"b548c2511513015","current-server-version":"3.7.0","target-version":"3.6.0"}
Étape 6 : redémarrer le serveur etcd avec la même configuration
Redémarrez le serveur etcd avec la même configuration, mais en utilisant le binaire etcd v3.6.
Vérifiez que chaque membre, puis l’ensemble du cluster, devient sain avec le binaire etcd v3.6 :
etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint status -w=table
<<COMMENT
+-----------------+------------------+------------+-----------------+---------+--------+-----------------------+--------+-----------+------------+-----------+------------+--------------------+--------+--------------------------+-------------------+
| ENDPOINT | ID | VERSION | STORAGE VERSION | DB SIZE | IN USE | PERCENTAGE NOT IN USE | QUOTA | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS | DOWNGRADE TARGET VERSION | DOWNGRADE ENABLED |
+-----------------+------------------+------------+-----------------+---------+--------+-----------------------+--------+-----------+------------+-----------+------------+--------------------+--------+--------------------------+-------------------+
| localhost:2379 | 7339c4e5e833c029 | 3.7.0-rc.0 | 3.6.0 | 98 kB | 98 kB | 0% | 2.1 GB | true | false | 5 | 23 | 23 | | 3.6.0 | true |
| localhost:22379 | 729934363faa4a24 | 3.6.13 | 3.6.0 | 98 kB | 98 kB | 0% | 2.1 GB | false | false | 5 | 23 | 23 | | 3.6.0 | true |
| localhost:32379 | b548c2511513015 | 3.7.0-rc.0 | 3.6.0 | 98 kB | 98 kB | 0% | 2.1 GB | false | false | 5 | 23 | 23 | | 3.6.0 | true |
+-----------------+------------------+------------+-----------------+---------+--------+-----------------------+--------+-----------+------------+-----------+------------+--------------------+--------+--------------------------+-------------------+
COMMENTetcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 939.625µs
localhost:32379 is healthy: successfully committed proposal: took = 981.459µs
localhost:22379 is healthy: successfully committed proposal: took = 1.11075ms
COMMENT
Note
Contrairement à la version 3.5, le point d’extrémité d’état de la version 3.6 indique bien les informations de rétrogradation, de sorte que les membres rétrogradés continuent à afficher DOWNGRADE ENABLED comme true et leur version de stockage jusqu’à la fin de la rétrogradation.
Étape 7 : répéter étape 5 et étape 6 pour les membres restants
Lorsque tous les membres sont désactivés, la désactivation est automatiquement terminée et DOWNGRADE ENABLED est réinitialisé à false. Vérifiez l’état de santé et le statut du cluster, puis confirmez que la version mineure de tous les membres et la version de stockage sont v3.6 :
etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint status -w=table
<<COMMENT
+-----------------+------------------+---------+-----------------+---------+--------+-----------------------+--------+-----------+------------+-----------+------------+--------------------+--------+--------------------------+-------------------+
| ENDPOINT | ID | VERSION | STORAGE VERSION | DB SIZE | IN USE | PERCENTAGE NOT IN USE | QUOTA | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS | DOWNGRADE TARGET VERSION | DOWNGRADE ENABLED |
+-----------------+------------------+---------+-----------------+---------+--------+-----------------------+--------+-----------+------------+-----------+------------+--------------------+--------+--------------------------+-------------------+
| localhost:2379 | 7339c4e5e833c029 | 3.6.13 | 3.6.0 | 98 kB | 98 kB | 0% | 2.1 GB | false | false | 6 | 30 | 30 | | | false |
| localhost:22379 | 729934363faa4a24 | 3.6.13 | 3.6.0 | 98 kB | 98 kB | 0% | 2.1 GB | true | false | 6 | 30 | 30 | | | false |
| localhost:32379 | b548c2511513015 | 3.6.13 | 3.6.0 | 98 kB | 98 kB | 0% | 2.1 GB | false | false | 6 | 30 | 30 | | | false |
+-----------------+------------------+---------+-----------------+---------+--------+-----------------------+--------+-----------+------------+-----------+------------+--------------------+--------+--------------------------+-------------------+
COMMENTetcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
<<COMMENT
localhost:22379 is healthy: successfully committed proposal: took = 5.176958ms
localhost:32379 is healthy: successfully committed proposal: took = 5.177875ms
localhost:2379 is healthy: successfully committed proposal: took = 5.191625ms
COMMENTcurl http://localhost:2379/version
<<COMMENT
{"etcdserver":"3.6.13","etcdcluster":"3.6.0","storage":"3.6.0"}
COMMENTcurl http://localhost:22379/version
<<COMMENT
{"etcdserver":"3.6.13","etcdcluster":"3.6.0","storage":"3.6.0"}
COMMENTcurl http://localhost:32379/version
<<COMMENT
{"etcdserver":"3.6.13","etcdcluster":"3.6.0","storage":"3.6.0"}
COMMENT
Dans le journal du leader, vous devriez être en mesure de voir un message similaire au suivant :
{"level":"info","ts":"2026-07-02T06:48:32.312205+0300","caller":"version/monitor.go:143","msg":"the cluster has been downgraded","cluster-version":"3.6.0"}