Vue imprimable multi-pages de cette section. .

Mise à jour

Mise à jour des clusters etcd et des applications

1: Mise à jour des clusters etcd et des applications
2: Mettre à jour etcd de la version v3.6 à la version v3.7
3: Mettre à jour etcd de la version v3.5 à la version v3.6
4: Mettre à jour etcd de 3.4 à 3.5
5: Mettre à jour etcd de 3.3 à 3.4
6: Mettre à jour etcd de 3.2 vers 3.3
7: Mettre à jour etcd de 3.1 vers 3.2
8: Mettre à jour etcd de la version 3.0 à la 3.1
9: Mettre à jour etcd de la version 2.3 à la 3.0

1 - Mise à jour des clusters etcd et des applications

Liste de documentation pour la mise à jour des clusters etcd et des applications

Cette section contient les documents spécifiques à la mise à jour des clusters etcd et des applications.

Politique de mise à jour

Avant la mise à jour, notez qu’etcd ne prend en charge que les deux cas de mise à jour suivants :

Mise à jour corrective : Mise à jour entre des versions correctives du même numéro de version mineure (par exemple, 3.7.0 → 3.7.1).
Mise à jour mineure : Mise à jour d’une version mineure à la fois (par exemple, 3.6 → 3.7). Les mises à jour qui sautent une version mineure ne sont pas prises en charge et risquent d’échouer. Mettez à jour vers la dernière version corrective avant de passer à la version mineure suivante.

Mise à jour d’un cluster etcd v3.x

Mise à niveau depuis etcd v2.3

Mettre à jour un cluster v2.3 vers la v3.0

2 - Mettre à jour etcd de la version v3.6 à la version v3.7

Processus, listes de vérification et notes sur la mise à niveau d’etcd de v3.6 à v3.7

Dans le cas général, la mise à niveau d’etcd v3.6 vers v3.7 peut être une mise à niveau progressive sans interruption de service :

un à un, arrêtez les processus etcd v3.6 et remplacez-les par des processus etcd v3.7
après avoir lancé tous les processus v3.7, les nouvelles fonctionnalités de la version v3.7 sont disponibles pour le cluster

Avant de lancer la mise à jour , lisez le reste du présent guide afin de vous préparer.

Listes de vérification pour la mise à jour

Mise à jour 3.6

Important

Avant de procéder à la mise à niveau vers 3.7, assurez-vous que tous vos membres 3.6 ont été mis à jour vers 3.6.11 ou une version ultérieure. Les correctifs 3.6 antérieurs peuvent ne pas être compatibles avec une mise à niveau progressive vers 3.7.

Magasin V2

Le magasin v2 a été entièrement supprimé dans la version 3.7. L’API HTTP v2 (--enable-v2), l’émulation v2 sur v3 (--experimental-enable-v2v3), le service de découverte v2, le paquet client/v2 et le chargement des fichiers d’instantané v2 ont tous disparu. Consultez les références aux changements de rupture dans CHANGELOG-3.7 .

Si vous effectuez une mise à jour à partir d’un cluster 3.6, ces drapeaux sont déjà absents et aucune action n’est requise. Si vous migrez depuis une version antérieure avec des données v2 personnalisées, suivez le guide de migration v2 avant la mise à jour.

Refactorisation Go

La version 3.7 contient des refontes internes importantes qui n’affectent pas les mises à jour normales, mais qui méritent d’être prises en compte lors de la mise à jour d’intégrations personnalisées :

Migration de gogo/protobuf vers google.golang.org/protobuf standard (suivi dans #14533 ).
Migration des bibliothèques de journalisation et d’étiquetage dépréciées go-grpc-middleware v1 vers les intercepteurs v2 (#20420 ).
Les intercepteurs gRPC OpenTelemetry ont été mis à jour vers otelgrpc v0.61.0, remplaçant les composants dépréciés UnaryServerInterceptor et StreamServerInterceptor par NewServerHandler (#20017 ).

Si vous intégrez etcd en tant que bibliothèque, effectuez la compilation contre l’API clientv3, ou dépendez de packages internes, examinez le CHANGELOG avant de procéder à la mise à jour.

Drapeaux supprimés

Tous les drapeaux --experimental-* obsolètes ont été supprimés dans la version 3.7 (#19959 ). Dans la version 3.6, chacun de ces drapeaux a été remplacé soit par un drapeau non expérimental du même nom, soit par une entrée --feature-gates. Si vous avez encore l’un de ces drapeaux défini, remplacez-le par l’équivalent de la version 3.6 avant de passer à la version 3.7, sinon le processus de la version 3.7 ne pourra pas démarrer.

-etcd --experimental-bootstrap-defrag-threshold-megabytes
-etcd --experimental-compact-hash-check-enabled
-etcd --experimental-compact-hash-check-time
-etcd --experimental-compaction-batch-limit
-etcd --experimental-compaction-sleep-interval
-etcd --experimental-corrupt-check-time
-etcd --experimental-distributed-tracing-address
-etcd --experimental-distributed-tracing-instance-id
-etcd --experimental-distributed-tracing-sampling-rate
-etcd --experimental-distributed-tracing-service-name
-etcd --experimental-downgrade-check-time
-etcd --experimental-enable-distributed-tracing
-etcd --experimental-enable-lease-checkpoint
-etcd --experimental-enable-lease-checkpoint-persist
-etcd --experimental-initial-corrupt-check
-etcd --experimental-memory-mlock
-etcd --experimental-peer-skip-client-san-verification
-etcd --experimental-snapshot-catchup-entries
-etcd --experimental-stop-grpc-service-on-defrag
-etcd --experimental-txn-mode-write-with-shared-buffer
-etcd --experimental-warning-apply-duration
-etcd --experimental-warning-unary-request-duration
-etcd --experimental-watch-progress-notify-interval

Reportez-vous au guide de mise à jour v3.5 vers v3.6 pour la correspondance de chaque drapeau supprimé vers son équivalent non expérimental ou son entrée --feature-gates.

Drapeaux ajoutés

Aucun.

Drapeaux avec de nouvelles valeurs par défaut

Aucun.

Liste de vérification pour la mise à jour du serveur

Exigences de mise à jour

Pour mettre à jour un déploiement etcd existant vers la version 3.7, le cluster en cours d’exécution doit être la version 3.6.11 ou ultérieure. Si le cluster utilise une version mineure antérieure, veuillez d’abord mettre à jour vers la version 3.6 ; etcd ne prend en charge la mise à jour que d’une version mineure à la fois.

En outre, pour garantir une mise à niveau progressive sans incident, le cluster en cours d’exécution doit être sain. Vérifiez l’état de santé du cluster à l’aide de la commande etcdctl endpoint health avant de poursuivre.

Préparation

Avant de mettre à jour etcd, testez toujours les services dépendants d’etcd dans un environnement de préproduction avant de déployer la mise à jour dans l’environnement de production.

Avant de commencer, téléchargez la sauvegarde d’instantané . Si une erreur survient lors de la mise à jour, il sera possible d’utiliser cette sauvegarde pour annuler la mise à jour et revenir à la version précédente d’etcd.

Versions mixtes

Lors d’une mise à jour, 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 uniquement lorsque tous ses membres ont été mis à jour vers la version v3.7. En interne, les membres etcd négocient entre eux afin de déterminer la version globale du cluster, qui contrôle la version signalée et les fonctionnalités prises en charge.

Retour arrière

Avant de mettre à jour 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 si nécessaire. Si des utilisateurs rencontrent des problèmes pendant la mise à jour, ils doivent d’abord identifier et résoudre la cause racine. Si le cluster est toujours dans un état mixte, où au moins un membre reste sur la version v3.6, il est possible de remplacer le binaire ou l’image par la version v3.6 antérieure, ou de restaurer directement le cluster à l’aide de l’instantané. Dans cet état mixte, le cluster continue de fonctionner en tant que cluster v3.6, permettant ainsi un retour arrière sans suivre un processus formel de rétrogradation.

Toutefois, une fois que tous les membres ont été mis à jour vers la version 3.7, le cluster est considéré comme entièrement mis à jour et la restauration à une version antérieure à l’aide des binaires n’est plus possible. Dans ce cas, les seules options de récupération sont de restaurer à partir de l’instantané pris avant la mise à jour ou de suivre le guide officiel de rétrogradation en cas de problème lors de la mise à jour.

Procédure de mise à jour

Cet exemple montre comment mettre à jour un cluster etcd v3.6 composé de trois membres, exécuté sur une machine locale. La sortie ci-dessous provient d’une exécution réelle contre etcd v3.6.12 et etcd v3.7.0-rc.0 sur un hôte unique utilisant trois ports de boucle locale.

Étape 1 : vérifier les exigences de mise à jour

Le cluster est-il sain et en cours d’exécution avec la version 3.6.11 ou ultérieure ?

etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint health
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 7.681459ms
localhost:22379 is healthy: successfully committed proposal: took = 7.691750ms
localhost:32379 is healthy: successfully committed proposal: took = 7.698000ms
COMMENT

curl http://localhost:2379/version
<<COMMENT
{"etcdserver":"3.6.12","etcdcluster":"3.6.0","storage":"3.6.0"}
COMMENT

Étape 2 : télécharger la sauvegarde d’instantané depuis le leader

Téléchargez l’instantané de sauvegarde afin de disposer d’une voie de retour en cas de problème.

Le leader etcd possède toujours les données d’application les plus récentes ; récupérez donc l’instantané depuis le leader :

for p in 2379 22379 32379; do
  echo -n "localhost:$p leader="
  curl -sL http://localhost:$p/metrics | grep "^etcd_server_is_leader " | awk '{print $2}'
done
<<COMMENT
localhost:2379 leader=1
localhost:22379 leader=0
localhost:32379 leader=0
COMMENT

etcdctl --endpoints=localhost:2379 snapshot save backup.db
<<COMMENT
{"level":"info","ts":"2026-06-02T07:01:41.863225+0300","caller":"snapshot/v3_snapshot.go:83","msg":"created temporary db file","path":"backup.db.part"}
{"level":"info","ts":"2026-06-02T07:01:41.866451+0300","logger":"client","caller":"v3@v3.6.12/maintenance.go:236","msg":"opened snapshot stream; downloading"}
{"level":"info","ts":"2026-06-02T07:01:41.874080+0300","caller":"snapshot/v3_snapshot.go:96","msg":"fetching snapshot","endpoint":"localhost:2379"}
{"level":"info","ts":"2026-06-02T07:01:41.877203+0300","caller":"snapshot/v3_snapshot.go:111","msg":"fetched snapshot","endpoint":"localhost:2379","size":"98 kB","took":"13.822583ms","etcd-version":"3.6.0"}
{"level":"info","ts":"2026-06-02T07:01:41.877303+0300","caller":"snapshot/v3_snapshot.go:121","msg":"saved","path":"backup.db"}
Snapshot saved at backup.db
Server version 3.6.0
COMMENT

Étape 3 : arrêter un serveur etcd existant

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. Le leader transfère son rôle avant de s’arrêter :

{"level":"info","ts":"2026-06-02T07:01:54.949299+0300","caller":"etcdserver/server.go:1274","msg":"leadership transfer finished","local-member-id":"7339c4e5e833c029","old-leader-member-id":"7339c4e5e833c029","new-leader-member-id":"b548c2511513015","took":"101.052625ms"}
{"level":"info","ts":"2026-06-02T07:01:54.949369+0300","caller":"etcdserver/server.go:2349","msg":"server has stopped; stopping cluster version's monitor"}
{"level":"info","ts":"2026-06-02T07:01:55.503219+0300","caller":"embed/etcd.go:626","msg":"stopped serving peer traffic","address":"127.0.0.1:2380"}

Étape 4 : redémarrer le serveur etcd avec la même configuration

Redémarrez le serveur etcd avec la même configuration, mais avec le binaire etcd mis à jour.

-etcd-old --name ${name} \
+etcd-new --name ${name} \
  --data-dir /path/to/${name}.etcd \
  --listen-client-urls http://localhost:2379 \
  --advertise-client-urls http://localhost:2379 \
  --listen-peer-urls http://localhost:2380 \
  --initial-advertise-peer-urls http://localhost:2380 \
  --initial-cluster s1=http://localhost:2380,s2=http://localhost:22380,s3=http://localhost:32380 \
  --initial-cluster-token tkn \
  --initial-cluster-state new

Le nouvel etcd v3.7 publiera ses informations dans le cluster. À ce stade, le cluster continue de fonctionner selon le protocole v3.6, qui constitue la version la plus basse commune.

{"level":"info","ts":"2026-06-02T07:01:58.920780+0300","caller":"membership/cluster.go:296","msg":"set cluster version from store","cluster-version":"3.6"}

{"level":"info","ts":"2026-06-02T07:01:58.979186+0300","caller":"etcdserver/server.go:1828","msg":"published local member to cluster through raft","local-member-id":"7339c4e5e833c029","local-member-attributes":"{Name:s1 ClientURLs:[http://localhost:2379]}","cluster-id":"7dee9ba76d59ed53","publish-timeout":"7s"}

Vérifiez que chaque membre, puis l’ensemble du cluster, devient sain avec le nouveau binaire etcd v3.7 :

etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint status -w table
<<COMMENT
+-----------------+------------------+------------+-----------------+---------+--------+-----------+
|    ENDPOINT     |        ID        |  VERSION   | STORAGE VERSION | DB SIZE | LEADER | RAFT TERM |
+-----------------+------------------+------------+-----------------+---------+--------+-----------+
|  localhost:2379 | 7339c4e5e833c029 | 3.7.0-rc.0 |           3.6.0 |   98 kB |  false |         3 |
| localhost:22379 | 729934363faa4a24 |     3.6.12 |           3.6.0 |   98 kB |  false |         3 |
| localhost:32379 |  b548c2511513015 |     3.6.12 |           3.6.0 |   98 kB |   true |         3 |
+-----------------+------------------+------------+-----------------+---------+--------+-----------+
COMMENT

Les membres non mis à jour et le membre mis à jour vont générer des messages concernant l’état à version mixte jusqu’à ce que l’intégralité du cluster soit mise à jour. Cela est attendu et cessera une fois que tous les membres du cluster etcd auront été mis à jour vers la version 3.7.

Étape 5 : répéter l’étape 3 et l’étape 4 pour les membres restants

Lorsque tous les membres sont mis à jour, le cluster signalera avec succès la mise à jour vers la version v3.7 :

{"level":"info","ts":"2026-06-02T07:02:36.054783+0300","caller":"etcdserver/server.go:2311","msg":"updating cluster version using v3 API","from":"3.6","to":"3.7"}

{"level":"info","ts":"2026-06-02T07:02:36.059345+0300","caller":"membership/cluster.go:593","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"7339c4e5e833c029","from":"3.6","to":"3.7"}

{"level":"info","ts":"2026-06-02T07:02:36.059409+0300","caller":"etcdserver/server.go:2326","msg":"cluster version is updated","cluster-version":"3.7"}

etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint health
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 550.833µs
localhost:32379 is healthy: successfully committed proposal: took = 733.458µs
localhost:22379 is healthy: successfully committed proposal: took = 714.416µs
COMMENT

curl http://localhost:2379/version
<<COMMENT
{"etcdserver":"3.7.0-rc.0","etcdcluster":"3.7.0","storage":"3.7.0"}
COMMENT

curl http://localhost:22379/version
<<COMMENT
{"etcdserver":"3.7.0-rc.0","etcdcluster":"3.7.0","storage":"3.7.0"}
COMMENT

curl http://localhost:32379/version
<<COMMENT
{"etcdserver":"3.7.0-rc.0","etcdcluster":"3.7.0","storage":"3.7.0"}
COMMENT

3 - Mettre à jour etcd de la version v3.5 à la version v3.6

Processus, listes de vérification et notes sur la mise à niveau d’etcd de la version 3.5 à la version 3.6

Dans le cas général, la mise à niveau d’etcd v3.5 vers v3.6 peut être une mise à niveau progressive sans interruption de service :

un à un, arrêtez les processus etcd v3.5 et remplacez-les par des processus etcd v3.6
après avoir lancé tous les processus v3.6, les nouvelles fonctionnalités de la version v3.6 sont disponibles pour le cluster

Avant de lancer la mise à jour , lisez le reste du présent guide afin de vous préparer.

Listes de vérification pour la mise à jour

Mise à jour 3.5

Important

Avant de mettre à jour vers la version 3.6, assurez-vous que tous vos membres 3.5 sont mis à jour vers la version 3.5.32 ou ultérieure . Les correctifs 3.5.24 à 3.5.26 corrigent plusieurs blocages potentiels liés à la mise à jour ; 3.5.32 ajoute --v2-deprecation=write-only-skip-check et étend etcdutl check v2store afin d’inspecter les enregistrements WAL ainsi que l’instantané v2.

Magasin V2

Note

Si le drapeau --enable-v2 n’est pas configuré ou est défini à false, aucune action supplémentaire n’est requise.

Si --enable-v2 est configuré, exécutez la commande etcdutl check v2store pour vérifier si le v2store contient des données non liées aux membres (données personnalisées). Si aucune donnée personnalisée n’est présente, le drapeau peut être supprimé en toute sécurité. Sinon, consultez le guide de migration v2 pour plus de détails.

Drapeaux ajoutés

+etcd --discovery-token ''
+etcd --discovery-endpoints ''
+etcd --discovery-dial-timeout '2s'
+etcd --discovery-request-timeout '5s'
+etcd --discovery-keepalive-time '2s'
+etcd --discovery-keepalive-timeout '6s'
+etcd --discovery-insecure-transport 'true'
+etcd --discovery-insecure-skip-tls-verify 'false'
+etcd --discovery-cert ''
+etcd --discovery-key ''
+etcd --discovery-cacert ''
+etcd --discovery-user ''
+etcd --discovery-password ''
+etcd --feature-gates
+etcd --log-format

Drapeaux supprimés

-etcd --enable-v2
-etcd --experimental-enable-v2v3
-etcd --proxy
-etcd --proxy-failure-wait
-etcd --proxy-refresh-interval
-etcd --proxy-dial-timeout
-etcd --proxy-write-timeout
-etcd --proxy-read-timeout

Drapeaux obsolètes

Le drapeau etcd --experimental-bootstrap-defrag-threshold-megabytes a été déprécié.


-etcd --experimental-bootstrap-defrag-threshold-megabytes

+etcd --bootstrap-defrag-threshold-megabytes

Le drapeau etcd --experimental-compaction-batch-limit a été déprécié.


-etcd --experimental-compaction-batch-limit

+etcd --compaction-batch-limit

Le drapeau etcd --experimental-compact-hash-check-time a été déprécié.


-etcd --experimental-compact-hash-check-time

+etcd --compact-hash-check-time

Le drapeau etcd --experimental-compaction-sleep-interval a été déprécié.


-etcd --experimental-compaction-sleep-interval

+etcd --compaction-sleep-interval

Le drapeau etcd --experimental-corrupt-check-time a été déprécié.


-etcd --experimental-corrupt-check-time

+etcd --corrupt-check-time

Le drapeau etcd --experimental-enable-distributed-tracing a été déprécié.


-etcd --experimental-enable-distributed-tracing

+etcd --enable-distributed-tracing

Le drapeau etcd --experimental-distributed-tracing-address a été déprécié.


-etcd --experimental-distributed-tracing-address

+etcd --distributed-tracing-address

Le drapeau etcd --experimental-distributed-tracing-instance-id a été déprécié.


-etcd --experimental-distributed-tracing-instance-id

+etcd --distributed-tracing-instance-id

Le drapeau etcd --experimental-distributed-tracing-sampling-rate a été déprécié.


-etcd --experimental-distributed-tracing-sampling-rate

+etcd --distributed-tracing-sampling-rate

Le drapeau etcd --experimental-distributed-tracing-service-name a été déprécié.


-etcd --experimental-distributed-tracing-service-name

+etcd --distributed-tracing-service-name

Le drapeau etcd --experimental-downgrade-check-time a été déprécié.


-etcd --experimental-downgrade-check-time

+etcd --downgrade-check-time

Le drapeau etcd --experimental-max-learners a été déprécié.


-etcd --experimental-max-learners

+etcd --max-learners

Le drapeau etcd --experimental-memory-mlock a été déprécié.


-etcd --experimental-memory-mlock

+etcd --memory-mlock

Le drapeau etcd --experimental-peer-skip-client-san-verification a été déprécié.


-etcd --experimental-peer-skip-client-san-verification

+etcd --peer-skip-client-san-verification

Le drapeau etcd --experimental-snapshot-catchup-entries a été déprécié.


-etcd --experimental-snapshot-catchup-entries

+etcd --snapshot-catchup-entries

Le drapeau etcd --experimental-warning-apply-duration a été déprécié.


-etcd --experimental-warning-apply-duration

+etcd --warning-apply-duration

Le drapeau etcd --experimental-warning-unary-request-duration a été déprécié.


-etcd --experimental-warning-unary-request-duration

+etcd --warning-unary-request-duration

Le drapeau etcd --experimental-watch-progress-notify-interval a été déprécié.


-etcd --experimental-watch-progress-notify-interval

+etcd --watch-progress-notify-interval

Migration des options expérimentales de v3.5 vers les portes fonctionnelles

Porte fonctionnelle correspondant à etcd --experimental-compact-hash-check-enabled=true


-etcd --experimental-compact-hash-check-enabled=true

+etcd --feature-gates=CompactHashCheck=true

Porte fonctionnelle correspondant à etcd --experimental-initial-corrupt-check=true


-etcd --experimental-initial-corrupt-check=true

+etcd --feature-gates=InitialCorruptCheck=true

Porte fonctionnelle correspondant à etcd --experimental-enable-lease-checkpoint=true


-etcd --experimental-enable-lease-checkpoint=true

+etcd --feature-gates=LeaseCheckpoint=true

Porte fonctionnelle correspondant à etcd --experimental-enable-lease-checkpoint-persist=true


-etcd --experimental-enable-lease-checkpoint-persist=true

+etcd --feature-gates=LeaseCheckpointPersist=true

Porte fonctionnelle correspondant à etcd --experimental-stop-grpc-service-on-defrag=true


-etcd --experimental-stop-grpc-service-on-defrag=true

+etcd --feature-gates=StopGRPCServiceOnDefrag=true

Porte fonctionnelle correspondant à etcd --experimental-txn-mode-write-with-shared-buffer=false


-etcd --experimental-txn-mode-write-with-shared-buffer=false

+etcd --feature-gates=TxnModeWriteWithSharedBuffer=false

Drapeaux avec de nouvelles valeurs par défaut

Valeur par défaut d’origine du drapeau etcd --snapshot-count=100000


-etcd --snapshot-count=100000

+etcd --snapshot-count=10000

Valeur par défaut d’origine du drapeau etcd --v2-deprecation='not-yet'


-etcd --v2-deprecation='not-yet'

+etcd --v2-deprecation='write-only'

Valeur par défaut d’origine du drapeau etcd --discovery-fallback='proxy'


-etcd --discovery-fallback='proxy'

+etcd --discovery-fallback='exit'

Différence entre les métriques Prometheus

# metrics added in v3.6
+etcd_network_known_peers
+etcd_server_feature_enabled

Liste de vérification pour la mise à jour du serveur

Exigences de mise à jour

Pour mettre à jour un déploiement etcd existant vers la version 3.6, le cluster en cours d’exécution doit être la version 3.5 ou ultérieure. Si la version est antérieure à 3.5, veuillez mettre à jour vers la version 3.5 avant de procéder à la mise à jour vers la version 3.6.

Préparation

Avant de mettre à jour etcd, testez toujours les services dépendants d’etcd dans un environnement de préproduction avant de déployer la mise à jour dans l’environnement de production.

Versions mixtes

Lors d’une mise à jour, 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 n’est considéré comme mis à jour qu’une fois que tous ses membres ont été mis à jour vers la version v3.6. En interne, les membres etcd négocient entre eux afin de déterminer la version globale du cluster, qui contrôle la version signalée et les fonctionnalités prises en charge.

Retour arrière

Avant de mettre à jour 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 si nécessaire. Si les utilisateurs rencontrent des problèmes pendant la mise à jour, ils doivent d’abord identifier et résoudre la cause racine. Si le cluster est toujours dans un état mixte — où au moins un membre reste sur la version v3.5 —, il est possible de remplacer le binaire ou l’image par la version v3.5 antérieure, ou de restaurer directement le cluster à l’aide de l’instantané. Dans cet état mixte, le cluster continue de fonctionner en tant que cluster v3.5, permettant ainsi un retour arrière sans suivre un processus formel de rétrogradation.

Toutefois, une fois que tous les membres ont été mis à jour vers la version v3.6, le cluster est considéré comme entièrement mis à jour et le simple remplacement des binaires n’est plus un retour arrière valide. Les options de récupération consistent à restaurer depuis l’instantané pris avant la mise à jour ou à suivre le guide officiel de rétrogradation pour revenir à la version d’origine en assurant la cohérence et en évitant toute corruption des données.

Procédure de mise à jour

Cet exemple montre comment mettre à jour un cluster etcd v3.5 composé de 3 membres, en cours d’exécution sur une machine locale.

Étape 1 : vérifier les exigences de mise à jour

Le cluster est-il sain et en cours d’exécution sous la version 3.5.x ?

etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint health
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 2.555774ms
localhost:32379 is healthy: successfully committed proposal: took = 2.631133ms
localhost:22379 is healthy: successfully committed proposal: took = 3.020958ms
COMMENT

curl http://localhost:2379/version
<<COMMENT
{"etcdserver":"3.5.18","etcdcluster":"3.5.0"}
COMMENT

curl http://localhost:22379/version
<<COMMENT
{"etcdserver":"3.5.18","etcdcluster":"3.5.0"}
COMMENT

curl http://localhost:32379/version
<<COMMENT
{"etcdserver":"3.5.18","etcdcluster":"3.5.0"}
COMMENT

Étape 2 : télécharger la sauvegarde d’instantané depuis le leader

Téléchargez l’instantané de sauvegarde afin de disposer d’une voie de retour en cas de problème.

Le leader etcd possède toujours les données d’application les plus récentes ; récupérez donc l’instantané depuis le leader :

curl -sL http://localhost:2379/metrics | grep etcd_server_is_leader
<<COMMENT
# HELP etcd_server_is_leader Whether or not this member is a leader. 1 if is, 0 otherwise.
# TYPE etcd_server_is_leader gauge
etcd_server_is_leader 1
COMMENT

curl -sL http://localhost:22379/metrics | grep etcd_server_is_leader
<<COMMENT
etcd_server_is_leader 0
COMMENT

curl -sL http://localhost:32379/metrics | grep etcd_server_is_leader
<<COMMENT
etcd_server_is_leader 0
COMMENT

etcdctl --endpoints=localhost:2379 snapshot save backup.db
<<COMMENT
{"level":"info","ts":"2025-03-01T04:34:10.336768+0530","caller":"snapshot/v3_snapshot.go:65","msg":"created temporary db file","path":"backup.db.part"}
{"level":"info","ts":"2025-03-01T04:34:10.342373+0530","logger":"client","caller":"v3@v3.5.18/maintenance.go:212","msg":"opened snapshot stream; downloading"}
{"level":"info","ts":"2025-03-01T04:34:10.342433+0530","caller":"snapshot/v3_snapshot.go:73","msg":"fetching snapshot","endpoint":"localhost:2379"}
{"level":"info","ts":"2025-03-01T04:34:10.346482+0530","logger":"client","caller":"v3@v3.5.18/maintenance.go:220","msg":"completed snapshot read; closing"}
{"level":"info","ts":"2025-03-01T04:34:10.348801+0530","caller":"snapshot/v3_snapshot.go:88","msg":"fetched snapshot","endpoint":"localhost:2379","size":"20 kB","took":"now"}
{"level":"info","ts":"2025-03-01T04:34:10.348933+0530","caller":"snapshot/v3_snapshot.go:97","msg":"saved","path":"backup.db"}
Snapshot saved at backup.db
COMMENT

Étape 3 : arrêter un serveur etcd existant

{"level":"info","ts":"2025-03-01T04:31:50.654520+0530","caller":"etcdserver/server.go:2676","msg":"cluster version is updated","cluster-version":"3.5"}
{"level":"info","ts":"2025-03-01T04:34:10.345927+0530","caller":"v3rpc/maintenance.go:130","msg":"sending database snapshot to client","total-bytes":20480,"size":"20 kB"}
{"level":"info","ts":"2025-03-01T04:34:10.346094+0530","caller":"v3rpc/maintenance.go:170","msg":"sending database sha256 checksum to client","total-bytes":20480,"checksum-size":32}
{"level":"info","ts":"2025-03-01T04:34:10.346108+0530","caller":"v3rpc/maintenance.go:179","msg":"successfully sent database snapshot to client","total-bytes":20480,"size":"20 kB","took":"now"}
^C
{"level":"info","ts":"2025-03-01T04:35:01.443045+0530","caller":"osutil/interrupt_unix.go:64","msg":"received signal; shutting down","signal":"interrupt"}
{"level":"info","ts":"2025-03-01T04:35:01.443088+0530","caller":"embed/etcd.go:408","msg":"closing etcd server","name":"node1","data-dir":"/tmp/etcd-node1","advertise-peer-urls":["http://127.0.0.1:2380"],"advertise-client-urls":["http://127.0.0.1:2379"]}
{"level":"info","ts":"2025-03-01T04:35:01.443417+0530","caller":"etcdserver/server.go:1503","msg":"leadership transfer starting","local-member-id":"bf9071f4639c75cc","current-leader-member-id":"bf9071f4639c75cc","transferee-member-id":"91bc3c398fb3c146"}
{"level":"info","ts":"2025-03-01T04:35:01.443441+0530","logger":"raft","caller":"etcdserver/zap_raft.go:77","msg":"bf9071f4639c75cc [term 2] starts to transfer leadership to 91bc3c398fb3c146"}
{"level":"info","ts":"2025-03-01T04:35:01.443455+0530","logger":"raft","caller":"etcdserver/zap_raft.go:77","msg":"bf9071f4639c75cc sends MsgTimeoutNow to 91bc3c398fb3c146 immediately as 91bc3c398fb3c146 already has up-to-date log"}
{"level":"warn","ts":"2025-03-01T04:35:01.443517+0530","caller":"embed/serve.go:179","msg":"stopping insecure grpc server due to error","error":"accept tcp 127.0.0.1:2379: use of closed network connection"}
{"level":"warn","ts":"2025-03-01T04:35:01.443548+0530","caller":"embed/serve.go:181","msg":"stopped insecure grpc server due to error","error":"accept tcp 127.0.0.1:2379: use of closed network connection"}
{"level":"info","ts":"2025-03-01T04:35:01.445536+0530","logger":"raft","caller":"etcdserver/zap_raft.go:77","msg":"bf9071f4639c75cc [term: 2] received a MsgVote message with higher term from 91bc3c398fb3c146 [term: 3]"}
{"level":"info","ts":"2025-03-01T04:35:01.445556+0530","logger":"raft","caller":"etcdserver/zap_raft.go:77","msg":"bf9071f4639c75cc became follower at term 3"}
{"level":"info","ts":"2025-03-01T04:35:01.445565+0530","logger":"raft","caller":"etcdserver/zap_raft.go:77","msg":"bf9071f4639c75cc [logterm: 2, index: 12, vote: 0] cast MsgVote for 91bc3c398fb3c146 [logterm: 2, index: 12] at term 3"}
{"level":"info","ts":"2025-03-01T04:35:01.445572+0530","logger":"raft","caller":"etcdserver/zap_raft.go:77","msg":"raft.node: bf9071f4639c75cc lost leader bf9071f4639c75cc at term 3"}
{"level":"info","ts":"2025-03-01T04:35:01.446773+0530","logger":"raft","caller":"etcdserver/zap_raft.go:77","msg":"raft.node: bf9071f4639c75cc elected leader 91bc3c398fb3c146 at term 3"}
{"level":"info","ts":"2025-03-01T04:35:01.544062+0530","caller":"etcdserver/server.go:1520","msg":"leadership transfer finished","local-member-id":"bf9071f4639c75cc","old-leader-member-id":"bf9071f4639c75cc","new-leader-member-id":"91bc3c398fb3c146","took":"100.640374ms"}
{"level":"info","ts":"2025-03-01T04:35:01.544160+0530","caller":"rafthttp/peer.go:330","msg":"stopping remote peer","remote-peer-id":"91bc3c398fb3c146"}
{"level":"warn","ts":"2025-03-01T04:35:01.544956+0530","caller":"rafthttp/stream.go:286","msg":"closed TCP streaming connection with remote peer","stream-writer-type":"stream MsgApp v2","remote-peer-id":"91bc3c398fb3c146"}
{"level":"info","ts":"2025-03-01T04:35:01.544984+0530","caller":"rafthttp/stream.go:294","msg":"stopped TCP streaming connection with remote peer","stream-writer-type":"stream MsgApp v2","remote-peer-id":"91bc3c398fb3c146"}
{"level":"warn","ts":"2025-03-01T04:35:01.545050+0530","caller":"rafthttp/stream.go:286","msg":"closed TCP streaming connection with remote peer","stream-writer-type":"stream Message","remote-peer-id":"91bc3c398fb3c146"}
{"level":"info","ts":"2025-03-01T04:35:01.545065+0530","caller":"rafthttp/stream.go:294","msg":"stopped TCP streaming connection with remote peer","stream-writer-type":"stream Message","remote-peer-id":"91bc3c398fb3c146"}
{"level":"info","ts":"2025-03-01T04:35:01.545099+0530","caller":"rafthttp/pipeline.go:85","msg":"stopped HTTP pipelining with remote peer","local-member-id":"bf9071f4639c75cc","remote-peer-id":"91bc3c398fb3c146"}
{"level":"warn","ts":"2025-03-01T04:35:01.545156+0530","caller":"rafthttp/stream.go:421","msg":"lost TCP streaming connection with remote peer","stream-reader-type":"stream MsgApp v2","local-member-id":"bf9071f4639c75cc","remote-peer-id":"91bc3c398fb3c146","error":"context canceled"}
{"level":"warn","ts":"2025-03-01T04:35:01.545178+0530","caller":"rafthttp/peer_status.go:66","msg":"peer became inactive (message send to peer failed)","peer-id":"91bc3c398fb3c146","error":"failed to read 91bc3c398fb3c146 on stream MsgApp v2 (context canceled)"}
{"level":"info","ts":"2025-03-01T04:35:01.545199+0530","caller":"rafthttp/stream.go:442","msg":"stopped stream reader with remote peer","stream-reader-type":"stream MsgApp v2","local-member-id":"bf9071f4639c75cc","remote-peer-id":"91bc3c398fb3c146"}
{"level":"warn","ts":"2025-03-01T04:35:01.545246+0530","caller":"rafthttp/stream.go:421","msg":"lost TCP streaming connection with remote peer","stream-reader-type":"stream Message","local-member-id":"bf9071f4639c75cc","remote-peer-id":"91bc3c398fb3c146","error":"context canceled"}
{"level":"info","ts":"2025-03-01T04:35:01.545263+0530","caller":"rafthttp/stream.go:442","msg":"stopped stream reader with remote peer","stream-reader-type":"stream Message","local-member-id":"bf9071f4639c75cc","remote-peer-id":"91bc3c398fb3c146"}
{"level":"info","ts":"2025-03-01T04:35:01.545272+0530","caller":"rafthttp/peer.go:335","msg":"stopped remote peer","remote-peer-id":"91bc3c398fb3c146"}
{"level":"info","ts":"2025-03-01T04:35:01.545282+0530","caller":"rafthttp/peer.go:330","msg":"stopping remote peer","remote-peer-id":"fd422379fda50e48"}
{"level":"warn","ts":"2025-03-01T04:35:01.545307+0530","caller":"rafthttp/stream.go:286","msg":"closed TCP streaming connection with remote peer","stream-writer-type":"stream MsgApp v2","remote-peer-id":"fd422379fda50e48"}
{"level":"info","ts":"2025-03-01T04:35:01.545328+0530","caller":"rafthttp/stream.go:294","msg":"stopped TCP streaming connection with remote peer","stream-writer-type":"stream MsgApp v2","remote-peer-id":"fd422379fda50e48"}
{"level":"warn","ts":"2025-03-01T04:35:01.545359+0530","caller":"rafthttp/stream.go:286","msg":"closed TCP streaming connection with remote peer","stream-writer-type":"stream Message","remote-peer-id":"fd422379fda50e48"}
{"level":"info","ts":"2025-03-01T04:35:01.545379+0530","caller":"rafthttp/stream.go:294","msg":"stopped TCP streaming connection with remote peer","stream-writer-type":"stream Message","remote-peer-id":"fd422379fda50e48"}
{"level":"info","ts":"2025-03-01T04:35:01.545410+0530","caller":"rafthttp/pipeline.go:85","msg":"stopped HTTP pipelining with remote peer","local-member-id":"bf9071f4639c75cc","remote-peer-id":"fd422379fda50e48"}
{"level":"warn","ts":"2025-03-01T04:35:01.545467+0530","caller":"rafthttp/stream.go:421","msg":"lost TCP streaming connection with remote peer","stream-reader-type":"stream MsgApp v2","local-member-id":"bf9071f4639c75cc","remote-peer-id":"fd422379fda50e48","error":"context canceled"}
{"level":"warn","ts":"2025-03-01T04:35:01.545485+0530","caller":"rafthttp/peer_status.go:66","msg":"peer became inactive (message send to peer failed)","peer-id":"fd422379fda50e48","error":"failed to read fd422379fda50e48 on stream MsgApp v2 (context canceled)"}
{"level":"info","ts":"2025-03-01T04:35:01.545504+0530","caller":"rafthttp/stream.go:442","msg":"stopped stream reader with remote peer","stream-reader-type":"stream MsgApp v2","local-member-id":"bf9071f4639c75cc","remote-peer-id":"fd422379fda50e48"}
{"level":"warn","ts":"2025-03-01T04:35:01.545560+0530","caller":"rafthttp/stream.go:421","msg":"lost TCP streaming connection with remote peer","stream-reader-type":"stream Message","local-member-id":"bf9071f4639c75cc","remote-peer-id":"fd422379fda50e48","error":"context canceled"}
{"level":"info","ts":"2025-03-01T04:35:01.545577+0530","caller":"rafthttp/stream.go:442","msg":"stopped stream reader with remote peer","stream-reader-type":"stream Message","local-member-id":"bf9071f4639c75cc","remote-peer-id":"fd422379fda50e48"}
{"level":"info","ts":"2025-03-01T04:35:01.545592+0530","caller":"rafthttp/peer.go:335","msg":"stopped remote peer","remote-peer-id":"fd422379fda50e48"}
{"level":"warn","ts":"2025-03-01T04:35:01.545669+0530","caller":"rafthttp/http.go:413","msg":"failed to find remote peer in cluster","local-member-id":"bf9071f4639c75cc","remote-peer-id-stream-handler":"bf9071f4639c75cc","remote-peer-id-from":"91bc3c398fb3c146","cluster-id":"59a05384c9b79ee"}
{"level":"warn","ts":"2025-03-01T04:35:01.545698+0530","caller":"rafthttp/http.go:413","msg":"failed to find remote peer in cluster","local-member-id":"bf9071f4639c75cc","remote-peer-id-stream-handler":"bf9071f4639c75cc","remote-peer-id-from":"fd422379fda50e48","cluster-id":"59a05384c9b79ee"}
{"level":"warn","ts":"2025-03-01T04:35:01.545732+0530","caller":"rafthttp/http.go:413","msg":"failed to find remote peer in cluster","local-member-id":"bf9071f4639c75cc","remote-peer-id-stream-handler":"bf9071f4639c75cc","remote-peer-id-from":"91bc3c398fb3c146","cluster-id":"59a05384c9b79ee"}
{"level":"warn","ts":"2025-03-01T04:35:01.545765+0530","caller":"rafthttp/http.go:413","msg":"failed to find remote peer in cluster","local-member-id":"bf9071f4639c75cc","remote-peer-id-stream-handler":"bf9071f4639c75cc","remote-peer-id-from":"fd422379fda50e48","cluster-id":"59a05384c9b79ee"}
{"level":"info","ts":"2025-03-01T04:35:01.549658+0530","caller":"embed/etcd.go:613","msg":"stopping serving peer traffic","address":"127.0.0.1:2380"}
{"level":"info","ts":"2025-03-01T04:35:02.550532+0530","caller":"embed/etcd.go:618","msg":"stopped serving peer traffic","address":"127.0.0.1:2380"}
{"level":"info","ts":"2025-03-01T04:35:02.550561+0530","caller":"embed/etcd.go:410","msg":"closed etcd server","name":"node1","data-dir":"/tmp/etcd-node1","advertise-peer-urls":["http://127.0.0.1:2380"],"advertise-client-urls":["http://127.0.0.1:2379"]}

Étape 4 : redémarrer le serveur etcd avec la même configuration

Redémarrez le serveur etcd avec la même configuration, mais avec le binaire etcd mis à jour.

-etcd-old --name ${name} \
+etcd-new --name ${name} \
  --data-dir /path/to/${name}.etcd \
  --listen-client-urls http://localhost:2379 \
  --advertise-client-urls http://localhost:2379 \
  --listen-peer-urls http://localhost:2380 \
  --initial-advertise-peer-urls http://localhost:2380 \
  --initial-cluster s1=http://localhost:2380,s2=http://localhost:22380,s3=http://localhost:32380 \
  --initial-cluster-token tkn \
  --initial-cluster-state new

Le nouvel etcd v3.6 publiera ses informations dans le cluster. À ce stade, le cluster continue de fonctionner selon le protocole v3.5, qui constitue la version la plus basse commune.

{"level":"info","ts":"2025-03-01T04:40:36.828+0530","caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.5"}

{"level":"info","ts":"2025-03-01T04:40:36.889+0530","caller":"membership/cluster.go:539","msg":"updated cluster version","cluster-id":"59a05384c9b79ee","local-member-id":"bf9071f4639c75cc","from":"3.0","to":"3.5"}

{"level":"info","ts":"2025-03-01T04:40:36.828+0530","caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.5"}

{"level":"info","ts":"2025-03-01T04:40:36.894+0530","caller":"etcdserver/server.go:1686","msg":"published local member to cluster through raft","local-member-id":"bf9071f4639c75cc","local-member-attributes":"{Name:node1 ClientURLs:[http://127.0.0.1:2379]}","cluster-id":"59a05384c9b79ee","publish-timeout":"7s"}

Vérifiez que chaque membre, puis l’ensemble du cluster, devient sain avec le nouveau binaire etcd v3.6 :

etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 1.704998ms
localhost:22379 is healthy: successfully committed proposal: took = 2.331754ms
localhost:32379 is healthy: successfully committed proposal: took = 2.490705ms
COMMENT

Les membres non mis à jour afficheront des avertissements tels que les suivants jusqu’à ce que tout le cluster soit mis à jour.

Cela est attendu et cessera une fois que tous les membres du cluster etcd auront été mis à jour vers la version 3.6 :

{"level":"warn","ts":"2025-03-01T04:40:37.545960+0530","caller":"etcdserver/cluster_util.go:189","msg":"leader found higher-versioned member","local-member-version":"3.5.18","remote-member-id":"bf9071f4639c75cc","remote-member-version":"3.6.0-alpha.0"}

Étape 5 : répéter l’étape 3 et l’étape 4 pour les membres restants

Lorsque tous les membres sont mis à jour, le cluster signalera avec succès la mise à jour vers la version v3.6 :

Membre 1 :

{"level":"info","ts":"2025-03-01T04:58:32.375+0530","caller":"etcdserver/server.go:2149","msg":"updating cluster version using v3 API","from":"3.5","to":"3.6"} {"level":"info","ts":"2025-03-01T04:58:32.377+0530","caller":"etcdserver/server.go:2164","msg":"cluster version is updated","cluster-version":"3.6"}

Membre 2 :

{"level":"info","ts":"2025-03-01T04:58:32.377+0530","caller":"membership/cluster.go:539","msg":"updated cluster version","cluster-id":"59a05384c9b79ee","local-member-id":"91bc3c398fb3c146","from":"3.5","to":"3.6"}

Membre 3 :

{"level":"info","ts":"2025-03-01T04:58:32.377+0530","caller":"membership/cluster.go:539","msg":"updated cluster version","cluster-id":"59a05384c9b79ee","local-member-id":"fd422379fda50e48","from":"3.5","to":"3.6"}

endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 492.834µs
localhost:22379 is healthy: successfully committed proposal: took = 1.015025ms
localhost:32379 is healthy: successfully committed proposal: took = 1.853077ms
COMMENT

curl http://localhost:2379/version
<<COMMENT
{"etcdserver":"3.6.0-alpha.0","etcdcluster":"3.6.0"}
COMMENT

curl http://localhost:22379/version
<<COMMENT
{"etcdserver":"3.6.0-alpha.0","etcdcluster":"3.6.0"}
COMMENT

curl http://localhost:32379/version
<<COMMENT
{"etcdserver":"3.6.0-alpha.0","etcdcluster":"3.6.0"}
COMMENT

4 - Mettre à jour etcd de 3.4 à 3.5

Processus, listes de vérification et notes sur la mise à niveau d’etcd de la version 3.4 à la 3.5

Dans le cas général, la mise à niveau d’etcd 3.4 vers 3.5 peut être effectuée sans interruption de service, en mode mise à niveau progressive :

un par un, arrêtez les processus etcd v3.4 et remplacez-les par des processus etcd v3.5
après avoir lancé tous les processus v3.5, les nouvelles fonctionnalités de la version v3.5 sont disponibles pour le cluster

Avant de lancer la mise à jour , lisez le reste du présent guide afin de vous préparer.

Listes de vérification pour la mise à jour

Avertissement

Lorsque on migre depuis la version v2 sans données v3 , le serveur etcd v3.2+ provoque une panne lorsqu’il restaure à partir d’un instantané existant mais qu’aucun fichier v3 ETCD_DATA_DIR/member/snap/db n’est présent. Cela se produit lorsque le serveur a été migré depuis la version v2 sans données v3 précédentes. Cela empêche également la perte accidentelle de données v3 (par exemple, le fichier db pourrait avoir été déplacé). etcd exige que les opérations après migration vers v3 ne soient effectuées que si des données v3 sont présentes. N’effectuez pas la mise à jour vers des versions v3 plus récentes tant que le serveur v3.0 ne contient pas de données v3.

Avertissement

Si votre cluster a l’authentification activée, la mise à niveau progressive à partir d’une version 3.4 ou antérieure n’est pas prise en charge, car la version 3.5 modifie le format des entrées WAL liées à l’authentification .

Changements de rupture mis en évidence dans la version 3.5.

Métriques Prometheus `etcd_debugging_mvcc_db_total_size_in_bytes` obsolètes

v3.5 a promu les métriques Prometheus etcd_debugging_mvcc_db_total_size_in_bytes à etcd_mvcc_db_total_size_in_bytes, afin de favoriser la surveillance du stockage etcd. La version v3.5 déprécie complètement etcd_debugging_mvcc_db_total_size_in_bytes.

-etcd_debugging_mvcc_db_total_size_in_bytes
+etcd_mvcc_db_total_size_in_bytes

Notez que les métriques de l’espace de noms etcd_debugging_* sont marquées comme expérimentales. Au fur et à mesure que nous améliorons le guide de surveillance, certaines métriques pourraient être promues.

Métriques Prometheus `etcd_debugging_mvcc_put_total` obsolètes

v3.5 a promu les métriques Prometheus etcd_debugging_mvcc_put_total à etcd_mvcc_put_total, afin de favoriser la surveillance du stockage etcd. La version v3.5 déprécie complètement etcd_debugging_mvcc_put_total.

-etcd_debugging_mvcc_put_total
+etcd_mvcc_put_total

Métriques Prometheus `etcd_debugging_mvcc_delete_total` obsolètes

v3.5 a promu les métriques Prometheus etcd_debugging_mvcc_delete_total à etcd_mvcc_delete_total, afin de favoriser la surveillance du stockage etcd. La version v3.5 déprécie complètement etcd_debugging_mvcc_delete_total.

-etcd_debugging_mvcc_delete_total
+etcd_mvcc_delete_total

Métriques Prometheus `etcd_debugging_mvcc_txn_total` obsolètes

v3.5 a promu les métriques Prometheus etcd_debugging_mvcc_txn_total à etcd_mvcc_txn_total, afin de favoriser la surveillance du stockage etcd. La version v3.5 déprécie complètement etcd_debugging_mvcc_txn_total.

-etcd_debugging_mvcc_txn_total
+etcd_mvcc_txn_total

Métriques Prometheus `etcd_debugging_mvcc_range_total` obsolètes

v3.5 a promu les métriques Prometheus etcd_debugging_mvcc_range_total à etcd_mvcc_range_total, afin de favoriser la surveillance du stockage etcd. La version v3.5 déprécie complètement etcd_debugging_mvcc_range_total.

-etcd_debugging_mvcc_range_total
+etcd_mvcc_range_total

Dépréciation de `etcd --logger capnslog`

La version 3.5 utilise par défaut --logger=zap afin de prendre en charge plusieurs sorties de journalisation et la journalisation structurée.

etcd --logger=capnslog a été déprécié à partir de la version 3.5, et --logger=zap est désormais la valeur par défaut.

-etcd --logger=capnslog
+etcd --logger=zap --log-outputs=stderr

+# to write logs to stderr and a.log file at the same time
+etcd --logger=zap --log-outputs=stderr,a.log

v3.4 ajoute la prise en charge de etcd --logger=zap pour la journalisation structurée et plusieurs sorties de journal. La motivation principale est de favoriser la surveillance automatisée d’etcd, plutôt que d’analyser les journaux serveur lorsqu’il commence à présenter des anomalies. Les développements futurs viseront à réduire au minimum la quantité de logs générés par etcd, et à faciliter sa surveillance grâce aux métriques et aux alertes. etcd --logger=capnslog sera déprécié à partir de v3.5.

Dépréciation de `etcd --log-output`

v3.4 a renommé etcd --log-output en --log-outputs afin de prendre en charge plusieurs sorties de journalisation.

etcd --log-output a été déprécié à partir de la version 3.5.

-etcd --log-output=stderr
+etcd --log-outputs=stderr

Dépréciation de le drapeau `etcd --debug` (maintenant `--log-level=debug`)

Le drapeau etcd --debug a été déprécié.

-etcd --debug
+etcd --log-level debug

Dépréciation de `etcd --log-package-levels`

Le drapeau etcd --log-package-levels pour capnslog a été déprécié.

Maintenant, etcd --logger=zap est la valeur par défaut.

-etcd --log-package-levels 'etcdmain=CRITICAL,etcdserver=DEBUG'
+etcd --logger=zap --log-outputs=stderr

Dépréciation de `[CLIENT-URL]/config/local/log`

L’endpoint /config/local/log est déprécié à partir de la version 3.5, tout comme le drapeau etcd --log-package-levels.

-$ curl http://127.0.0.1:2379/config/local/log -XPUT -d '{"Level":"DEBUG"}'
-# debug logging enabled

Modifier les points d’accès HTTP de la passerelle gRPC (obsolète `/v3beta`)

Avant

curl -L http://localhost:2379/v3beta/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'

Après

curl -L http://localhost:2379/v3/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'

/v3beta a été supprimé dans la version 3.5.

Liste de vérification pour la mise à jour du serveur

Exigences de mise à jour

Pour mettre à jour un déploiement etcd existant vers la version 3.5, le cluster en cours d’exécution doit être la version 3.4 ou ultérieure. Si la version est antérieure à 3.4, veuillez mettre à jour vers la version 3.4 avant de procéder à la mise à jour vers la version 3.5.

Préparation

Avant de mettre à jour etcd, testez toujours les services dépendants d’etcd dans un environnement de préproduction avant de déployer la mise à jour dans l’environnement de production.

Avant de commencer, téléchargez l’instantané de sauvegarde . Si une erreur survient lors de la mise à jour, il sera possible d’utiliser cette sauvegarde pour rétrograder vers la version existante d’etcd. Veuillez noter que la commande snapshot ne sauvegarde que les données v3. Pour les données v2, consultez sauvegarde du magasin de données v2 .

Versions mixtes

Lors d’une mise à jour, 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 n’est considéré comme mis à jour qu’une fois que tous ses membres ont été mis à jour vers la version 3.5. En interne, les membres etcd négocient entre eux afin de déterminer la version globale du cluster, qui contrôle la version signalée et les fonctionnalités prises en charge.

Limitations

Note : Si le cluster ne contient que des données v3 et aucune donnée v2, il n’est pas soumis à cette limitation.

Si le cluster sert un jeu de données v2 dont la taille dépasse 50 Mo, chaque membre nouvellement mis à jour peut prendre jusqu’à deux minutes pour rattraper le cluster existant. Vérifiez la taille d’un instantané récent afin d’estimer la taille totale des données. Autrement dit, le plus sûr est d’attendre deux minutes entre chaque mise à jour de membre.

Pour une taille totale de données bien plus importante, de 100 Mo ou plus, ce processus unique peut prendre encore plus de temps. Les administrateurs de clusters etcd très volumineux de cette ampleur peuvent librement contacter l’équipe etcd avant la mise à jour, et nous serons heureux de leur fournir des conseils sur la procédure.

Rétrogradation

Si tous les membres ont été mis à jour vers la version v3.5, le cluster sera mis à jour vers la v3.5, et un retour en arrière depuis cet état finalisé est impossible. Toutefois, si un seul membre reste en version v3.4, le cluster et ses opérations restent “v3.4”, et il est possible, depuis cet état de cluster mixte, de revenir à l’utilisation d’un binaire etcd v3.4 sur tous les membres.

Veuillez télécharger la sauvegarde d’instantané afin de permettre la rétrogradation du cluster, même après sa mise à jour complète.

Procédure de mise à jour

Cet exemple montre comment mettre à jour un cluster etcd v3.4 à trois membres en cours d’exécution sur une machine locale.

Étape 1 : vérifier les exigences de mise à jour

Le cluster est-il sain et en cours d’exécution sous la version 3.4.x ?

etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint health
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 2.118638ms
localhost:22379 is healthy: successfully committed proposal: took = 3.631388ms
localhost:32379 is healthy: successfully committed proposal: took = 2.157051ms
COMMENT

curl http://localhost:2379/version
<<COMMENT
{"etcdserver":"3.4.0","etcdcluster":"3.4.0"}
COMMENT

curl http://localhost:22379/version
<<COMMENT
{"etcdserver":"3.4.0","etcdcluster":"3.4.0"}
COMMENT

curl http://localhost:32379/version
<<COMMENT
{"etcdserver":"3.4.0","etcdcluster":"3.4.0"}
COMMENT

Étape 2 : télécharger la sauvegarde d’instantané depuis le leader

Téléchargez l’instantané de sauvegarde afin de disposer d’une voie de retour en cas de problème.

Le leader etcd possède toujours les données d’application les plus récentes ; récupérez donc l’instantané depuis le leader :

curl -sL http://localhost:2379/metrics | grep etcd_server_is_leader
<<COMMENT
# HELP etcd_server_is_leader Whether or not this member is a leader. 1 if is, 0 otherwise.
# TYPE etcd_server_is_leader gauge
etcd_server_is_leader 1
COMMENT

curl -sL http://localhost:22379/metrics | grep etcd_server_is_leader
<<COMMENT
etcd_server_is_leader 0
COMMENT

curl -sL http://localhost:32379/metrics | grep etcd_server_is_leader
<<COMMENT
etcd_server_is_leader 0
COMMENT

etcdctl --endpoints=localhost:2379 snapshot save backup.db
<<COMMENT
{"level":"info","ts":1526585787.148433,"caller":"snapshot/v3_snapshot.go:109","msg":"created temporary db file","path":"backup.db.part"}
{"level":"info","ts":1526585787.1485257,"caller":"snapshot/v3_snapshot.go:120","msg":"fetching snapshot","endpoint":"localhost:2379"}
{"level":"info","ts":1526585787.1519694,"caller":"snapshot/v3_snapshot.go:133","msg":"fetched snapshot","endpoint":"localhost:2379","took":0.003502721}
{"level":"info","ts":1526585787.1520295,"caller":"snapshot/v3_snapshot.go:142","msg":"saved","path":"backup.db"}
Snapshot saved at backup.db
COMMENT

Étape 3 : arrêter un serveur etcd existant

{"level":"info","ts":1526587281.2001143,"caller":"etcdserver/server.go:2249","msg":"updating cluster version","from":"3.0","to":"3.4"}
{"level":"info","ts":1526587281.2010646,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"7339c4e5e833c029","from":"3.0","from":"3.4"}
{"level":"info","ts":1526587281.2012327,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.4"}
{"level":"info","ts":1526587281.2013083,"caller":"etcdserver/server.go:2272","msg":"cluster version is updated","cluster-version":"3.4"}



^C{"level":"info","ts":1526587299.0717514,"caller":"osutil/interrupt_unix.go:63","msg":"received signal; shutting down","signal":"interrupt"}
{"level":"info","ts":1526587299.0718873,"caller":"embed/etcd.go:285","msg":"closing etcd server","name":"s1","data-dir":"/tmp/etcd/s1","advertise-peer-urls":["http://localhost:2380"],"advertise-client-urls":["http://localhost:2379"]}
{"level":"info","ts":1526587299.0722554,"caller":"etcdserver/server.go:1341","msg":"leadership transfer starting","local-member-id":"7339c4e5e833c029","current-leader-member-id":"7339c4e5e833c029","transferee-member-id":"729934363faa4a24"}
{"level":"info","ts":1526587299.0723994,"caller":"raft/raft.go:1107","msg":"7339c4e5e833c029 [term 3] starts to transfer leadership to 729934363faa4a24"}
{"level":"info","ts":1526587299.0724802,"caller":"raft/raft.go:1113","msg":"7339c4e5e833c029 sends MsgTimeoutNow to 729934363faa4a24 immediately as 729934363faa4a24 already has up-to-date log"}
{"level":"info","ts":1526587299.0737045,"caller":"raft/raft.go:797","msg":"7339c4e5e833c029 [term: 3] received a MsgVote message with higher term from 729934363faa4a24 [term: 4]"}
{"level":"info","ts":1526587299.0737681,"caller":"raft/raft.go:656","msg":"7339c4e5e833c029 became follower at term 4"}
{"level":"info","ts":1526587299.073831,"caller":"raft/raft.go:882","msg":"7339c4e5e833c029 [logterm: 3, index: 9, vote: 0] cast MsgVote for 729934363faa4a24 [logterm: 3, index: 9] at term 4"}
{"level":"info","ts":1526587299.0738947,"caller":"raft/node.go:312","msg":"raft.node: 7339c4e5e833c029 lost leader 7339c4e5e833c029 at term 4"}
{"level":"info","ts":1526587299.0748374,"caller":"raft/node.go:306","msg":"raft.node: 7339c4e5e833c029 elected leader 729934363faa4a24 at term 4"}
{"level":"info","ts":1526587299.1726425,"caller":"etcdserver/server.go:1362","msg":"leadership transfer finished","local-member-id":"7339c4e5e833c029","old-leader-member-id":"7339c4e5e833c029","new-leader-member-id":"729934363faa4a24","took":0.100389359}
{"level":"info","ts":1526587299.1728148,"caller":"rafthttp/peer.go:333","msg":"stopping remote peer","remote-peer-id":"b548c2511513015"}
{"level":"warn","ts":1526587299.1751974,"caller":"rafthttp/stream.go:291","msg":"closed TCP streaming connection with remote peer","stream-writer-type":"stream MsgApp v2","remote-peer-id":"b548c2511513015"}
{"level":"warn","ts":1526587299.1752589,"caller":"rafthttp/stream.go:301","msg":"stopped TCP streaming connection with remote peer","stream-writer-type":"stream MsgApp v2","remote-peer-id":"b548c2511513015"}
{"level":"warn","ts":1526587299.177348,"caller":"rafthttp/stream.go:291","msg":"closed TCP streaming connection with remote peer","stream-writer-type":"stream Message","remote-peer-id":"b548c2511513015"}
{"level":"warn","ts":1526587299.1774004,"caller":"rafthttp/stream.go:301","msg":"stopped TCP streaming connection with remote peer","stream-writer-type":"stream Message","remote-peer-id":"b548c2511513015"}
{"level":"info","ts":1526587299.177515,"caller":"rafthttp/pipeline.go:86","msg":"stopped HTTP pipelining with remote peer","local-member-id":"7339c4e5e833c029","remote-peer-id":"b548c2511513015"}
{"level":"warn","ts":1526587299.1777067,"caller":"rafthttp/stream.go:436","msg":"lost TCP streaming connection with remote peer","stream-reader-type":"stream MsgApp v2","local-member-id":"7339c4e5e833c029","remote-peer-id":"b548c2511513015","error":"read tcp 127.0.0.1:34636->127.0.0.1:32380: use of closed network connection"}
{"level":"info","ts":1526587299.1778402,"caller":"rafthttp/stream.go:459","msg":"stopped stream reader with remote peer","stream-reader-type":"stream MsgApp v2","local-member-id":"7339c4e5e833c029","remote-peer-id":"b548c2511513015"}
{"level":"warn","ts":1526587299.1780295,"caller":"rafthttp/stream.go:436","msg":"lost TCP streaming connection with remote peer","stream-reader-type":"stream Message","local-member-id":"7339c4e5e833c029","remote-peer-id":"b548c2511513015","error":"read tcp 127.0.0.1:34634->127.0.0.1:32380: use of closed network connection"}
{"level":"info","ts":1526587299.1780987,"caller":"rafthttp/stream.go:459","msg":"stopped stream reader with remote peer","stream-reader-type":"stream Message","local-member-id":"7339c4e5e833c029","remote-peer-id":"b548c2511513015"}
{"level":"info","ts":1526587299.1781602,"caller":"rafthttp/peer.go:340","msg":"stopped remote peer","remote-peer-id":"b548c2511513015"}
{"level":"info","ts":1526587299.1781986,"caller":"rafthttp/peer.go:333","msg":"stopping remote peer","remote-peer-id":"729934363faa4a24"}
{"level":"warn","ts":1526587299.1802843,"caller":"rafthttp/stream.go:291","msg":"closed TCP streaming connection with remote peer","stream-writer-type":"stream MsgApp v2","remote-peer-id":"729934363faa4a24"}
{"level":"warn","ts":1526587299.1803446,"caller":"rafthttp/stream.go:301","msg":"stopped TCP streaming connection with remote peer","stream-writer-type":"stream MsgApp v2","remote-peer-id":"729934363faa4a24"}
{"level":"warn","ts":1526587299.1824749,"caller":"rafthttp/stream.go:291","msg":"closed TCP streaming connection with remote peer","stream-writer-type":"stream Message","remote-peer-id":"729934363faa4a24"}
{"level":"warn","ts":1526587299.18255,"caller":"rafthttp/stream.go:301","msg":"stopped TCP streaming connection with remote peer","stream-writer-type":"stream Message","remote-peer-id":"729934363faa4a24"}
{"level":"info","ts":1526587299.18261,"caller":"rafthttp/pipeline.go:86","msg":"stopped HTTP pipelining with remote peer","local-member-id":"7339c4e5e833c029","remote-peer-id":"729934363faa4a24"}
{"level":"warn","ts":1526587299.1827736,"caller":"rafthttp/stream.go:436","msg":"lost TCP streaming connection with remote peer","stream-reader-type":"stream MsgApp v2","local-member-id":"7339c4e5e833c029","remote-peer-id":"729934363faa4a24","error":"read tcp 127.0.0.1:51482->127.0.0.1:22380: use of closed network connection"}
{"level":"info","ts":1526587299.182845,"caller":"rafthttp/stream.go:459","msg":"stopped stream reader with remote peer","stream-reader-type":"stream MsgApp v2","local-member-id":"7339c4e5e833c029","remote-peer-id":"729934363faa4a24"}
{"level":"warn","ts":1526587299.1830168,"caller":"rafthttp/stream.go:436","msg":"lost TCP streaming connection with remote peer","stream-reader-type":"stream Message","local-member-id":"7339c4e5e833c029","remote-peer-id":"729934363faa4a24","error":"context canceled"}
{"level":"warn","ts":1526587299.1831107,"caller":"rafthttp/peer_status.go:65","msg":"peer became inactive","peer-id":"729934363faa4a24","error":"failed to read 729934363faa4a24 on stream Message (context canceled)"}
{"level":"info","ts":1526587299.1831737,"caller":"rafthttp/stream.go:459","msg":"stopped stream reader with remote peer","stream-reader-type":"stream Message","local-member-id":"7339c4e5e833c029","remote-peer-id":"729934363faa4a24"}
{"level":"info","ts":1526587299.1832306,"caller":"rafthttp/peer.go:340","msg":"stopped remote peer","remote-peer-id":"729934363faa4a24"}
{"level":"warn","ts":1526587299.1837125,"caller":"rafthttp/http.go:424","msg":"failed to find remote peer in cluster","local-member-id":"7339c4e5e833c029","remote-peer-id-stream-handler":"7339c4e5e833c029","remote-peer-id-from":"b548c2511513015","cluster-id":"7dee9ba76d59ed53"}
{"level":"warn","ts":1526587299.1840093,"caller":"rafthttp/http.go:424","msg":"failed to find remote peer in cluster","local-member-id":"7339c4e5e833c029","remote-peer-id-stream-handler":"7339c4e5e833c029","remote-peer-id-from":"b548c2511513015","cluster-id":"7dee9ba76d59ed53"}
{"level":"warn","ts":1526587299.1842315,"caller":"rafthttp/http.go:424","msg":"failed to find remote peer in cluster","local-member-id":"7339c4e5e833c029","remote-peer-id-stream-handler":"7339c4e5e833c029","remote-peer-id-from":"729934363faa4a24","cluster-id":"7dee9ba76d59ed53"}
{"level":"warn","ts":1526587299.1844475,"caller":"rafthttp/http.go:424","msg":"failed to find remote peer in cluster","local-member-id":"7339c4e5e833c029","remote-peer-id-stream-handler":"7339c4e5e833c029","remote-peer-id-from":"729934363faa4a24","cluster-id":"7dee9ba76d59ed53"}
{"level":"info","ts":1526587299.2056687,"caller":"embed/etcd.go:473","msg":"stopping serving peer traffic","address":"127.0.0.1:2380"}
{"level":"info","ts":1526587299.205819,"caller":"embed/etcd.go:480","msg":"stopped serving peer traffic","address":"127.0.0.1:2380"}
{"level":"info","ts":1526587299.2058413,"caller":"embed/etcd.go:289","msg":"closed etcd server","name":"s1","data-dir":"/tmp/etcd/s1","advertise-peer-urls":["http://localhost:2380"],"advertise-client-urls":["http://localhost:2379"]}

Étape 4 : redémarrer le serveur etcd avec la même configuration

Redémarrez le serveur etcd avec la même configuration, mais avec le binaire etcd mis à jour.

-etcd-old --name s1 \
+etcd-new --name s1 \
  --data-dir /tmp/etcd/s1 \
  --listen-client-urls http://localhost:2379 \
  --advertise-client-urls http://localhost:2379 \
  --listen-peer-urls http://localhost:2380 \
  --initial-advertise-peer-urls http://localhost:2380 \
  --initial-cluster s1=http://localhost:2380,s2=http://localhost:22380,s3=http://localhost:32380 \
  --initial-cluster-token tkn \
  --initial-cluster-state new

Le nouvel etcd v3.5 publiera ses informations dans le cluster. À ce stade, le cluster continue de fonctionner selon le protocole v3.4, qui constitue la version la plus basse commune.

{"level":"info","ts":1526586617.1647713,"caller":"membership/cluster.go:485","msg":"set initial cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"7339c4e5e833c029","cluster-version":"3.0"}

{"level":"info","ts":1526586617.1648536,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.0"}

{"level":"info","ts":1526586617.1649303,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"7339c4e5e833c029","from":"3.0","from":"3.4"}

{"level":"info","ts":1526586617.1649797,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.4"}

{"level":"info","ts":1526586617.2107732,"caller":"etcdserver/server.go:1770","msg":"published local member to cluster through raft","local-member-id":"7339c4e5e833c029","local-member-attributes":"{Name:s1 ClientURLs:[http://localhost:2379]}","request-path":"/0/members/7339c4e5e833c029/attributes","cluster-id":"7dee9ba76d59ed53","publish-timeout":7}

Vérifiez que chaque membre, puis l’intégralité du cluster, deviennent sains avec le nouveau binaire etcd v3.5 :

etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
<<COMMENT
localhost:32379 is healthy: successfully committed proposal: took = 2.337471ms
localhost:22379 is healthy: successfully committed proposal: took = 1.130717ms
localhost:2379 is healthy: successfully committed proposal: took = 2.124843ms
COMMENT

Les membres non mis à jour afficheront des avertissements tels que les suivants jusqu’à ce que tout le cluster soit mis à jour.

Cela est attendu et cessera une fois que tous les membres du cluster etcd auront été mis à jour vers la version 3.5 :

:41.942121 W | etcdserver: member 7339c4e5e833c029 has a higher version 3.5.0
:45.945154 W | etcdserver: the local etcd version 3.4.0 is not up-to-date

Étape 5 : répéter l’étape 3 et l’étape 4 pour les membres restants

Lorsque tous les membres sont mis à jour, le cluster signalera avec succès la mise à jour vers la version 3.5 :

Membre 1 :

{"level":"info","ts":1526586949.0920913,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.5"} {"level":"info","ts":1526586949.0921566,"caller":"etcdserver/server.go:2272","msg":"cluster version is updated","cluster-version":"3.5"}

Membre 2 :

{"level":"info","ts":1526586949.092117,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"729934363faa4a24","from":"3.4","from":"3.5"} {"level":"info","ts":1526586949.0923078,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.5"}

Membre 3 :

{"level":"info","ts":1526586949.0921423,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"b548c2511513015","from":"3.4","from":"3.5"} {"level":"info","ts":1526586949.0922918,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.5"}

endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 492.834µs
localhost:22379 is healthy: successfully committed proposal: took = 1.015025ms
localhost:32379 is healthy: successfully committed proposal: took = 1.853077ms
COMMENT

curl http://localhost:2379/version
<<COMMENT
{"etcdserver":"3.5.0","etcdcluster":"3.5.0"}
COMMENT

curl http://localhost:22379/version
<<COMMENT
{"etcdserver":"3.5.0","etcdcluster":"3.5.0"}
COMMENT

curl http://localhost:32379/version
<<COMMENT
{"etcdserver":"3.5.0","etcdcluster":"3.5.0"}
COMMENT

5 - Mettre à jour etcd de 3.3 à 3.4

Processus, listes de vérification et notes sur la mise à niveau d’etcd de la version 3.3 à la 3.4

Dans le cas général, la mise à niveau d’etcd 3.3 vers 3.4 peut s’effectuer sans interruption de service, par mise à niveau progressive :

un par un, arrêtez les processus etcd v3.3 et remplacez-les par des processus etcd v3.4
après avoir lancé tous les processus v3.4, les nouvelles fonctionnalités de la version v3.4 sont disponibles pour le cluster

Avant de lancer la mise à jour , lisez le reste du présent guide afin de vous préparer.

Listes de vérification pour la mise à jour

Avertissement

Changements de rupture mis en évidence dans la version 3.4.

Rendre `ETCDCTL_API=3 etcdctl` par défaut

ETCDCTL_API=3 est désormais la valeur par défaut.

etcdctl set foo bar
Error: unknown command "set" for "etcdctl"

-etcdctl set foo bar
+ETCDCTL_API=2 etcdctl set foo bar
bar

ETCDCTL_API=3 etcdctl put foo bar
OK

-ETCDCTL_API=3 etcdctl put foo bar
+etcdctl put foo bar

Rendre `etcd --enable-v2=false` par défaut

etcd --enable-v2=false est désormais la valeur par défaut.

Cela signifie qu’à moins que etcd --enable-v2=true ne soit spécifié, le serveur etcd v3.4 n’acceptera pas les requêtes de l’API v2.

Si l’API v2 était utilisée, assurez-vous d’activer l’API v2 dans la version 3.4 :

-etcd
+etcd --enable-v2=true

D’autres API HTTP fonctionneront toujours (par exemple [CLIENT-URL]/metrics, [CLIENT-URL]/health, passerelle gRPC v3).

Dépréciation des drapeaux `etcd --ca-file` et `etcd --peer-ca-file`

Les drapeaux --ca-file et --peer-ca-file sont obsolètes ; ils ont été dépréciés depuis la version v2.1.

Note : la configuration de ce paramètre active automatiquement l’authentification par certificat client, quelle que soit la valeur définie pour --client-cert-auth.

-etcd --ca-file ca-client.crt
+etcd --trusted-ca-file ca-client.crt

-etcd --peer-ca-file ca-peer.crt
+etcd --peer-trusted-ca-file ca-peer.crt

Erreur `grpc.ErrClientConnClosing` obsolète

grpc.ErrClientConnClosing a été déprécié dans gRPC >= 1.10 .

import (
+	"go.etcd.io/etcd/clientv3"

	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
)

_, err := kvc.Get(ctx, "a")
-if err == grpc.ErrClientConnClosing {
+if clientv3.IsConnCanceled(err) {

// or
+s, ok := status.FromError(err)
+if ok {
+  if s.Code() == codes.Canceled

Exiger `grpc.WithBlock` pour la connexion client

Le nouveau répartiteur de charge client utilise un résolveur asynchrone pour transmettre les points de terminaison à la fonction gRPC dial. En conséquence, le client v3.4 exige l’option grpc.WithBlock pour attendre que la connexion sous-jacente soit active.

import (
	"time"
	"go.etcd.io/etcd/clientv3"
+	"google.golang.org/grpc"
)

+// "grpc.WithBlock()" to block until the underlying connection is up
ccfg := clientv3.Config{
  Endpoints:            []string{"localhost:2379"},
  DialTimeout:          time.Second,
+ DialOptions:          []grpc.DialOption{grpc.WithBlock()},
  DialKeepAliveTime:    time.Second,
  DialKeepAliveTimeout: 500 * time.Millisecond,
}

Dépréciation des métriques Prometheus `etcd_debugging_mvcc_db_total_size_in_bytes`

v3.4 promeut les métriques Prometheus etcd_debugging_mvcc_db_total_size_in_bytes vers etcd_mvcc_db_total_size_in_bytes, afin d’encourager la surveillance du stockage etcd.

etcd_debugging_mvcc_db_total_size_in_bytes est toujours fourni dans la version 3.4 pour des raisons de compatibilité descendante. Il sera complètement obsolète dans la version 3.5.

-etcd_debugging_mvcc_db_total_size_in_bytes
+etcd_mvcc_db_total_size_in_bytes

Dépréciation des métriques Prometheus `etcd_debugging_mvcc_put_total`

v3.4 promeut les métriques Prometheus etcd_debugging_mvcc_put_total vers etcd_mvcc_put_total, afin d’encourager la surveillance du stockage etcd.

etcd_debugging_mvcc_put_total est toujours fourni dans la version 3.4 pour des raisons de compatibilité descendante. Il sera complètement obsolète dans la version 3.5.

-etcd_debugging_mvcc_put_total
+etcd_mvcc_put_total

Dépréciation des métriques Prometheus `etcd_debugging_mvcc_delete_total`

v3.4 promeut les métriques Prometheus etcd_debugging_mvcc_delete_total vers etcd_mvcc_delete_total, afin d’encourager la surveillance du stockage etcd.

etcd_debugging_mvcc_delete_total est toujours fourni dans la version 3.4 pour des raisons de compatibilité descendante. Il sera complètement obsolète dans la version 3.5.

-etcd_debugging_mvcc_delete_total
+etcd_mvcc_delete_total

Dépréciation des métriques Prometheus `etcd_debugging_mvcc_txn_total`

v3.4 promeut les métriques Prometheus etcd_debugging_mvcc_txn_total vers etcd_mvcc_txn_total, afin d’encourager la surveillance du stockage etcd.

etcd_debugging_mvcc_txn_total est toujours fourni dans la version 3.4 pour des raisons de compatibilité descendante. Il sera complètement obsolète dans la version 3.5.

-etcd_debugging_mvcc_txn_total
+etcd_mvcc_txn_total

Dépréciation des métriques Prometheus `etcd_debugging_mvcc_range_total`

v3.4 promeut les métriques Prometheus etcd_debugging_mvcc_range_total vers etcd_mvcc_range_total, afin d’encourager la surveillance du stockage etcd.

etcd_debugging_mvcc_range_total est toujours fourni dans la version 3.4 pour des raisons de compatibilité descendante. Il sera complètement obsolète dans la version 3.5.

-etcd_debugging_mvcc_range_total
+etcd_mvcc_range_total

Dépréciation du drapeau `etcd --log-output` (maintenant `--log-outputs`)

Renommez etcd --log-output en --log-outputs pour prendre en charge plusieurs sorties de journalisation. etcd --logger=capnslog ne prend pas en charge plusieurs sorties de journalisation.

etcd --log-output sera obsolète à partir de la version 3.5. etcd --logger=capnslog sera obsolète à partir de la version 3.5.

-etcd --log-output=stderr
+etcd --log-outputs=stderr

+# to write logs to stderr and a.log file at the same time
+# only "--logger=zap" supports multiple writers
+etcd --logger=zap --log-outputs=stderr,a.log

v3.4 ajoute la prise en charge de etcd --logger=zap --log-outputs=stderr pour la journalisation structurée et plusieurs sorties de journal. La motivation principale est de favoriser la surveillance automatisée d’etcd, plutôt que d’analyser les journaux serveur après une panne. Les développements futurs viseront à réduire au minimum la quantité de logs générés par etcd, et à faciliter sa surveillance grâce aux métriques et aux alertes. etcd --logger=capnslog sera déprécié à partir de v3.5.

Changer le type de champ `log-outputs` dans `etcd --config-file` en `[]string`

À présent que log-outputs (ancien nom de champ log-output) accepte plusieurs sorties de journalisation, le champ du fichier YAML de configuration etcd log-outputs doit être modifié en type []string comme indiqué ci-dessous :

 # Specify 'stdout' or 'stderr' to skip journald logging even when running under systemd.
-log-output: default
+log-outputs: [default]

Renommer `embed.Config.LogOutput` en `embed.Config.LogOutputs`

embed.Config.LogOutput a été renommé en embed.Config.LogOutputs afin de prendre en charge plusieurs sorties de journalisation. Le type de embed.Config.LogOutput est également passé de string à []string afin de prendre en charge plusieurs sorties de journalisation.

import "github.com/coreos/etcd/embed"

cfg := &embed.Config{Debug: false}
-cfg.LogOutput = "stderr"
+cfg.LogOutputs = []string{"stderr"}

v3.5 déprécie `capnslog`

v3.5 dépréciera le drapeau etcd --log-package-levels pour capnslog ; etcd --logger=zap --log-outputs=stderr sera la valeur par défaut. v3.5 dépréciera l’endpoint [CLIENT-URL]/config/local/log.

-etcd
+etcd --logger zap

Dépréciation du drapeau `etcd --debug` (maintenant `--log-level=debug`)

La version 3.4 déprécie l’utilisation du drapeau etcd --debug . À la place, utilisez le drapeau etcd --log-level=debug.

-etcd --debug
+etcd --logger zap --log-level debug

Champ `pkg/transport.TLSInfo.CAFile` obsolète

Champ pkg/transport.TLSInfo.CAFile obsolète.

import "github.com/coreos/etcd/pkg/transport"

tlsInfo := transport.TLSInfo{
    CertFile: "/tmp/test-certs/test.pem",
    KeyFile: "/tmp/test-certs/test-key.pem",
-   CAFile: "/tmp/test-certs/trusted-ca.pem",
+   TrustedCAFile: "/tmp/test-certs/trusted-ca.pem",
}
tlsConfig, err := tlsInfo.ClientConfig()
if err != nil {
    panic(err)
}

Modifier `embed.Config.SnapCount` en `embed.Config.SnapshotCount`

Pour rester cohérent avec le nom du drapeau etcd --snapshot-count, le champ embed.Config.SnapCount a été renommé en embed.Config.SnapshotCount :

import "github.com/coreos/etcd/embed"

cfg := embed.NewConfig()
-cfg.SnapCount = 100000
+cfg.SnapshotCount = 100000

Modifier `etcdserver.ServerConfig.SnapCount` en `etcdserver.ServerConfig.SnapshotCount`

Pour rester cohérent avec le nom du drapeau etcd --snapshot-count, le champ etcdserver.ServerConfig.SnapCount a été renommé en etcdserver.ServerConfig.SnapshotCount :

import "github.com/coreos/etcd/etcdserver"

srvcfg := etcdserver.ServerConfig{
-  SnapCount: 100000,
+  SnapshotCount: 100000,

Signature de fonction modifiée dans le package `wal`

Les signatures de fonction de wal ont été modifiées pour prendre en charge le journalisateur structuré.

import "github.com/coreos/etcd/wal"
+import "go.uber.org/zap"

+lg, _ = zap.NewProduction()

-wal.Open(dirpath, snap)
+wal.Open(lg, dirpath, snap)

-wal.OpenForRead(dirpath, snap)
+wal.OpenForRead(lg, dirpath, snap)

-wal.Repair(dirpath)
+wal.Repair(lg, dirpath)

-wal.Create(dirpath, metadata)
+wal.Create(lg, dirpath, metadata)

Modifier le type `IntervalTree` dans le package `pkg/adt`

pkg/adt.IntervalTree est désormais défini comme une interface.

import (
    "fmt"

    "go.etcd.io/etcd/pkg/adt"
)

func main() {
-    ivt := &adt.IntervalTree{}
+    ivt := adt.NewIntervalTree()

Dépréciation de `embed.Config.SetupLogging`

embed.Config.SetupLogging a été supprimé afin d’éviter une configuration incorrecte de la journalisation, et est désormais configuré automatiquement.

import "github.com/coreos/etcd/embed"

cfg := &embed.Config{Debug: false}
-cfg.SetupLogging()

Modifier les points d’entrée HTTP de la passerelle gRPC (remplacé `/v3beta` par `/v3`)

Avant

curl -L http://localhost:2379/v3beta/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'

Après

curl -L http://localhost:2379/v3/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'

Les requêtes vers les points de terminaison /v3beta seront redirigées vers /v3, et /v3beta sera supprimé dans la version 3.5.

Balises d’image conteneur obsolètes

latest et les balises de version mineure sont obsolètes :

-docker pull gcr.io/etcd-development/etcd:latest
+docker pull gcr.io/etcd-development/etcd:v3.4.0

-docker pull gcr.io/etcd-development/etcd:v3.4
+docker pull gcr.io/etcd-development/etcd:v3.4.0

-docker pull gcr.io/etcd-development/etcd:v3.4
+docker pull gcr.io/etcd-development/etcd:v3.4.1

-docker pull gcr.io/etcd-development/etcd:v3.4
+docker pull gcr.io/etcd-development/etcd:v3.4.2

Liste de vérification pour la mise à jour du serveur

Exigences de mise à jour

Pour mettre à jour un déploiement etcd existant vers la version 3.4, le cluster en cours d’exécution doit être la version 3.3 ou ultérieure. Si la version est antérieure à 3.3, veuillez mettre à jour vers la version 3.3 avant de procéder à la mise à jour vers la version 3.4.

Préparation

Avant de mettre à jour etcd, testez toujours les services dépendants d’etcd dans un environnement de préproduction avant de déployer la mise à jour dans l’environnement de production.

Avant de commencer, téléchargez la sauvegarde d’instantané . Si une erreur survient lors de la mise à jour, il sera possible d’utiliser cette sauvegarde pour rétrograder vers la version existante d’etcd. Veuillez noter que la commande snapshot ne sauvegarde que les données v3. Pour les données v2, consultez sauvegarde du magasin de données v2 .

Versions mixtes

Lors d’une mise à jour, 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 n’est considéré comme mis à jour qu’une fois que tous ses membres ont été mis à jour vers la version 3.4. En interne, les membres etcd négocient entre eux afin de déterminer la version globale du cluster, qui contrôle la version signalée et les fonctionnalités prises en charge.

Limitations

Note : Si le cluster ne contient que des données v3 et aucune donnée v2, il n’est pas soumis à cette limitation.

Rétrogradation

Si tous les membres ont été mis à jour vers la version v3.4, le cluster sera mis à jour vers la version v3.4, et un retour en arrière depuis cet état finalisé est impossible. Toutefois, si un seul membre reste en version v3.3, le cluster et ses opérations restent “v3.3”, et il est possible, depuis cet état de cluster mixte, de revenir à l’utilisation d’un binaire etcd v3.3 sur tous les membres.

Veuillez télécharger la sauvegarde d’instantané afin de permettre la rétrogradation du cluster, même après sa mise à jour complète.

Procédure de mise à jour

Cet exemple montre comment mettre à jour un cluster etcd v3.3 composé de 3 membres, en cours d’exécution sur une machine locale.

Étape 1 : vérifier les exigences de mise à jour

Le cluster est-il sain et en cours d’exécution sous la version 3.3.x ?

etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint health
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 2.118638ms
localhost:22379 is healthy: successfully committed proposal: took = 3.631388ms
localhost:32379 is healthy: successfully committed proposal: took = 2.157051ms
COMMENT

curl http://localhost:2379/version
<<COMMENT
{"etcdserver":"3.3.5","etcdcluster":"3.3.0"}
COMMENT

curl http://localhost:22379/version
<<COMMENT
{"etcdserver":"3.3.5","etcdcluster":"3.3.0"}
COMMENT

curl http://localhost:32379/version
<<COMMENT
{"etcdserver":"3.3.5","etcdcluster":"3.3.0"}
COMMENT

Étape 2 : télécharger la sauvegarde d’instantané depuis le leader

Téléchargez l’instantané de sauvegarde afin de disposer d’une voie de retour en cas de problème.

Le leader etcd possède toujours les données d’application les plus récentes ; récupérez donc l’instantané depuis le leader :

curl -sL http://localhost:2379/metrics | grep etcd_server_is_leader
<<COMMENT
# HELP etcd_server_is_leader Whether or not this member is a leader. 1 if is, 0 otherwise.
# TYPE etcd_server_is_leader gauge
etcd_server_is_leader 1
COMMENT

curl -sL http://localhost:22379/metrics | grep etcd_server_is_leader
<<COMMENT
etcd_server_is_leader 0
COMMENT

curl -sL http://localhost:32379/metrics | grep etcd_server_is_leader
<<COMMENT
etcd_server_is_leader 0
COMMENT

etcdctl --endpoints=localhost:2379 snapshot save backup.db
<<COMMENT
{"level":"info","ts":1526585787.148433,"caller":"snapshot/v3_snapshot.go:109","msg":"created temporary db file","path":"backup.db.part"}
{"level":"info","ts":1526585787.1485257,"caller":"snapshot/v3_snapshot.go:120","msg":"fetching snapshot","endpoint":"localhost:2379"}
{"level":"info","ts":1526585787.1519694,"caller":"snapshot/v3_snapshot.go:133","msg":"fetched snapshot","endpoint":"localhost:2379","took":0.003502721}
{"level":"info","ts":1526585787.1520295,"caller":"snapshot/v3_snapshot.go:142","msg":"saved","path":"backup.db"}
Snapshot saved at backup.db
COMMENT

Étape 3 : arrêter un serveur etcd existant

10.237579 I | etcdserver: updating the cluster version from 3.0 to 3.3
10.238315 N | etcdserver/membership: updated the cluster version from 3.0 to 3.3
10.238451 I | etcdserver/api: enabled capabilities for version 3.3


^C21.192174 N | pkg/osutil: received interrupt signal, shutting down...
21.192459 I | etcdserver: 7339c4e5e833c029 starts leadership transfer from 7339c4e5e833c029 to 729934363faa4a24
21.192569 I | raft: 7339c4e5e833c029 [term 8] starts to transfer leadership to 729934363faa4a24
21.192619 I | raft: 7339c4e5e833c029 sends MsgTimeoutNow to 729934363faa4a24 immediately as 729934363faa4a24 already has up-to-date log
WARNING: 2018/05/17 12:45:21 grpc: addrConn.resetTransport failed to create client transport: connection error: desc = "transport: Error while dialing dial tcp: operation was canceled"; Reconnecting to {localhost:2379 0  <nil>}
WARNING: 2018/05/17 12:45:21 grpc: addrConn.transportMonitor exits due to: grpc: the connection is closing
21.193589 I | raft: 7339c4e5e833c029 [term: 8] received a MsgVote message with higher term from 729934363faa4a24 [term: 9]
21.193626 I | raft: 7339c4e5e833c029 became follower at term 9
21.193651 I | raft: 7339c4e5e833c029 [logterm: 8, index: 9, vote: 0] cast MsgVote for 729934363faa4a24 [logterm: 8, index: 9] at term 9
21.193675 I | raft: raft.node: 7339c4e5e833c029 lost leader 7339c4e5e833c029 at term 9
21.194424 I | raft: raft.node: 7339c4e5e833c029 elected leader 729934363faa4a24 at term 9
21.292898 I | etcdserver: 7339c4e5e833c029 finished leadership transfer from 7339c4e5e833c029 to 729934363faa4a24 (took 100.436391ms)
21.292975 I | rafthttp: stopping peer 729934363faa4a24...
21.293206 I | rafthttp: closed the TCP streaming connection with peer 729934363faa4a24 (stream MsgApp v2 writer)
21.293225 I | rafthttp: stopped streaming with peer 729934363faa4a24 (writer)
21.293437 I | rafthttp: closed the TCP streaming connection with peer 729934363faa4a24 (stream Message writer)
21.293459 I | rafthttp: stopped streaming with peer 729934363faa4a24 (writer)
21.293514 I | rafthttp: stopped HTTP pipelining with peer 729934363faa4a24
21.293590 W | rafthttp: lost the TCP streaming connection with peer 729934363faa4a24 (stream MsgApp v2 reader)
21.293610 I | rafthttp: stopped streaming with peer 729934363faa4a24 (stream MsgApp v2 reader)
21.293680 W | rafthttp: lost the TCP streaming connection with peer 729934363faa4a24 (stream Message reader)
21.293700 I | rafthttp: stopped streaming with peer 729934363faa4a24 (stream Message reader)
21.293711 I | rafthttp: stopped peer 729934363faa4a24
21.293720 I | rafthttp: stopping peer b548c2511513015...
21.293987 I | rafthttp: closed the TCP streaming connection with peer b548c2511513015 (stream MsgApp v2 writer)
21.294063 I | rafthttp: stopped streaming with peer b548c2511513015 (writer)
21.294467 I | rafthttp: closed the TCP streaming connection with peer b548c2511513015 (stream Message writer)
21.294561 I | rafthttp: stopped streaming with peer b548c2511513015 (writer)
21.294742 I | rafthttp: stopped HTTP pipelining with peer b548c2511513015
21.294867 W | rafthttp: lost the TCP streaming connection with peer b548c2511513015 (stream MsgApp v2 reader)
21.294892 I | rafthttp: stopped streaming with peer b548c2511513015 (stream MsgApp v2 reader)
21.294990 W | rafthttp: lost the TCP streaming connection with peer b548c2511513015 (stream Message reader)
21.295004 E | rafthttp: failed to read b548c2511513015 on stream Message (context canceled)
21.295013 I | rafthttp: peer b548c2511513015 became inactive
21.295024 I | rafthttp: stopped streaming with peer b548c2511513015 (stream Message reader)
21.295035 I | rafthttp: stopped peer b548c2511513015

Étape 4 : redémarrer le serveur etcd avec la même configuration

Redémarrez le serveur etcd avec la même configuration, mais avec le binaire etcd mis à jour.

-etcd-old --name s1 \
+etcd-new --name s1 \
  --data-dir /tmp/etcd/s1 \
  --listen-client-urls http://localhost:2379 \
  --advertise-client-urls http://localhost:2379 \
  --listen-peer-urls http://localhost:2380 \
  --initial-advertise-peer-urls http://localhost:2380 \
  --initial-cluster s1=http://localhost:2380,s2=http://localhost:22380,s3=http://localhost:32380 \
  --initial-cluster-token tkn \
+ --initial-cluster-state new \
+ --logger zap \
+ --log-outputs stderr

Le nouvel etcd v3.4 publiera ses informations dans le cluster. À ce stade, le cluster continue de fonctionner selon le protocole v3.3, qui constitue la version la plus basse commune.

{"level":"info","ts":1526586617.1647713,"caller":"membership/cluster.go:485","msg":"set initial cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"7339c4e5e833c029","cluster-version":"3.0"}

{"level":"info","ts":1526586617.1648536,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.0"}

{"level":"info","ts":1526586617.1649303,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"7339c4e5e833c029","from":"3.0","from":"3.3"}

{"level":"info","ts":1526586617.1649797,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.3"}

{"level":"info","ts":1526586617.2107732,"caller":"etcdserver/server.go:1770","msg":"published local member to cluster through raft","local-member-id":"7339c4e5e833c029","local-member-attributes":"{Name:s1 ClientURLs:[http://localhost:2379]}","request-path":"/0/members/7339c4e5e833c029/attributes","cluster-id":"7dee9ba76d59ed53","publish-timeout":7}

Vérifiez que chaque membre, puis l’ensemble du cluster, devient sain avec le binaire etcd v3.4 nouvellement installé :

etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
<<COMMENT
localhost:32379 is healthy: successfully committed proposal: took = 2.337471ms
localhost:22379 is healthy: successfully committed proposal: took = 1.130717ms
localhost:2379 is healthy: successfully committed proposal: took = 2.124843ms
COMMENT

Les membres non mis à jour afficheront des avertissements tels que les suivants jusqu’à ce que tout le cluster soit mis à jour.

Cela est attendu et cessera une fois que tous les membres du cluster etcd auront été mis à jour vers la version 3.4 :

:41.942121 W | etcdserver: member 7339c4e5e833c029 has a higher version 3.4.0
:45.945154 W | etcdserver: the local etcd version 3.3.5 is not up-to-date

Étape 5 : répéter l’étape 3 et l’étape 4 pour les membres restants

Lorsque tous les membres sont mis à jour, le cluster signalera avec succès la mise à jour vers la version 3.4 :

Membre 1 :

{"level":"info","ts":1526586949.0920913,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.4"} {"level":"info","ts":1526586949.0921566,"caller":"etcdserver/server.go:2272","msg":"cluster version is updated","cluster-version":"3.4"}

Membre 2 :

{"level":"info","ts":1526586949.092117,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"729934363faa4a24","from":"3.3","from":"3.4"} {"level":"info","ts":1526586949.0923078,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.4"}

Membre 3 :

{"level":"info","ts":1526586949.0921423,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"b548c2511513015","from":"3.3","from":"3.4"} {"level":"info","ts":1526586949.0922918,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.4"}

endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
<<COMMENT
localhost:2379 is healthy: successfully committed proposal: took = 492.834µs
localhost:22379 is healthy: successfully committed proposal: took = 1.015025ms
localhost:32379 is healthy: successfully committed proposal: took = 1.853077ms
COMMENT

curl http://localhost:2379/version
<<COMMENT
{"etcdserver":"3.4.0","etcdcluster":"3.4.0"}
COMMENT

curl http://localhost:22379/version
<<COMMENT
{"etcdserver":"3.4.0","etcdcluster":"3.4.0"}
COMMENT

curl http://localhost:32379/version
<<COMMENT
{"etcdserver":"3.4.0","etcdcluster":"3.4.0"}
COMMENT

6 - Mettre à jour etcd de 3.2 vers 3.3

Processus, listes de vérification et notes sur la mise à jour d’etcd de la version 3.2 à la 3.3

Dans le cas général, la mise à niveau d’etcd 3.2 vers 3.3 peut être effectuée sans interruption de service, par mise à niveau progressive :

un par un, arrêtez les processus etcd v3.2 et remplacez-les par des processus etcd v3.3
après avoir lancé tous les processus v3.3, les nouvelles fonctionnalités de la version v3.3 sont disponibles pour le cluster

Avant de lancer la mise à jour , lisez le reste du présent guide afin de vous préparer.

Listes de vérification pour la mise à jour

Avertissement

si vous activez l’authentification et utilisez des baux (avec une durée de vie courte), il y a de fortes chances de rencontrer un problème entraînant une incohérence des données. Il est fortement recommandé de mettre à jour vers 3.2.31 ou ultérieur avant toute mise à jour vers 3.3, afin de corriger ce problème. En outre, si un utilisateur sans autorisation envoie une requête LeaseRevoke à un nœud 3.3 pendant la mise à jour, cela peut encore provoquer une corruption des données. Le mieux est donc de s’assurer que votre environnement ne contient pas d’appels anormaux avant la mise à jour ; consultez #11691 pour plus de détails.

Changements de rupture mis en évidence dans 3.3.

Changement du type de valeur du drapeau `etcd --auto-compaction-retention` en `string`

Le drapeau --auto-compaction-retention a été modifié pour accepter des valeurs de type chaîne avec une granularité plus fine . À présent que --auto-compaction-retention accepte des valeurs de type chaîne, le champ du fichier YAML de configuration etcd auto-compaction-retention doit être de type string. Auparavant, --config-file etcd.config.yaml pouvait inclure le champ auto-compaction-retention: 24, désormais il doit être auto-compaction-retention: "24" ou auto-compaction-retention: "24h". Si configuré comme --auto-compaction-mode periodic --auto-compaction-retention "24h", la valeur de durée pour le drapeau --auto-compaction-retention doit être valide pour la fonction time.ParseDuration en Go.

# etcd.config.yaml
+auto-compaction-mode: periodic
-auto-compaction-retention: 24
+auto-compaction-retention: "24"
+# Or
+auto-compaction-retention: "24h"

Modifier `*etcdserver.ServerConfig` en `etcdserver.ServerConfig`

etcdserver.EtcdServer a modifié le type de son champ membre *etcdserver.ServerConfig en etcdserver.ServerConfig. Et etcdserver.NewServer prend désormais etcdserver.ServerConfig, plutôt que *etcdserver.ServerConfig.

Avant et après (par exemple k8s.io/kubernetes/test/e2e_node/services/etcd.go )

import "github.com/coreos/etcd/etcdserver"

type EtcdServer struct {
	*etcdserver.EtcdServer
-	config *etcdserver.ServerConfig
+	config etcdserver.ServerConfig
}

func NewEtcd(dataDir string) *EtcdServer {
-	config := &etcdserver.ServerConfig{
+	config := etcdserver.ServerConfig{
		DataDir: dataDir,
        ...
	}
	return &EtcdServer{config: config}
}

func (e *EtcdServer) Start() error {
	var err error
	e.EtcdServer, err = etcdserver.NewServer(e.config)
    ...

Ajout du champ `embed.Config.LogOutput`

Avertissement

Notez que ce champ a été renommé en embed.Config.LogOutputs et est de type []string à partir de la version 3.4. Consultez le guide de mise à jour vers la version 3.4 pour plus de détails.

Le champ LogOutput est ajouté à embed.Config :

package embed

type Config struct {
 	Debug bool `json:"debug"`
 	LogPkgLevels string `json:"log-package-levels"`
+	LogOutput string `json:"log-output"`
 	...

Auparavant, les avertissements du serveur gRPC étaient journalisés dans etcdserver.

WARNING: 2017/11/02 11:35:51 grpc: addrConn.resetTransport failed to create client transport: connection error: desc = "transport: Error while dialing dial tcp: operation was canceled"; Reconnecting to {localhost:2379 <nil>}
WARNING: 2017/11/02 11:35:51 grpc: addrConn.resetTransport failed to create client transport: connection error: desc = "transport: Error while dialing dial tcp: operation was canceled"; Reconnecting to {localhost:2379 <nil>}

À compter de la version 3.3, les journaux du serveur gRPC sont désactivés par défaut.

Avertissement

Notez que la méthode embed.Config.SetupLogging a été dépréciée à partir de la version v3.4. Consultez le guide de mise à jour vers la version v3.4 pour plus de détails.

import "github.com/coreos/etcd/embed"

cfg := &embed.Config{Debug: false}
cfg.SetupLogging()

Définissez le champ embed.Config.Debug sur true pour activer les journaux du serveur gRPC.

Modifier la réponse de l’endpoint `/health`

Précédemment, [endpoint]:[client-port]/health renvoyait une valeur JSON marshalisée manuellement. La version 3.3 définit désormais la structure etcdhttp.Health .

Notez que dans les versions v3.3.0-rc.0, v3.3.0-rc.1 et v3.3.0-rc.2, etcdhttp.Health possède des champs "health" et "errors" de type booléen. Afin de garantir la compatibilité descendante, nous avons rétabli le champ "health" vers le type string et supprimé le champ "errors". Les informations de santé supplémentaires seront fournies via des API séparées.

$ curl http://localhost:2379/health
{"health":"true"}

Modifier les points d’entrée HTTP de la passerelle gRPC (remplacé `/v3alpha` par `/v3beta`)

Avant

curl -L http://localhost:2379/v3alpha/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'

Après

curl -L http://localhost:2379/v3beta/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'

Les requêtes vers les points de terminaison /v3alpha seront redirigées vers /v3beta, et /v3alpha sera supprimé dans la version 3.4.

Modifier les limites de taille maximale des requêtes

3.3 permet désormais des limites de taille de requête personnalisées pour le serveur et le côté client. Dans les versions précédentes (v3.2.10, v3.2.11), la taille de réponse du client était limitée à 4 MiB.

Les limites de requêtes côté serveur peuvent être configurées à l’aide du drapeau --max-request-bytes :

# limits request size to 1.5 KiB
etcd --max-request-bytes 1536

# client writes exceeding 1.5 KiB will be rejected
etcdctl put foo [LARGE VALUE...]
# etcdserver: request is too large

Ou configurez le champ embed.Config.MaxRequestBytes :

import "github.com/coreos/etcd/embed"
import "github.com/coreos/etcd/etcdserver/api/v3rpc/rpctypes"

// limit requests to 5 MiB
cfg := embed.NewConfig()
cfg.MaxRequestBytes = 5 * 1024 * 1024

// client writes exceeding 5 MiB will be rejected
_, err := cli.Put(ctx, "foo", [LARGE VALUE...])
err == rpctypes.ErrRequestTooLarge

Si non spécifié, la limite côté serveur est par défaut de 1,5 MiB.

Les limites de requêtes côté client doivent être configurées en fonction des limites côté serveur.

# limits request size to 1 MiB
etcd --max-request-bytes 1048576

import "github.com/coreos/etcd/clientv3"

cli, _ := clientv3.New(clientv3.Config{
    Endpoints: []string{"127.0.0.1:2379"},
    MaxCallSendMsgSize: 2 * 1024 * 1024,
    MaxCallRecvMsgSize: 3 * 1024 * 1024,
})


// client writes exceeding "--max-request-bytes" will be rejected from etcd server
_, err := cli.Put(ctx, "foo", strings.Repeat("a", 1*1024*1024+5))
err == rpctypes.ErrRequestTooLarge


// client writes exceeding "MaxCallSendMsgSize" will be rejected from client-side
_, err = cli.Put(ctx, "foo", strings.Repeat("a", 5*1024*1024))
err.Error() == "rpc error: code = ResourceExhausted desc = grpc: trying to send message larger than max (5242890 vs. 2097152)"


// some writes under limits
for i := range []int{0,1,2,3,4} {
    _, err = cli.Put(ctx, fmt.Sprintf("foo%d", i), strings.Repeat("a", 1*1024*1024-500))
    if err != nil {
        panic(err)
    }
}
// client reads exceeding "MaxCallRecvMsgSize" will be rejected from client-side
_, err = cli.Get(ctx, "foo", clientv3.WithPrefix())
err.Error() == "rpc error: code = ResourceExhausted desc = grpc: received message larger than max (5240509 vs. 3145728)"

Si non spécifié, la limite d’envoi côté client est par défaut fixée à 2 MiB (1,5 MiB + surcharge gRPC) et la limite de réception à math.MaxInt32. Voir clientv3 godoc pour plus de détails.

Modifier les signatures des fonctions d’enveloppe du client gRPC brut

3.3 modifie les signatures de fonction du wrapper client gRPC clientv3. Ce changement était nécessaire pour prendre en charge les options personnalisées grpc.CallOption sur les limites de taille de message .

Avant et après

-func NewKVFromKVClient(remote pb.KVClient) KV {
+func NewKVFromKVClient(remote pb.KVClient, c *Client) KV {

-func NewClusterFromClusterClient(remote pb.ClusterClient) Cluster {
+func NewClusterFromClusterClient(remote pb.ClusterClient, c *Client) Cluster {

-func NewLeaseFromLeaseClient(remote pb.LeaseClient, keepAliveTimeout time.Duration) Lease {
+func NewLeaseFromLeaseClient(remote pb.LeaseClient, c *Client, keepAliveTimeout time.Duration) Lease {

-func NewMaintenanceFromMaintenanceClient(remote pb.MaintenanceClient) Maintenance {
+func NewMaintenanceFromMaintenanceClient(remote pb.MaintenanceClient, c *Client) Maintenance {

-func NewWatchFromWatchClient(wc pb.WatchClient) Watcher {
+func NewWatchFromWatchClient(wc pb.WatchClient, c *Client) Watcher {

Changer le type d’erreur de l’API clientv3 `Snapshot`

Précédemment, l’API clientv3 Snapshot renvoyait des erreurs de type [grpc/*status.statusError] brutes. La version 3.3 les traduit désormais en types d’erreurs publiques correspondants, afin de maintenir une cohérence avec les autres API.

Avant

import "context"

// reading snapshot with canceled context should error out
ctx, cancel := context.WithCancel(context.Background())
rc, _ := cli.Snapshot(ctx)
cancel()
_, err := io.Copy(f, rc)
err.Error() == "rpc error: code = Canceled desc = context canceled"

// reading snapshot with deadline exceeded should error out
ctx, cancel = context.WithTimeout(context.Background(), time.Second)
defer cancel()
rc, _ = cli.Snapshot(ctx)
time.Sleep(2 * time.Second)
_, err = io.Copy(f, rc)
err.Error() == "rpc error: code = DeadlineExceeded desc = context deadline exceeded"

Après

import "context"

// reading snapshot with canceled context should error out
ctx, cancel := context.WithCancel(context.Background())
rc, _ := cli.Snapshot(ctx)
cancel()
_, err := io.Copy(f, rc)
err == context.Canceled

// reading snapshot with deadline exceeded should error out
ctx, cancel = context.WithTimeout(context.Background(), time.Second)
defer cancel()
rc, _ = cli.Snapshot(ctx)
time.Sleep(2 * time.Second)
_, err = io.Copy(f, rc)
err == context.DeadlineExceeded

Changer la sortie de la commande `etcdctl lease timetolive`

Précédemment, la commande lease timetolive LEASE_ID sur un bail expiré affichait -1s pour le nombre de secondes restantes. La version 3.3 affiche désormais des messages plus clairs.

Avant

lease 2d8257079fa1bc0c granted with TTL(0s), remaining(-1s)

Après

lease 2d8257079fa1bc0c already expired

Modifier les imports `golang.org/x/net/context`

clientv3 a déprécié golang.org/x/net/context. Si un projet inclut golang.org/x/net/context dans son répertoire vendor pour d’autres parties du code (par exemple, du code généré par etcd pour les protocoles buffer) et importe github.com/coreos/etcd/clientv3, une version de Go 1.9 ou ultérieure est requise pour la compilation.

Avant

import "golang.org/x/net/context"
cli.Put(context.Background(), "f", "v")

Après

import "context"
cli.Put(context.Background(), "f", "v")

Modifier la dépendance gRPC

3.3 exige désormais grpc/grpc-go v1.7.5.

Dépréciation de `grpclog.Logger`

grpclog.Logger a été déprécié en faveur de grpclog.LoggerV2 . clientv3.Logger est désormais grpclog.LoggerV2.

Avant

import "github.com/coreos/etcd/clientv3"
clientv3.SetLogger(log.New(os.Stderr, "grpc: ", 0))

Après

import "github.com/coreos/etcd/clientv3"
import "google.golang.org/grpc/grpclog"
clientv3.SetLogger(grpclog.NewLoggerV2(os.Stderr, os.Stderr, os.Stderr))

// log.New above cannot be used (not implement grpclog.LoggerV2 interface)

Dépréciation de `grpc.ErrClientConnTimeout`

Précédemment, l’erreur grpc.ErrClientConnTimeout était renvoyée en cas de délai d’attente lors de la connexion client. La version 3.3 renvoie désormais context.DeadlineExceeded (voir #8504 ).

Avant

// expect dial time-out on ipv4 blackhole
_, err := clientv3.New(clientv3.Config{
    Endpoints:   []string{"http://254.0.0.1:12345"},
    DialTimeout: 2 * time.Second
})
if err == grpc.ErrClientConnTimeout {
	// handle errors
}

Après

_, err := clientv3.New(clientv3.Config{
    Endpoints:   []string{"http://254.0.0.1:12345"},
    DialTimeout: 2 * time.Second
})
if err == context.DeadlineExceeded {
	// handle errors
}

Changement du registre conteneur officiel

etcd utilise désormais gcr.io/etcd-development/etcd comme registre conteneur principal, et quay.io/coreos/etcd comme secondaire.

Avant

docker pull quay.io/coreos/etcd:v3.2.5

Après

docker pull gcr.io/etcd-development/etcd:v3.3.0

Mises à jour vers v3.3.14 ou une version ultérieure

v3.3.14 a dû intégrer certaines fonctionnalités de la version 3.4, tout en cherchant à minimiser les différences entre les implémentations du répartiteur de charge client. Cette version corrige “kube-apiserver 1.13.x refuse de fonctionner lorsque le premier serveur etcd n’est pas disponible” (kubernetes#72102) .

grpc.ErrClientConnClosing a été déprécié dans gRPC >= 1.10 .

import (
+	"go.etcd.io/etcd/clientv3"

	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
)

_, err := kvc.Get(ctx, "a")
-if err == grpc.ErrClientConnClosing {
+if clientv3.IsConnCanceled(err) {

// or
+s, ok := status.FromError(err)
+if ok {
+  if s.Code() == codes.Canceled

Le nouveau répartiteur de charge client utilise un résolveur asynchrone pour transmettre les points de terminaison à la fonction de connexion gRPC. En conséquence, v3.3.14 ou une version ultérieure nécessite l’option grpc.WithBlock pour attendre que la connexion sous-jacente soit active.

import (
	"time"
	"go.etcd.io/etcd/clientv3"
+	"google.golang.org/grpc"
)

+// "grpc.WithBlock()" to block until the underlying connection is up
ccfg := clientv3.Config{
  Endpoints:            []string{"localhost:2379"},
  DialTimeout:          time.Second,
+ DialOptions:          []grpc.DialOption{grpc.WithBlock()},
  DialKeepAliveTime:    time.Second,
  DialKeepAliveTimeout: 500 * time.Millisecond,
}

Veuillez consulter CHANGELOG pour obtenir la liste complète des modifications.

Liste de vérification pour la mise à jour du serveur

Exigences de mise à jour

Pour mettre à jour un déploiement etcd existant vers la version 3.3, le cluster en cours d’exécution doit être la version 3.2 ou ultérieure. Si la version est antérieure à 3.2, veuillez mettre à jour vers la version 3.2 avant de procéder à la mise à jour vers la version 3.3.

Préparation

Avant de mettre à jour etcd, testez toujours les services dépendants d’etcd dans un environnement de préproduction avant de déployer la mise à jour dans l’environnement de production.

Avant de commencer, sauvegardez les données etcd . Si une erreur survient lors de la mise à jour, il sera possible d’utiliser cette sauvegarde pour rétrograder vers la version existante d’etcd. Veuillez noter que la commande snapshot ne sauvegarde que les données v3. Pour les données v2, consultez sauvegarde du magasin de données v2 .

Versions mixtes

Lors d’une mise à jour, 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 uniquement lorsque tous ses membres ont été mis à jour vers la version 3.3. En interne, les membres etcd négocient entre eux afin de déterminer la version globale du cluster, qui contrôle la version signalée et les fonctionnalités prises en charge.

Limitations

Note : Si le cluster ne contient que des données v3 et aucune donnée v2, il n’est pas soumis à cette limitation.

Rétrogradation

Si tous les membres ont été mis à jour vers la version v3.3, le cluster sera mis à jour vers la v3.3, et un retour en arrière depuis cet état finalisé est impossible. Si toutefois un seul membre reste en version v3.2, le cluster et ses opérations restent “v3.2”, et il est possible, depuis cet état de cluster mixte, de revenir à l’utilisation d’un binaire etcd v3.2 sur tous les membres.

Veuillez sauvegarder le répertoire de données de tous les membres etcd afin de permettre la rétrogradation du cluster, même après sa mise à jour complète.

Procédure de mise à jour

Cet exemple montre comment mettre à jour un cluster etcd v3.2 composé de 3 membres, en cours d’exécution sur une machine locale.

1. Vérifier les prérequis de mise à jour

Le cluster est-il sain et en cours d’exécution sous la version 3.2.x ?

$ ETCDCTL_API=3 etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:2379 is healthy: successfully committed proposal: took = 6.600684ms
localhost:22379 is healthy: successfully committed proposal: took = 8.540064ms
localhost:32379 is healthy: successfully committed proposal: took = 8.763432ms

$ curl http://localhost:2379/version
{"etcdserver":"3.2.7","etcdcluster":"3.2.0"}

2. Arrêtez le processus etcd existant

14:13:31.491746 I | raft: c89feb932daef420 [term 3] received MsgTimeoutNow from 6d4f535bae3ab960 and starts an election to get leadership.
14:13:31.491769 I | raft: c89feb932daef420 became candidate at term 4
14:13:31.491788 I | raft: c89feb932daef420 received MsgVoteResp from c89feb932daef420 at term 4
14:13:31.491797 I | raft: c89feb932daef420 [logterm: 3, index: 9] sent MsgVote request to 6d4f535bae3ab960 at term 4
14:13:31.491805 I | raft: c89feb932daef420 [logterm: 3, index: 9] sent MsgVote request to 9eda174c7df8a033 at term 4
14:13:31.491815 I | raft: raft.node: c89feb932daef420 lost leader 6d4f535bae3ab960 at term 4
14:13:31.524084 I | raft: c89feb932daef420 received MsgVoteResp from 6d4f535bae3ab960 at term 4
14:13:31.524108 I | raft: c89feb932daef420 [quorum:2] has received 2 MsgVoteResp votes and 0 vote rejections
14:13:31.524123 I | raft: c89feb932daef420 became leader at term 4
14:13:31.524136 I | raft: raft.node: c89feb932daef420 elected leader c89feb932daef420 at term 4
14:13:31.592650 W | rafthttp: lost the TCP streaming connection with peer 6d4f535bae3ab960 (stream MsgApp v2 reader)
14:13:31.592825 W | rafthttp: lost the TCP streaming connection with peer 6d4f535bae3ab960 (stream Message reader)
14:13:31.693275 E | rafthttp: failed to dial 6d4f535bae3ab960 on stream Message (dial tcp [::1]:2380: getsockopt: connection refused)
14:13:31.693289 I | rafthttp: peer 6d4f535bae3ab960 became inactive
14:13:31.936678 W | rafthttp: lost the TCP streaming connection with peer 6d4f535bae3ab960 (stream Message writer)

Il est recommandé de procéder à une sauvegarde des données etcd à cette étape afin de disposer d’un chemin de retour en cas de problème :

$ etcdctl snapshot save backup.db

3. Remplacer le binaire par etcd v3.3 et démarrer le nouveau processus etcd

Le nouvel etcd v3.3 publiera ses informations dans le cluster :

14:14:25.363225 I | etcdserver: published {Name:s1 ClientURLs:[http://localhost:2379]} to cluster a9ededbffcb1b1f1

Vérifiez que chaque membre, puis l’ensemble du cluster, devient sain avec le nouveau binaire etcd v3.3 :

$ ETCDCTL_API=3 /etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:22379 is healthy: successfully committed proposal: took = 5.540129ms
localhost:32379 is healthy: successfully committed proposal: took = 7.321771ms
localhost:2379 is healthy: successfully committed proposal: took = 10.629901ms

Les membres mis à jour émettront des avertissements similaires au suivant jusqu’à ce que l’intégralité du cluster soit mise à jour. C’est normal et cessera une fois que tous les membres du cluster etcd auront été mis à jour vers la version 3.3 :

14:15:17.071804 W | etcdserver: member c89feb932daef420 has a higher version 3.3.0
14:15:21.073110 W | etcdserver: the local etcd version 3.2.7 is not up-to-date
14:15:21.073142 W | etcdserver: member 6d4f535bae3ab960 has a higher version 3.3.0
14:15:21.073157 W | etcdserver: the local etcd version 3.2.7 is not up-to-date
14:15:21.073164 W | etcdserver: member c89feb932daef420 has a higher version 3.3.0

4. Répétez l’étape 2 à l’étape 3 pour tous les autres membres

5. Terminer

Lorsque tous les membres sont mis à jour, le cluster signalera avec succès la mise à jour vers la version 3.3 :

14:15:54.536901 N | etcdserver/membership: updated the cluster version from 3.2 to 3.3
14:15:54.537035 I | etcdserver/api: enabled capabilities for version 3.3

$ ETCDCTL_API=3 /etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:2379 is healthy: successfully committed proposal: took = 2.312897ms
localhost:22379 is healthy: successfully committed proposal: took = 2.553476ms
localhost:32379 is healthy: successfully committed proposal: took = 2.517902ms

7 - Mettre à jour etcd de 3.1 vers 3.2

Processus, listes de vérification et notes sur la mise à jour d’etcd de la version 3.1 à la 3.2

Dans le cas général, la mise à niveau d’etcd 3.1 vers 3.2 peut être effectuée sans interruption de service, par mise à niveau progressive :

un par un, arrêtez les processus etcd v3.1 et remplacez-les par des processus etcd v3.2
après avoir lancé tous les processus v3.2, les nouvelles fonctionnalités de la version v3.2 sont disponibles pour le cluster

Avant de lancer la mise à jour , lisez le reste du présent guide afin de vous préparer.

Listes de vérification pour la mise à jour

Avertissement

Changements de rupture mis en évidence dans 3.2.

Changer la valeur par défaut de `snapshot-count`

Une valeur plus élevée de --snapshot-count conserve davantage d’entrées Raft en mémoire jusqu’à l’instantané, entraînant ainsi une utilisation mémoire plus élevée et récurrente . Comme le leader conserve les dernières entrées Raft plus longtemps, un suiveur lent dispose de plus de temps pour se synchroniser avant que le leader ne prenne un instantané. --snapshot-count représente un compromis entre une utilisation mémoire plus élevée et une meilleure disponibilité des suiveurs lents.

Depuis la version 3.2, la valeur par défaut de --snapshot-count est passée de 10 000 à 100 000 .

Changement de dépendance gRPC (>=3.2.10)

3.2.10 ou ultérieure exige désormais grpc/grpc-go v1.7.5 (les versions 3.2.9 et antérieures exigent v1.2.1).

Dépréciation de `grpclog.Logger`

grpclog.Logger a été déprécié en faveur de grpclog.LoggerV2 . clientv3.Logger est désormais grpclog.LoggerV2.

Avant

import "github.com/coreos/etcd/clientv3"
clientv3.SetLogger(log.New(os.Stderr, "grpc: ", 0))

Après

import "github.com/coreos/etcd/clientv3"
import "google.golang.org/grpc/grpclog"
clientv3.SetLogger(grpclog.NewLoggerV2(os.Stderr, os.Stderr, os.Stderr))

// log.New above cannot be used (not implement grpclog.LoggerV2 interface)

Dépréciation de `grpc.ErrClientConnTimeout`

Précédemment, l’erreur grpc.ErrClientConnTimeout était renvoyée en cas de délai d’attente lors de la connexion client. La version 3.2 renvoie désormais context.DeadlineExceeded (voir #8504 ).

Avant

// expect dial time-out on ipv4 blackhole
_, err := clientv3.New(clientv3.Config{
    Endpoints:   []string{"http://254.0.0.1:12345"},
    DialTimeout: 2 * time.Second
})
if err == grpc.ErrClientConnTimeout {
	// handle errors
}

Après

_, err := clientv3.New(clientv3.Config{
    Endpoints:   []string{"http://254.0.0.1:12345"},
    DialTimeout: 2 * time.Second
})
if err == context.DeadlineExceeded {
	// handle errors
}

Modifier les limites de taille de requête maximale (>=3.2.10)

3.2.10 et 3.2.11 permettent de définir des limites personnalisées de taille de requête côté serveur. À partir de la version 3.2.12, il est possible de définir des limites personnalisées de taille de requête côté serveur et côté client. Dans les versions antérieures (v3.2.10, v3.2.11), la taille des réponses côté client était limitée à 4 MiB.

Les limites de requêtes côté serveur peuvent être configurées à l’aide du drapeau --max-request-bytes :

# limits request size to 1.5 KiB
etcd --max-request-bytes 1536

# client writes exceeding 1.5 KiB will be rejected
etcdctl put foo [LARGE VALUE...]
# etcdserver: request is too large

Ou configurez le champ embed.Config.MaxRequestBytes :

import "github.com/coreos/etcd/embed"
import "github.com/coreos/etcd/etcdserver/api/v3rpc/rpctypes"

// limit requests to 5 MiB
cfg := embed.NewConfig()
cfg.MaxRequestBytes = 5 * 1024 * 1024

// client writes exceeding 5 MiB will be rejected
_, err := cli.Put(ctx, "foo", [LARGE VALUE...])
err == rpctypes.ErrRequestTooLarge

Si non spécifié, la limite côté serveur est par défaut de 1,5 MiB.

Les limites de requêtes côté client doivent être configurées en fonction des limites côté serveur.

# limits request size to 1 MiB
etcd --max-request-bytes 1048576

import "github.com/coreos/etcd/clientv3"

cli, _ := clientv3.New(clientv3.Config{
    Endpoints: []string{"127.0.0.1:2379"},
    MaxCallSendMsgSize: 2 * 1024 * 1024,
    MaxCallRecvMsgSize: 3 * 1024 * 1024,
})


// client writes exceeding "--max-request-bytes" will be rejected from etcd server
_, err := cli.Put(ctx, "foo", strings.Repeat("a", 1*1024*1024+5))
err == rpctypes.ErrRequestTooLarge


// client writes exceeding "MaxCallSendMsgSize" will be rejected from client-side
_, err = cli.Put(ctx, "foo", strings.Repeat("a", 5*1024*1024))
err.Error() == "rpc error: code = ResourceExhausted desc = grpc: trying to send message larger than max (5242890 vs. 2097152)"


// some writes under limits
for i := range []int{0,1,2,3,4} {
    _, err = cli.Put(ctx, fmt.Sprintf("foo%d", i), strings.Repeat("a", 1*1024*1024-500))
    if err != nil {
        panic(err)
    }
}
// client reads exceeding "MaxCallRecvMsgSize" will be rejected from client-side
_, err = cli.Get(ctx, "foo", clientv3.WithPrefix())
err.Error() == "rpc error: code = ResourceExhausted desc = grpc: received message larger than max (5240509 vs. 3145728)"

Modifier les enveloppes client gRPC brutes

3.2.12 ou versions ultérieures modifient les signatures de fonction du wrapper client gRPC clientv3. Ce changement était nécessaire pour prendre en charge les options grpc.CallOption sur les limites de taille des messages .

Avant et après

-func NewKVFromKVClient(remote pb.KVClient) KV {
+func NewKVFromKVClient(remote pb.KVClient, c *Client) KV {

-func NewClusterFromClusterClient(remote pb.ClusterClient) Cluster {
+func NewClusterFromClusterClient(remote pb.ClusterClient, c *Client) Cluster {

-func NewLeaseFromLeaseClient(remote pb.LeaseClient, keepAliveTimeout time.Duration) Lease {
+func NewLeaseFromLeaseClient(remote pb.LeaseClient, c *Client, keepAliveTimeout time.Duration) Lease {

-func NewMaintenanceFromMaintenanceClient(remote pb.MaintenanceClient) Maintenance {
+func NewMaintenanceFromMaintenanceClient(remote pb.MaintenanceClient, c *Client) Maintenance {

-func NewWatchFromWatchClient(wc pb.WatchClient) Watcher {
+func NewWatchFromWatchClient(wc pb.WatchClient, c *Client) Watcher {

Modifier l’API `clientv3.Lease.TimeToLive`

Précédemment, l’API clientv3.Lease.TimeToLive renvoyait lease.ErrLeaseNotFound en cas d’ID de bail inexistant. La version 3.2 renvoie désormais TTL=-1 dans sa réponse, sans erreur (voir #7305 ).

Avant

// when leaseID does not exist
resp, err := TimeToLive(ctx, leaseID)
resp == nil
err == lease.ErrLeaseNotFound

Après

// when leaseID does not exist
resp, err := TimeToLive(ctx, leaseID)
resp.TTL == -1
err == nil

Déplacer `clientv3.NewFromConfigFile` vers `clientv3.yaml.NewConfig`

clientv3.NewFromConfigFile est déplacé vers yaml.NewConfig.

Avant

import "github.com/coreos/etcd/clientv3"
clientv3.NewFromConfigFile

Après

import clientv3yaml "github.com/coreos/etcd/clientv3/yaml"
clientv3yaml.NewConfig

Changement apporté à `--listen-peer-urls` et `--listen-client-urls`

3.2 refuse désormais les noms de domaine pour --listen-peer-urls et --listen-client-urls (3.1 n’affichait que des avertissements), car un nom de domaine n’est pas valide pour le lien d’interface réseau. Assurez-vous que ces URL sont correctement formatées en tant que scheme://IP:port.

Consultez issue #6336 pour plus de contextes.

Liste de vérification pour la mise à jour du serveur

Exigences de mise à jour

Pour mettre à jour un déploiement etcd existant vers la version 3.2, le cluster en cours d’exécution doit être la version 3.1 ou ultérieure. Si la version est antérieure à 3.1, veuillez mettre à jour vers la version 3.1 avant de procéder à la mise à jour vers la version 3.2.

Préparation

Avant de mettre à jour etcd, testez toujours les services dépendants d’etcd dans un environnement de préproduction avant de déployer la mise à jour dans l’environnement de production.

Avant de commencer, sauvegardez les données etcd . Si une erreur survient durant la mise à jour, il sera possible d’utiliser cette sauvegarde pour rétrograder vers la version existante d’etcd. Veuillez noter que la commande snapshot ne sauvegarde que les données v3. Pour les données v2, consultez sauvegarde du magasin de données v2 .

Versions mixtes

Lors d’une mise à jour, 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 n’est considéré comme mis à jour qu’une fois que tous ses membres ont été mis à jour vers la version 3.2. En interne, les membres etcd négocient entre eux afin de déterminer la version globale du cluster, qui détermine la version signalée et les fonctionnalités prises en charge.

Limitations

Note : Si le cluster ne contient que des données v3 et aucune donnée v2, il n’est pas soumis à cette limitation.

Rétrogradation

Si tous les membres ont été mis à jour vers la version v3.2, le cluster sera mis à jour vers la version v3.2, et le retour en arrière depuis cet état finalisé est impossible. Si toutefois un seul membre reste en version v3.1, le cluster et ses opérations restent “v3.1”, et il est possible, depuis cet état de cluster mixte, de revenir à l’utilisation d’un binaire etcd v3.1 sur tous les membres.

Veuillez sauvegarder le répertoire de données de tous les membres etcd afin de permettre la rétrogradation du cluster, même après sa mise à jour complète.

Procédure de mise à jour

Cet exemple montre comment mettre à jour un cluster etcd v3.1 composé de 3 membres, en cours d’exécution sur une machine locale.

1. Vérifier les prérequis de mise à jour

Le cluster est-il sain et en cours d’exécution sous la version 3.1.x ?

$ ETCDCTL_API=3 etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:2379 is healthy: successfully committed proposal: took = 6.600684ms
localhost:22379 is healthy: successfully committed proposal: took = 8.540064ms
localhost:32379 is healthy: successfully committed proposal: took = 8.763432ms

$ curl http://localhost:2379/version
{"etcdserver":"3.1.7","etcdcluster":"3.1.0"}

2. Arrêtez le processus etcd existant

2017-04-27 14:13:31.491746 I | raft: c89feb932daef420 [term 3] received MsgTimeoutNow from 6d4f535bae3ab960 and starts an election to get leadership.
2017-04-27 14:13:31.491769 I | raft: c89feb932daef420 became candidate at term 4
2017-04-27 14:13:31.491788 I | raft: c89feb932daef420 received MsgVoteResp from c89feb932daef420 at term 4
2017-04-27 14:13:31.491797 I | raft: c89feb932daef420 [logterm: 3, index: 9] sent MsgVote request to 6d4f535bae3ab960 at term 4
2017-04-27 14:13:31.491805 I | raft: c89feb932daef420 [logterm: 3, index: 9] sent MsgVote request to 9eda174c7df8a033 at term 4
2017-04-27 14:13:31.491815 I | raft: raft.node: c89feb932daef420 lost leader 6d4f535bae3ab960 at term 4
2017-04-27 14:13:31.524084 I | raft: c89feb932daef420 received MsgVoteResp from 6d4f535bae3ab960 at term 4
2017-04-27 14:13:31.524108 I | raft: c89feb932daef420 [quorum:2] has received 2 MsgVoteResp votes and 0 vote rejections
2017-04-27 14:13:31.524123 I | raft: c89feb932daef420 became leader at term 4
2017-04-27 14:13:31.524136 I | raft: raft.node: c89feb932daef420 elected leader c89feb932daef420 at term 4
2017-04-27 14:13:31.592650 W | rafthttp: lost the TCP streaming connection with peer 6d4f535bae3ab960 (stream MsgApp v2 reader)
2017-04-27 14:13:31.592825 W | rafthttp: lost the TCP streaming connection with peer 6d4f535bae3ab960 (stream Message reader)
2017-04-27 14:13:31.693275 E | rafthttp: failed to dial 6d4f535bae3ab960 on stream Message (dial tcp [::1]:2380: getsockopt: connection refused)
2017-04-27 14:13:31.693289 I | rafthttp: peer 6d4f535bae3ab960 became inactive
2017-04-27 14:13:31.936678 W | rafthttp: lost the TCP streaming connection with peer 6d4f535bae3ab960 (stream Message writer)

Il est recommandé de procéder à une sauvegarde des données etcd à cette étape afin de disposer d’un chemin de retour en cas de problème :

$ etcdctl snapshot save backup.db

3. Remplacer le binaire par etcd v3.2 et démarrer le nouveau processus etcd

Le nouvel etcd v3.2 publiera ses informations dans le cluster :

2017-04-27 14:14:25.363225 I | etcdserver: published {Name:s1 ClientURLs:[http://localhost:2379]} to cluster a9ededbffcb1b1f1

Vérifiez que chaque membre, puis l’ensemble du cluster, devient sain avec le nouveau binaire etcd v3.2 :

$ ETCDCTL_API=3 /etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:22379 is healthy: successfully committed proposal: took = 5.540129ms
localhost:32379 is healthy: successfully committed proposal: took = 7.321771ms
localhost:2379 is healthy: successfully committed proposal: took = 10.629901ms

2017-04-27 14:15:17.071804 W | etcdserver: member c89feb932daef420 has a higher version 3.2.0
2017-04-27 14:15:21.073110 W | etcdserver: the local etcd version 3.1.7 is not up-to-date
2017-04-27 14:15:21.073142 W | etcdserver: member 6d4f535bae3ab960 has a higher version 3.2.0
2017-04-27 14:15:21.073157 W | etcdserver: the local etcd version 3.1.7 is not up-to-date
2017-04-27 14:15:21.073164 W | etcdserver: member c89feb932daef420 has a higher version 3.2.0

4. Répétez l’étape 2 à l’étape 3 pour tous les autres membres

5. Terminer

Lorsque tous les membres sont mis à jour, le cluster signalera avec succès la mise à jour vers la version 3.2 :

2017-04-27 14:15:54.536901 N | etcdserver/membership: updated the cluster version from 3.1 to 3.2
2017-04-27 14:15:54.537035 I | etcdserver/api: enabled capabilities for version 3.2

$ ETCDCTL_API=3 /etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:2379 is healthy: successfully committed proposal: took = 2.312897ms
localhost:22379 is healthy: successfully committed proposal: took = 2.553476ms
localhost:32379 is healthy: successfully committed proposal: took = 2.517902ms

8 - Mettre à jour etcd de la version 3.0 à la 3.1

Processus, listes de vérification et notes sur la mise à niveau d’etcd de la version 3.0 à la 3.1

Dans le cas général, la mise à niveau d’etcd 3.0 vers 3.1 peut être effectuée sans interruption de service, par mise à niveau progressive :

un nœud à la fois, arrêtez les processus etcd v3.0 et remplacez-les par des processus etcd v3.1
après avoir lancé tous les processus v3.1, les nouvelles fonctionnalités de la version v3.1 sont disponibles pour le cluster

Avant de lancer la mise à jour , lisez le reste du présent guide afin de vous préparer.

Listes de vérification pour la mise à jour

Avertissement

Surveillance

Les métriques suivantes issues de la version 3.0.x ont été dépréciées en faveur de go-grpc-prometheus :

etcd_grpc_requests_total
etcd_grpc_requests_failed_total
etcd_grpc_active_streams
etcd_grpc_unary_requests_duration_seconds

Exigences de mise à jour

Pour mettre à jour un déploiement etcd existant vers la version 3.1, le cluster en cours d’exécution doit être la version 3.0 ou ultérieure. Si la version est antérieure à 3.0, veuillez mettre à jour vers la version 3.0 avant de procéder à la mise à jour vers la version 3.1.

Préparation

Avant de mettre à jour etcd, testez toujours les services dépendants d’etcd dans un environnement de préproduction avant de déployer la mise à jour dans l’environnement de production.

Versions mixtes

Lors d’une mise à jour, 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 n’est considéré comme mis à jour qu’une fois que tous ses membres ont été mis à jour vers la version 3.1. En interne, les membres etcd négocient entre eux afin de déterminer la version globale du cluster, qui détermine la version signalée et les fonctionnalités prises en charge.

Limitations

Note : Si le cluster ne contient que des données v3 et aucune donnée v2, il n’est pas soumis à cette limitation.

Rétrogradation

Si tous les membres ont été mis à jour vers la version v3.1, le cluster sera mis à jour vers la v3.1, et un retour en arrière depuis cet état finalisé est impossible. Toutefois, si un seul membre reste en version v3.0, le cluster et ses opérations restent “v3.0”, et il est possible, depuis cet état de cluster mixte, de revenir à l’utilisation d’un binaire etcd v3.0 sur tous les membres.

Veuillez sauvegarder le répertoire de données de tous les membres etcd afin de permettre la rétrogradation du cluster, même après sa mise à jour complète.

Procédure de mise à jour

Cet exemple montre comment mettre à jour un cluster etcd à 3 membres, version 3.0, en cours d’exécution sur une machine locale.

1. Vérifier les prérequis de mise à jour

Le cluster est-il sain et en cours d’exécution sous la version 3.0.x ?

$ ETCDCTL_API=3 etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:2379 is healthy: successfully committed proposal: took = 6.600684ms
localhost:22379 is healthy: successfully committed proposal: took = 8.540064ms
localhost:32379 is healthy: successfully committed proposal: took = 8.763432ms

$ curl http://localhost:2379/version
{"etcdserver":"3.0.16","etcdcluster":"3.0.0"}

2. Arrêtez le processus etcd existant

2017-01-17 09:34:18.352662 I | raft: raft.node: 1640829d9eea5cfb elected leader 1640829d9eea5cfb at term 5
2017-01-17 09:34:18.359630 W | etcdserver: failed to reach the peerURL(http://localhost:2380) of member fd32987dcd0511e0 (Get http://localhost:2380/version: dial tcp 127.0.0.1:2380: getsockopt: connection refused)
2017-01-17 09:34:18.359679 W | etcdserver: cannot get the version of member fd32987dcd0511e0 (Get http://localhost:2380/version: dial tcp 127.0.0.1:2380: getsockopt: connection refused)
2017-01-17 09:34:18.548116 W | rafthttp: lost the TCP streaming connection with peer fd32987dcd0511e0 (stream Message writer)
2017-01-17 09:34:19.147816 W | rafthttp: lost the TCP streaming connection with peer fd32987dcd0511e0 (stream MsgApp v2 writer)
2017-01-17 09:34:34.364907 W | etcdserver: failed to reach the peerURL(http://localhost:2380) of member fd32987dcd0511e0 (Get http://localhost:2380/version: dial tcp 127.0.0.1:2380: getsockopt: connection refused)

Il est recommandé de procéder à une sauvegarde des données etcd à cette étape afin de disposer d’un chemin de retour en cas de problème :

$ etcdctl snapshot save backup.db

3. Remplacer le binaire par etcd v3.1 et démarrer le nouveau processus etcd

Le nouvel etcd v3.1 publiera ses informations dans le cluster :

2017-01-17 09:36:00.996590 I | etcdserver: published {Name:my-etcd-1 ClientURLs:[http://localhost:2379]} to cluster 46bc3ce73049e678

Vérifiez que chaque membre, puis l’ensemble du cluster, devient sain avec le binaire etcd v3.1 nouvellement installé :

$ ETCDCTL_API=3 /etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:22379 is healthy: successfully committed proposal: took = 5.540129ms
localhost:32379 is healthy: successfully committed proposal: took = 7.321671ms
localhost:2379 is healthy: successfully committed proposal: took = 10.629901ms

2017-01-17 09:36:38.406268 W | etcdserver: the local etcd version 3.0.16 is not up-to-date
2017-01-17 09:36:38.406295 W | etcdserver: member fd32987dcd0511e0 has a higher version 3.1.0
2017-01-17 09:36:42.407695 W | etcdserver: the local etcd version 3.0.16 is not up-to-date
2017-01-17 09:36:42.407730 W | etcdserver: member fd32987dcd0511e0 has a higher version 3.1.0

4. Répétez l’étape 2 à l’étape 3 pour tous les autres membres

5. Terminer

Lorsque tous les membres sont mis à jour, le cluster signalera avec succès la mise à jour vers la version 3.1 :

2017-01-17 09:37:03.100015 I | etcdserver: updating the cluster version from 3.0 to 3.1
2017-01-17 09:37:03.104263 N | etcdserver/membership: updated the cluster version from 3.0 to 3.1
2017-01-17 09:37:03.104374 I | etcdserver/api: enabled capabilities for version 3.1

$ ETCDCTL_API=3 /etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:2379 is healthy: successfully committed proposal: took = 2.312897ms
localhost:22379 is healthy: successfully committed proposal: took = 2.553476ms
localhost:32379 is healthy: successfully committed proposal: took = 2.516902ms

9 - Mettre à jour etcd de la version 2.3 à la 3.0

Processus, listes de vérification et notes sur la mise à jour d’etcd de la version 2.3 à la 3.0

Dans le cas général, la mise à niveau d’etcd 2.3 vers 3.0 peut s’effectuer sans interruption de service, par mise à niveau progressive :

un par un, arrêtez les processus etcd v2.3 et remplacez-les par des processus etcd v3.0
après avoir lancé tous les processus v3.0, les nouvelles fonctionnalités de la version 3.0 sont disponibles pour le cluster

Avant de lancer la mise à jour , lisez le reste du présent guide afin de vous préparer.

Listes de vérification pour la mise à jour

Avertissement

Exigences de mise à jour

Pour mettre à jour un déploiement etcd existant vers la version 3.0, le cluster en cours d’exécution doit être la version 2.3 ou ultérieure. Si la version est antérieure à 2.3, veuillez mettre à jour vers 2.3 avant de procéder à la mise à jour vers la version 3.0.

Préparation

Avant de mettre à jour etcd, testez toujours les services dépendants d’etcd dans un environnement de préproduction avant de déployer la mise à jour dans l’environnement de production.

Avant de commencer, sauvegardez le répertoire de données etcd . Si une erreur survient durant la mise à jour, il sera possible d’utiliser cette sauvegarde pour revenir à la version d’etcd actuellement déployée .

Versions mixtes

Lors d’une mise à jour, 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 n’est considéré comme mis à jour qu’une fois que tous ses membres ont été mis à jour vers la version 3.0. En interne, les membres etcd négocient entre eux afin de déterminer la version globale du cluster, qui contrôle la version signalée et les fonctionnalités prises en charge.

Limitations

Il peut falloir jusqu’à 2 minutes pour que le membre nouvellement mis à jour rattrape le cluster existant lorsque la taille totale des données dépasse 50 Mo. Vérifiez la taille d’un instantané récent pour estimer la taille totale des données. Autrement dit, le plus sûr est d’attendre 2 minutes entre chaque mise à jour de membre.

Rétrogradation

Si tous les membres ont été mis à jour vers la version v3.0, le cluster sera mis à jour vers la version v3.0, et le retour à une version antérieure à partir de cet état finalisé est impossible. Si toutefois un seul membre reste en version v2.3, le cluster et ses opérations restent au niveau « v2.3 », et il est possible, depuis cet état de cluster mixte, de revenir à l’utilisation d’un binaire etcd v2.3 sur tous les membres.

Veuillez sauvegarder le répertoire de données de tous les membres etcd afin de permettre la rétrogradation du cluster, même après sa mise à jour complète.

Procédure de mise à jour

Cet exemple détaille la mise à jour d’un cluster etcd v2.3 à trois membres fonctionnant sur une machine locale.

1. Vérifier les prérequis de mise à jour.

Le cluster est-il sain et en cours d’exécution sous la version v.2.3.x ?

$ etcdctl cluster-health
member 6e3bd23ae5f1eae0 is healthy: got healthy result from http://localhost:22379
member 924e2e83e93f2560 is healthy: got healthy result from http://localhost:32379
member 8211f1d0f64f3269 is healthy: got healthy result from http://localhost:12379
cluster is healthy

$ curl http://localhost:2379/version
{"etcdserver":"2.3.x","etcdcluster":"2.3.8"}

2. Arrêtez le processus etcd existant

2016-06-27 15:21:48.624124 E | rafthttp: failed to dial 8211f1d0f64f3269 on stream Message (dial tcp 127.0.0.1:12380: getsockopt: connection refused)
2016-06-27 15:21:48.624175 I | rafthttp: the connection with 8211f1d0f64f3269 became inactive

Il est recommandé de procéder à une sauvegarde du répertoire de données etcd afin de disposer d’un chemin de retour en cas de problème :

$ etcdctl backup \
      --data-dir /var/lib/etcd \
      --backup-dir /tmp/etcd_backup

3. Remplacer le binaire par etcd v3.0 et démarrer le nouveau processus etcd

Le nouvel etcd v3.0 publiera ses informations dans le cluster :

09:58:25.938673 I | etcdserver: published {Name:infra1 ClientURLs:[http://localhost:12379]} to cluster 524400597fb1d5f6

Vérifiez que chaque membre, puis l’ensemble du cluster, devient sain avec le nouveau binaire etcd v3.0 :

$ etcdctl cluster-health
member 6e3bd23ae5f1eae0 is healthy: got healthy result from http://localhost:22379
member 924e2e83e93f2560 is healthy: got healthy result from http://localhost:32379
member 8211f1d0f64f3269 is healthy: got healthy result from http://localhost:12379
cluster is healthy

2016-06-27 15:22:05.679644 W | etcdserver: the local etcd version 2.3.7 is not up-to-date
2016-06-27 15:22:05.679660 W | etcdserver: member 8211f1d0f64f3269 has a higher version 3.0.0

4. Répétez l’étape 2 à l’étape 3 pour tous les autres membres

5. Terminer

Lorsque tous les membres sont mis à jour, le cluster signalera avec succès la mise à jour vers la version 3.0 :

2016-06-27 15:22:19.873751 N | membership: updated the cluster version from 2.3 to 3.0
2016-06-27 15:22:19.914574 I | api: enabled capabilities for version 3.0.0

$ ETCDCTL_API=3 etcdctl endpoint health
127.0.0.1:12379 is healthy: successfully committed proposal: took = 18.440155ms
127.0.0.1:32379 is healthy: successfully committed proposal: took = 13.651368ms
127.0.0.1:22379 is healthy: successfully committed proposal: took = 18.513301ms

Considérations complémentaires

Les variables d’environnement etcdctl ont été mises à jour. Si ETCDCTL_API=2 etcdctl cluster-health fonctionne correctement mais que ETCDCTL_API=3 etcdctl endpoints health renvoie Error: grpc: timed out when dialing, veillez à utiliser les nouveaux noms de variables .

Problèmes connus

etcd < v3.1 ne fonctionne pas correctement s’il est compilé avec Go > v1.7. Consultez Problème 6951 pour plus d’informations.
Si une erreur telle que transport: http2Client.notifyError got notified that the client transport was broken unexpected EOF. apparaît dans les journaux du serveur etcd, assurez-vous qu’etcd est une version précompilée ou bien compilée avec (etcd v3.1+ & go v1.7+) ou (etcd <v3.1 & go v1.6.x).
L’ajout d’un membre v3 à un cluster v2.3 pendant une mise à jour n’est pas pris en charge et peut provoquer des paniques. Consultez Problème 7249 pour plus d’informations. Les versions mixtes de membres etcd ne sont autorisées que pendant la migration vers v3. Terminez les mises à jour avant d’effectuer toute modification de la composition du cluster.

Mise à jour

1 - Mise à jour des clusters etcd et des applications

Politique de mise à jour

Mise à jour d’un cluster etcd v3.x

Mise à niveau depuis etcd v2.3

2 - Mettre à jour etcd de la version v3.6 à la version v3.7

Listes de vérification pour la mise à jour

Mise à jour 3.6

Magasin V2

Refactorisation Go

Drapeaux supprimés

Drapeaux ajoutés

Drapeaux avec de nouvelles valeurs par défaut

Liste de vérification pour la mise à jour du serveur

Exigences de mise à jour

Préparation

Versions mixtes

Retour arrière

Procédure de mise à jour

Étape 1 : vérifier les exigences de mise à jour

Étape 2 : télécharger la sauvegarde d’instantané depuis le leader

Étape 3 : arrêter un serveur etcd existant

Étape 4 : redémarrer le serveur etcd avec la même configuration

Étape 5 : répéter l’étape 3 et l’étape 4 pour les membres restants

3 - Mettre à jour etcd de la version v3.5 à la version v3.6

Listes de vérification pour la mise à jour

Mise à jour 3.5

Magasin V2

Drapeaux ajoutés

Drapeaux supprimés

Drapeaux obsolètes

Migration des options expérimentales de v3.5 vers les portes fonctionnelles

Drapeaux avec de nouvelles valeurs par défaut

Différence entre les métriques Prometheus

Liste de vérification pour la mise à jour du serveur

Exigences de mise à jour

Préparation

Versions mixtes

Retour arrière

Procédure de mise à jour

Étape 1 : vérifier les exigences de mise à jour

Étape 2 : télécharger la sauvegarde d’instantané depuis le leader

Étape 3 : arrêter un serveur etcd existant

Étape 4 : redémarrer le serveur etcd avec la même configuration

Étape 5 : répéter l’étape 3 et l’étape 4 pour les membres restants

4 - Mettre à jour etcd de 3.4 à 3.5

Listes de vérification pour la mise à jour

Métriques Prometheus etcd_debugging_mvcc_db_total_size_in_bytes obsolètes

Métriques Prometheus etcd_debugging_mvcc_put_total obsolètes

Métriques Prometheus etcd_debugging_mvcc_delete_total obsolètes

Métriques Prometheus etcd_debugging_mvcc_txn_total obsolètes

Métriques Prometheus etcd_debugging_mvcc_range_total obsolètes

Dépréciation de etcd --logger capnslog

Dépréciation de etcd --log-output

Dépréciation de le drapeau etcd --debug (maintenant --log-level=debug)

Dépréciation de etcd --log-package-levels

Dépréciation de [CLIENT-URL]/config/local/log

Modifier les points d’accès HTTP de la passerelle gRPC (obsolète /v3beta)

Liste de vérification pour la mise à jour du serveur

Exigences de mise à jour

Préparation

Versions mixtes

Limitations

Rétrogradation

Procédure de mise à jour

Étape 1 : vérifier les exigences de mise à jour

Étape 2 : télécharger la sauvegarde d’instantané depuis le leader

Étape 3 : arrêter un serveur etcd existant

Étape 4 : redémarrer le serveur etcd avec la même configuration

Étape 5 : répéter l’étape 3 et l’étape 4 pour les membres restants

5 - Mettre à jour etcd de 3.3 à 3.4

Listes de vérification pour la mise à jour

Rendre ETCDCTL_API=3 etcdctl par défaut

Rendre etcd --enable-v2=false par défaut

Dépréciation des drapeaux etcd --ca-file et etcd --peer-ca-file

Erreur grpc.ErrClientConnClosing obsolète

Exiger grpc.WithBlock pour la connexion client

Dépréciation des métriques Prometheus etcd_debugging_mvcc_db_total_size_in_bytes

Dépréciation des métriques Prometheus etcd_debugging_mvcc_put_total

Dépréciation des métriques Prometheus etcd_debugging_mvcc_delete_total

Métriques Prometheus `etcd_debugging_mvcc_db_total_size_in_bytes` obsolètes

Métriques Prometheus `etcd_debugging_mvcc_put_total` obsolètes

Métriques Prometheus `etcd_debugging_mvcc_delete_total` obsolètes

Métriques Prometheus `etcd_debugging_mvcc_txn_total` obsolètes

Métriques Prometheus `etcd_debugging_mvcc_range_total` obsolètes

Dépréciation de `etcd --logger capnslog`

Dépréciation de `etcd --log-output`

Dépréciation de le drapeau `etcd --debug` (maintenant `--log-level=debug`)

Dépréciation de `etcd --log-package-levels`

Dépréciation de `[CLIENT-URL]/config/local/log`

Modifier les points d’accès HTTP de la passerelle gRPC (obsolète `/v3beta`)

Rendre `ETCDCTL_API=3 etcdctl` par défaut

Rendre `etcd --enable-v2=false` par défaut

Dépréciation des drapeaux `etcd --ca-file` et `etcd --peer-ca-file`

Erreur `grpc.ErrClientConnClosing` obsolète

Exiger `grpc.WithBlock` pour la connexion client

Dépréciation des métriques Prometheus `etcd_debugging_mvcc_db_total_size_in_bytes`

Dépréciation des métriques Prometheus `etcd_debugging_mvcc_put_total`

Dépréciation des métriques Prometheus `etcd_debugging_mvcc_delete_total`

Dépréciation des métriques Prometheus `etcd_debugging_mvcc_txn_total`

Dépréciation des métriques Prometheus `etcd_debugging_mvcc_range_total`

Dépréciation du drapeau `etcd --log-output` (maintenant `--log-outputs`)

Changer le type de champ `log-outputs` dans `etcd --config-file` en `[]string`

Renommer `embed.Config.LogOutput` en `embed.Config.LogOutputs`

v3.5 déprécie `capnslog`

Dépréciation du drapeau `etcd --debug` (maintenant `--log-level=debug`)

Champ `pkg/transport.TLSInfo.CAFile` obsolète

Modifier `embed.Config.SnapCount` en `embed.Config.SnapshotCount`

Modifier `etcdserver.ServerConfig.SnapCount` en `etcdserver.ServerConfig.SnapshotCount`

Signature de fonction modifiée dans le package `wal`

Modifier le type `IntervalTree` dans le package `pkg/adt`

Dépréciation de `embed.Config.SetupLogging`

Modifier les points d’entrée HTTP de la passerelle gRPC (remplacé `/v3beta` par `/v3`)

Changement du type de valeur du drapeau `etcd --auto-compaction-retention` en `string`

Modifier `*etcdserver.ServerConfig` en `etcdserver.ServerConfig`

Ajout du champ `embed.Config.LogOutput`

Modifier la réponse de l’endpoint `/health`

Modifier les points d’entrée HTTP de la passerelle gRPC (remplacé `/v3alpha` par `/v3beta`)

Changer le type d’erreur de l’API clientv3 `Snapshot`

Changer la sortie de la commande `etcdctl lease timetolive`

Modifier les imports `golang.org/x/net/context`

Dépréciation de `grpclog.Logger`

Dépréciation de `grpc.ErrClientConnTimeout`

Changer la valeur par défaut de `snapshot-count`

Dépréciation de `grpclog.Logger`

Dépréciation de `grpc.ErrClientConnTimeout`

Modifier l’API `clientv3.Lease.TimeToLive`

Déplacer `clientv3.NewFromConfigFile` vers `clientv3.yaml.NewConfig`

Changement apporté à `--listen-peer-urls` et `--listen-client-urls`