etcd : la base clé/valeur du control plane Kubernetes

Votre API server Kubernetes répond lentement ? Les pods mettent du temps à démarrer ? Le problème vient peut-être d'etcd, la base de données qui stocke l'intégralité de l'état de votre cluster. Ce guide vous apprend à diagnostiquer, sauvegarder et maintenir etcd pour éviter les pannes et garantir la résilience de votre infrastructure.

Ce que vous allez apprendre

• Expliquer ce que Kubernetes attend d'etcd : cohérence, latence, sécurité
• Vérifier la santé d'un cluster etcd en deux minutes, et diagnostiquer un etcd lent ou instable
• Créer et restaurer des snapshots, avec la procédure complète et testée
• Assurer la maintenance day-2 : compaction, défragmentation, quota, alarmes NOSPACE
• Surveiller etcd avec Prometheus et interpréter les signaux

Ce guide s'adresse aux administrateurs de clusters et aux SRE, en production comme en préparation de la CKA ou de la CKS. Les concepts valent pour kubeadm, k3s, RKE et toute distribution qui s'appuie sur etcd.

Les sorties publiées viennent d'un cluster Kubernetes 1.37, dont l'image embarquée est etcd 3.7.0. Deux conséquences pratiques structurent tout le reste de cette page. D'abord, la répartition des outils a changé : etcdctl snapshot n'offre plus que save, tandis que la vérification et la restauration d'un instantané sont passées à etcdutl. Ensuite, l'image est distroless : elle ne contient ni sh ni tar, seulement les deux binaires. Toutes les commandes de ce guide en tiennent compte.

Pourquoi etcd est critique dans Kubernetes

Kubernetes n'a aucune autre mémoire qu'etcd : ni fichier de configuration persistant, ni base secondaire. L'API server est un service sans état qui traduit vos requêtes en lectures et en écritures dans cette base clé/valeur. Comprendre ce couplage explique la plupart des incidents de control plane, et c'est le point de départ de tous les diagnostics de cette page.

Rôle exact d'etcd côté Kubernetes

etcd est la source de vérité unique de votre cluster Kubernetes. Tout ce que l'API server connaît, pods, services, secrets, configmaps, RBAC, est stocké dans etcd.

Ce qu'etcd stocke	Exemple
État désiré	"Je veux 3 réplicas de nginx"
État actuel	"2 pods running, 1 pending"
Configuration	Secrets, ConfigMaps, ServiceAccounts
Métadonnées	Labels, annotations, finalizers
Leases	Leader election des controllers

Glissez pour voir

Conséquence directe : si etcd est lent, l'API server est lent. Si etcd est down, l'API server ne peut plus persister l'état : les workloads existants continuent de tourner, mais aucune modification n'est possible (créations, suppressions, mises à jour). Selon la durée de l'indisponibilité, même la lecture via API peut se dégrader.

La redondance ne protège que de ce qu'elle couvre, et c'est le contresens le plus commun sur etcd. Trois membres protègent d'une panne de machine, pas d'un disque lent, d'un réseau instable ou d'un quota atteint : ces trois-là frappent les trois membres en même temps et rendent le cluster inutilisable malgré le quorum. D'où deux exigences matérielles non négociables, des SSD et une latence inférieure à 10 ms entre membres.

Ce que ce guide n'est pas

Ce n'est pas une page "historique" d'etcd. L'objectif est 100% opérationnel : des commandes à copier-coller et des runbooks pour résoudre les problèmes courants.

---

Modèle mental etcd en 15 minutes

Trois mécanismes suffisent à expliquer presque tous les incidents etcd : le consensus Raft, qui décide qui a le droit d'écrire ; le MVCC, qui conserve l'historique des modifications et fait grossir la base ; et les primitives transactions, watches et leases, dont Kubernetes dépend en permanence. Les connaître évite de traiter les symptômes sans comprendre la cause.

Raft : leader, followers, quorum

etcd utilise l'algorithme Raft pour garantir la cohérence des données entre tous les membres. Voici comment ça fonctionne :

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Règle d'or : sans quorum (majorité des membres disponibles), aucune écriture n'est possible.

Nombre de membres	Quorum requis	Tolérance aux pannes
1	1	0 (aucune)
3	2	1 membre
5	3	2 membres
7	4	3 membres

Glissez pour voir

Cette tolérance se vérifie en une manipulation sur le lab décrit plus bas. Arrêtez un des trois nœuds, puis demandez une écriture : elle passe.

docker stop etcd-lab-control-plane3
kubectl create namespace lab-quorum

Sortie

namespace/lab-quorum created

Deux membres sur trois forment bien la majorité, le cluster continue donc d'accepter les écritures. Ce qui change, c'est le diagnostic : la commande d'état signale explicitement le membre injoignable et sort en code 1, ce qui fera échouer votre supervision, à raison.

Sortie de endpoint status --cluster

Failed to get the status of endpoint https://172.26.0.5:2379 (context deadline exceeded)

Arrêtez un deuxième nœud et la majorité est perdue : plus aucune écriture n'aboutit, tandis que les charges déjà démarrées continuent de tourner, puisque ce sont les kubelets qui les maintiennent, pas etcd.

Le nombre de membres se choisit donc dans une fourchette étroite. Trois est le standard et convient à la quasi-totalité des clusters, il tolère la perte d'une machine. Cinq se justifie quand l'indisponibilité coûte très cher, il en tolère deux. Au-delà de cinq, le gain devient théorique alors que le coût est bien réel : chaque écriture doit être confirmée par la majorité, et plus la majorité est grande, plus l'écriture est lente. Un nombre pair n'apporte rien non plus, quatre membres tolérant la même panne unique que trois.

MVCC, révisions, compaction : pourquoi la base grossit

etcd utilise MVCC (Multi-Version Concurrency Control) : chaque modification crée une nouvelle révision sans supprimer l'ancienne. C'est ce qui permet les watches (notifications en temps réel).

Problème : sans maintenance, l'historique s'accumule indéfiniment.

Révision 1: pod-a créé
Révision 2: pod-a modifié (labels)
Révision 3: pod-a modifié (replicas)
Révision 4: pod-a supprimé
         ↓
   Toutes ces révisions sont conservées !

Solutions :

• Compaction : supprime les anciennes révisions (garde la plus récente)
• Défragmentation : récupère l'espace disque après compaction

Alarme NOSPACE

Si etcd atteint son quota (par défaut 2 GB), il passe en mode alarm : seules les lectures et suppressions sont autorisées. Le cluster est bloqué jusqu'à la résolution.

Transactions, watches, leases

etcd offre trois primitives que Kubernetes exploite massivement :

Primitive	Usage Kubernetes
Transactions	Mises à jour atomiques (create-or-update)
Watches	Controllers qui réagissent aux changements
Leases	Leader election, heartbeats

Glissez pour voir

À retenir : etcd est "simple" (clé/valeur) mais exigeant sur la qualité du stockage et du réseau.

---

Topologies etcd dans Kubernetes

Deux façons d'installer etcd coexistent : sur les nœuds du control plane, ou sur des machines dédiées. Le choix change la manière de sauvegarder, de renouveler les certificats et de mettre à jour le cluster. Identifier votre topologie est le préalable à toute intervention, car les chemins de fichiers et les commandes de maintenance en dépendent.

etcd "stacked" (sur les control planes)

C'est la topologie par défaut avec kubeadm et RKE2, et celle de la plupart des distributions qui embarquent etcd. k3s fait exception : sa documentation annonce SQLite comme datastore par défaut, et il ne bascule sur etcd embarqué que si on le lui demande, ou si des fichiers etcd existent déjà sur le disque. Chaque nœud du control plane héberge un membre etcd, et le nombre de membres suit donc mécaniquement le nombre de control planes : ajouter un troisième control plane ajoute un troisième membre etcd.

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Avantages : simplicité, moins de machines à gérer.

Inconvénients : si un control plane tombe, vous perdez un membre etcd.

etcd "external" (cluster séparé)

Pour les environnements critiques, etcd peut tourner sur des machines dédiées.

Quand c'est pertinent :

• Isolation des ressources (CPU/RAM/disque dédiés)
• Politique de backup différente
• Cluster etcd partagé entre plusieurs clusters K8s
• Exigences de latence strictes

Impacts opérationnels : certificats supplémentaires, endpoints à configurer, procédures de maintenance séparées.

---

Lab reproductible avec kind

kind (Kubernetes in Docker) crée un cluster complet dans des conteneurs, en quelques minutes et sans machine virtuelle. Avec trois nœuds de control plane, vous obtenez un vrai cluster etcd à trois membres, donc un quorum réel à observer. Toutes les commandes de ce guide sont exécutables sur ce lab.

L'intérêt est d'acquérir les gestes sans risquer un cluster de production, et ils se transposent : seuls les chemins de certificats changent d'une distribution à l'autre, les commandes etcdctl sont les mêmes partout.

Déployer un cluster kind avec 3 control planes

Le nombre de lignes role: control-plane détermine directement le nombre de membres etcd. Trois est le minimum pour tolérer la perte d'un membre sans perdre le quorum.

1. Créer le fichier de configuration

   kind-etcd-lab.yaml

   kind: Cluster
   apiVersion: kind.x-k8s.io/v1alpha4
   nodes:
   - role: control-plane
   - role: control-plane
   - role: control-plane

2. Créer le cluster

   kind create cluster --name etcd-lab --config kind-etcd-lab.yaml

   Sortie attendue :

   Creating cluster "etcd-lab" ...
    ✓ Ensuring node image (kindest/node:v1.37.0) 🖼️
    ✓ Preparing nodes 📦 📦 📦
    ✓ Configuring the external load balancer ⚖️
    ✓ Writing configuration 📜
    ✓ Starting control-plane 🕹️
    ✓ Installing CNI 🔌
    ✓ Installing StorageClass 💾
    ✓ Joining more control-plane nodes 🎮
   Set kubectl context to "kind-etcd-lab"

   Comptez une minute environ. La ligne « Configuring the external load balancer » n'apparaît qu'à partir de deux control planes : kind place un répartiteur devant les trois API servers, ce qu'un cluster à un seul nœud n'a pas.

3. Vérifier les pods etcd

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

   Sortie attendue :

   NAME                           READY   STATUS    RESTARTS   AGE   IP           NODE
   etcd-etcd-lab-control-plane    1/1     Running   0          60s   172.26.0.7   etcd-lab-control-plane
   etcd-etcd-lab-control-plane2   1/1     Running   0          18s   172.26.0.6   etcd-lab-control-plane2
   etcd-etcd-lab-control-plane3   1/1     Running   0          12s   172.26.0.5   etcd-lab-control-plane3

Accéder à etcd de manière sécurisée

etcd exige une authentification mTLS (mutual TLS). Voici le pattern recommandé pour exécuter des commandes etcdctl :

kubectl exec -n kube-system etcd-etcd-lab-control-plane -- etcdctl \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  --endpoints=https://127.0.0.1:2379 \
  <COMMANDE>

etcdctl est appelé directement, sans passer par un shell. C'est une obligation, pas une préférence : l'image etcd livrée avec Kubernetes, registry.k8s.io/etcd:3.7.0-0 en 1.37, est distroless. Elle ne contient ni sh ni tar, seulement les binaires etcdctl et etcdutl. Un kubectl exec ... -- sh -c '...' y répond :

exec: "sh": executable file not found in $PATH

Deux conséquences pratiques. Les options passent par des drapeaux, jamais par des variables d'environnement exportées. Et ETCDCTL_API=3 n'a plus lieu d'être : l'API v3 est le défaut depuis etcd 3.4.

Enfin, --endpoints=https://127.0.0.1:2379 vaut mieux que l'adresse du nœud : la commande s'exécute dans le conteneur etcd, la boucle locale y est donc toujours juste.

Répéter ces cinq lignes à chaque commande devient vite pénible. Une fonction définie sur votre poste, pas dans le conteneur, règle le problème pour toute la session :

etcdctl-lab() {
  kubectl exec -n kube-system etcd-etcd-lab-control-plane -- etcdctl \
    --cacert=/etc/kubernetes/pki/etcd/ca.crt \
    --cert=/etc/kubernetes/pki/etcd/server.crt \
    --key=/etc/kubernetes/pki/etcd/server.key \
    --endpoints=https://127.0.0.1:2379 "$@"
}

La suite du guide écrit les commandes en entier, pour qu'elles restent copiables telles quelles, mais etcdctl-lab endpoint health fait le même travail.

Valider la connectivité

Trois commandes se complètent et ne répondent pas à la même question. endpoint health dit si un membre accepte une écriture, endpoint status détaille son état interne, member list donne la composition déclarée. Un membre peut figurer dans member list tout en étant injoignable : c'est cet écart entre les deux vues qui révèle la panne.

Vérifier la santé d'un endpoint

Le test n'est pas une simple ouverture de connexion : etcd soumet réellement une proposition Raft et mesure le temps qu'elle met à être validée. Un endpoint healthy prouve donc que le quorum fonctionne à cet instant.

kubectl exec -n kube-system etcd-etcd-lab-control-plane -- etcdctl \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  --endpoints=https://127.0.0.1:2379 \
  endpoint health

Sortie attendue :

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

Vérifier le statut de tous les membres

Utilisez --cluster pour interroger automatiquement tous les membres (plus robuste que de lister les IPs manuellement) :

kubectl exec -n kube-system etcd-etcd-lab-control-plane -- etcdctl \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  --endpoints=https://127.0.0.1:2379 \
  endpoint status --cluster --write-out=table

Sortie attendue, relevée sur le lab en etcd 3.7.0. Le tableau est large, seize colonnes, et se lit en diagonale : cinq d'entre elles portent tout ce qui sert au diagnostic.

┌─────────────────────────┬──────────────────┬─────────┬─────────┬────────┬───────────────────────┬────────┬───────────┬───────────┬────────────┬────────┐
│        ENDPOINT         │        ID        │ VERSION │ DB SIZE │ IN USE │ PERCENTAGE NOT IN USE │ QUOTA  │ IS LEADER │ RAFT TERM │ RAFT INDEX │ ERRORS │
├─────────────────────────┼──────────────────┼─────────┼─────────┼────────┼───────────────────────┼────────┼───────────┼───────────┼────────────┼────────┤
│ https://172.26.0.6:2379 │ 370646228c096921 │   3.7.0 │  1.7 MB │ 1.7 MB │                    1% │ 2.1 GB │     false │         2 │        776 │        │
│ https://172.26.0.7:2379 │ 69d49f43581645df │   3.7.0 │  1.7 MB │ 1.7 MB │                    1% │ 2.1 GB │      true │         2 │        776 │        │
│ https://172.26.0.5:2379 │ e5237121cc9c0c3a │   3.7.0 │  1.7 MB │ 1.7 MB │                    1% │ 2.1 GB │     false │         2 │        776 │        │

Cinq colonnes ont été retirées de l'extrait ci-dessus pour qu'il tienne à l'écran, STORAGE VERSION, IS LEARNER, RAFT APPLIED INDEX, DOWNGRADE TARGET VERSION et DOWNGRADE ENABLED : elles apparaissent bien dans la vraie sortie, ne vous étonnez pas de les y trouver en plus.

Ce qu'il faut vérifier :

Colonne	Ce que ça signifie	Valeur attendue
IS LEADER	Un seul membre doit être leader	Exactement 1 true
DB SIZE	Taille du fichier de base	Similaire sur tous les membres
IN USE	Part réellement utilisée de ce fichier	Proche de DB SIZE
PERCENTAGE NOT IN USE	Espace à récupérer par défragmentation	Quelques pour cent
QUOTA	Plafond au-delà duquel l'alarme se déclenche	2.1 GB par défaut
RAFT INDEX	Index de réplication	Identique sur tous les membres
ERRORS	Alarmes actives	Vide

Glissez pour voir

Deux de ces colonnes n'existaient pas dans les versions plus anciennes et changent la façon de travailler. QUOTA affiche le plafond noir sur blanc, il n'y a plus à le supposer : 2.1 GB, soit les 2 Gio par défaut d'etcd, sur un cluster où aucun --quota-backend-bytes n'est posé. Et PERCENTAGE NOT IN USE mesure directement ce que la défragmentation récupérerait, ce qui transforme une opération jusque-là décidée au jugé en une décision chiffrée.

Lister les membres du cluster

Cette liste reflète la composition déclarée du cluster, telle qu'etcd la connaît, pas l'état réel des machines. C'est la référence à consulter avant d'ajouter ou de retirer un membre, et la colonne ID fournit l'identifiant attendu par member remove.

kubectl exec -n kube-system etcd-etcd-lab-control-plane -- etcdctl \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  --endpoints=https://127.0.0.1:2379 \
  member list --write-out=table

Sortie attendue :

┌──────────────────┬─────────┬─────────────────────────┬─────────────────────────┬─────────────────────────┬────────────┐
│        ID        │ STATUS  │          NAME           │       PEER ADDRS        │      CLIENT ADDRS       │ IS LEARNER │
├──────────────────┼─────────┼─────────────────────────┼─────────────────────────┼─────────────────────────┼────────────┤
│ 370646228c096921 │ started │ etcd-lab-control-plane2 │ https://172.26.0.6:2380 │ https://172.26.0.6:2379 │      false │
│ 69d49f43581645df │ started │  etcd-lab-control-plane │ https://172.26.0.7:2380 │ https://172.26.0.7:2379 │      false │
│ e5237121cc9c0c3a │ started │ etcd-lab-control-plane3 │ https://172.26.0.5:2380 │ https://172.26.0.5:2379 │      false │
└──────────────────┴─────────┴─────────────────────────┴─────────────────────────┴─────────────────────────┴────────────┘

L'ordre des lignes suit les identifiants, pas les noms : ne cherchez pas de signification dans le fait que control-plane2 apparaisse en premier.

---

Santé et diagnostic : les checks qui sauvent

En incident, l'erreur classique consiste à redémarrer un membre avant d'avoir compris, au risque de faire basculer le cluster sous le quorum. La méthode inverse tient en quatre vérifications sans effet de bord, puis une lecture ciblée des journaux. Les sections qui suivent donnent cette séquence, puis les symptômes fréquents et leurs causes.

Check baseline (2 minutes)

Voici la séquence de diagnostic à exécuter en cas de problème. Les certificats se passent en drapeaux, comme montré plus haut.

1. Vérifier que tous les membres répondent

   etcdctl --endpoints=https://127.0.0.1:2379 endpoint health --cluster

   Résultat attendu : tous les endpoints sont healthy

2. Identifier le leader

   etcdctl --endpoints=https://127.0.0.1:2379 endpoint status --cluster --write-out=table

   Résultat attendu : un seul membre a IS LEADER = true

3. Vérifier la cohérence des index

   Dans la sortie précédente, RAFT INDEX et RAFT APPLIED INDEX doivent être identiques sur tous les membres. Un décalage indique un problème de réplication.

4. Vérifier les alarmes

   etcdctl --endpoints=https://127.0.0.1:2379 alarm list

   Résultat attendu : sortie vide (aucune alarme)

Symptômes fréquents → Hypothèses → Actions

Les symptômes remontés concernent presque toujours Kubernetes, jamais etcd directement : kubectl qui traîne, Pods bloqués en Pending, déploiements qui expirent. Le lien avec etcd se confirme ou s'écarte en quelques commandes.

API server lent ou timeouts

Trois causes dominent, et chacune a sa commande de diagnostic. Traitez-les dans l'ordre du tableau : une alarme active bloque tout le reste et rend les autres mesures ininterprétables.

Symptôme	Cause probable	Diagnostic	Action
Requêtes kubectl lentes	etcd surchargé ou disque lent	endpoint status : latence élevée	Vérifier I/O disque, considérer des SSD
context deadline exceeded	Réseau instable entre API server et etcd	Logs etcd : slow request	Vérifier latence réseau, MTU
Pods pending longtemps	etcd en mode alarm	alarm list	Résoudre l'alarme (voir runbook)

Glissez pour voir

Élections fréquentes (leader instable)

Chaque élection interrompt les écritures : quelques changements de leader par heure suffisent à rendre l'API server erratique. Le compteur ci-dessous n'a de sens que rapporté à l'âge du Pod, un cluster ancien ayant forcément accumulé des élections légitimes.

# Compter les changements de leader dans les logs
kubectl logs -n kube-system etcd-etcd-lab-control-plane | grep -c "elected leader"

Cause	Solution
Latence réseau > 10ms	Améliorer réseau ou rapprocher les nœuds
CPU insuffisant	Augmenter les resources du pod/VM
Disque trop lent	Migrer vers SSD NVMe

Glissez pour voir

Runbook latence : où est le problème ?

Quand etcd est lent, il faut identifier où se situe la latence :

1. Vérifier la latence disque (métrique etcd_disk_backend_commit_duration_seconds)

   # Sur le nœud etcd
   iostat -x 1 5

   Attention : await > 10ms = disque trop lent → migrer vers SSD NVMe

2. Vérifier la latence réseau entre peers (métrique etcd_network_peer_round_trip_time_seconds)

   # Depuis un nœud etcd vers les autres
   ping -c 10 <IP_PEER>

   Attention : > 10ms = réseau instable → vérifier MTU, congestion

3. Corréler avec les logs etcd

   kubectl logs -n kube-system etcd-xxx --tail=200 | grep -E "took too long|slow"

   Les messages indiquent le type d'opération lente (apply, commit, etc.)

Lecture utile des logs etcd

Les journaux d'etcd sont volumineux et sans intérêt en exploitation courante. Quatre motifs concentrent l'information utile, et le filtre ci-dessous les isole en une commande.

kubectl logs -n kube-system etcd-etcd-lab-control-plane --tail=100 | grep -E "slow|compact|alarm|leader"

Ce qu'il faut chercher :

• took too long : requêtes lentes (I/O ou réseau)
• compaction : compaction en cours
• alarm : quota atteint
• elected leader : changement de leader

---

Sauvegarde et restauration

Un snapshot etcd est une copie cohérente de toute la base à un instant donné : il contient l'intégralité des objets Kubernetes, secrets compris. C'est le seul artefact qui permette de reconstruire un cluster dont le control plane a été perdu, et il doit donc être traité comme une donnée sensible, chiffrée et stockée hors du cluster.

Règle critique

Un backup non testé n'est pas un backup. Planifiez des exercices de restauration réguliers (au moins 1x/trimestre).

Stratégie de sauvegarde

La fréquence des snapshots fixe votre perte de données maximale acceptable : avec une sauvegarde horaire, une restauration ramène le cluster à l'état d'il y a une heure au pire. Les autres lignes du tableau protègent le snapshot lui-même, qui ne vaut rien s'il est stocké sur le nœud qui vient de brûler ou s'il n'a jamais été relu.

Élément	Recommandation
Fréquence	Toutes les heures minimum, toutes les 15 min pour clusters critiques
Rétention	7 jours minimum, 30 jours recommandé
Stockage	Hors du cluster (S3, GCS, NFS externe)
Chiffrement	GPG ou autre avant upload
Test	Restauration mensuelle sur cluster de test

Glissez pour voir

Créer un snapshot

Le snapshot est pris sur un seul membre et suffit à reconstruire tout le cluster, puisque Raft garantit que les membres détiennent les mêmes données. L'opération n'interrompt pas le service, mais elle écrit un fichier de la taille de la base dans le conteneur etcd : prévoyez la place et copiez-le à l'extérieur sans attendre.

1. Exécuter la sauvegarde

   kubectl exec -n kube-system etcd-etcd-lab-control-plane -- etcdctl \
     --cacert=/etc/kubernetes/pki/etcd/ca.crt \
     --cert=/etc/kubernetes/pki/etcd/server.crt \
     --key=/etc/kubernetes/pki/etcd/server.key \
     --endpoints=https://127.0.0.1:2379 \
     snapshot save /var/lib/etcd/snapshot.db

   Sortie attendue, relevée le 2026-09-13 sur etcd 3.7.0 :

   {"level":"info","msg":"created temporary db file","path":"/var/lib/etcd/snapshot.db.part"}
   {"level":"info","msg":"opened snapshot stream; downloading"}
   {"level":"info","msg":"fetching snapshot","endpoint":"https://127.0.0.1:2379"}
   {"level":"info","msg":"completed snapshot read; closing"}
   {"level":"info","msg":"fetched snapshot","size":"1.7 MB","took":"21.603078ms","etcd-version":"3.7.0"}
   {"level":"info","msg":"saved","path":"/var/lib/etcd/snapshot.db"}
   Snapshot saved at /var/lib/etcd/snapshot.db
   Server version 3.7.0

   Le fichier est d'abord écrit en .part puis renommé : un snapshot.db.part qui traîne signale une sauvegarde interrompue, à ne surtout pas prendre pour une sauvegarde valide.

   Le snapshot est écrit dans /var/lib/etcd et non dans /tmp : ce répertoire est le volume de données d'etcd, monté depuis le nœud. Le fichier est donc immédiatement lisible sur la machine, ce qui est le seul moyen de le sortir du conteneur.

2. Vérifier l'intégrité du snapshot (utilisez etcdutl, compatible 3.5/3.6)

   kubectl exec -n kube-system etcd-etcd-lab-control-plane -- \
     etcdutl snapshot status /var/lib/etcd/snapshot.db --write-out=table

   Sortie attendue, relevée sur etcd 3.7.0 :

   ┌──────────┬──────────┬────────────┬────────────┬─────────┐
   │   HASH   │ REVISION │ TOTAL KEYS │ TOTAL SIZE │ VERSION │
   ├──────────┼──────────┼────────────┼────────────┼─────────┤
   │ 21746525 │      713 │        426 │     1.7 MB │   3.7.0 │
   └──────────┴──────────┴────────────┴────────────┴─────────┘

   Ce point mérite un avertissement, parce que l'erreur est silencieuse. etcdctl snapshot status a été supprimé : en 3.7.0, etcdctl snapshot n'offre plus que save. Mais appeler la commande disparue ne produit aucune erreur ; etcdctl affiche l'aide de snapshot et sort en 0 :

   # ❌ démonstration du piège : cette commande n'existe plus et rend pourtant 0
   etcdctl snapshot status /var/lib/etcd/snapshot.db ; echo "code = $?"

   Sortie

   Manages etcd node snapshots
   
   Usage:
     etcdctl snapshot [command]
   code = 0

   Un script de sauvegarde qui vérifie son instantané avec etcdctl croit l'avoir vérifié, signale un succès, et ne contrôle rien du tout. C'est etcdutl qu'il faut appeler, et c'est ce que fait le script plus bas.

3. Sortir le snapshot du cluster

   kubectl cp ne fonctionne pas ici : il a besoin de tar dans le conteneur, et l'image distroless n'en contient pas. Le fichier ayant été écrit dans le volume de données, il est déjà sur le nœud :

   # Sur le control plane, en SSH
   cp /var/lib/etcd/snapshot.db /sauvegardes/etcd-$(date +%Y%m%d-%H%M%S).db

   Un snapshot laissé sur le nœud qu'il sauvegarde ne protège de rien : transférez-le ailleurs dans la foulée, et retirez la copie locale.

Restaurer un cluster etcd

Restaurer ne consiste pas à réinjecter des données dans un cluster vivant : l'opération recrée un répertoire de données neuf à partir du snapshot, sur chaque membre, etcd arrêté. Tout ce qui a été écrit après le snapshot est perdu, et le cluster repart avec un nouveau journal Raft. C'est une manœuvre de dernier recours, à répéter au moins une fois par trimestre sur un cluster de test pour ne pas la découvrir en incident.

Attention

Tous les membres doivent être restaurés à partir du même snapshot, sans quoi ils refusent de former un cluster cohérent.

Une idée reçue à écarter : l'identité du cluster ne change pas forcément. On lit souvent qu'une restauration réécrit le member ID et le cluster ID. C'est possible, ce n'est pas automatique. etcd calcule le member ID, par un SHA-1 des URL de pair triées et du jeton de cluster (--initial-cluster-token, etcd-cluster par défaut) : à paramètres identiques, l'identité obtenue est identique.

Mesuré le 2026-09-15 sur kubeadm 1.37, etcd 3.7.0. Avant restauration, endpoint status donne le member ID 2e830b06b400c72b. Après un etcdutl snapshot restore reprenant les valeurs du manifeste kubeadm, le même --name, le même --initial-cluster et les mêmes --initial-advertise-peer-urls, le member ID est le même, et le cluster ID aussi. Seul l'index Raft trahit le nouveau journal, 19103 avant, 57 après.

La conséquence pratique est celle qui compte : ne contrôlez pas une restauration à un changement d'identité, il ne se produira pas. Vérifiez plutôt la date de création du répertoire member en service, ou l'index Raft qui repart de zéro.

La procédure complète de restauration dépend de votre distribution :

kubeadm (production)

Certificats recommandés

En production kubeadm, utilisez les certificats healthcheck-client (pas le server.crt) :

export ETCDCTL_CACERT=/etc/kubernetes/pki/etcd/ca.crt
export ETCDCTL_CERT=/etc/kubernetes/pki/etcd/healthcheck-client.crt
export ETCDCTL_KEY=/etc/kubernetes/pki/etcd/healthcheck-client.key

systemctl stop kubelet n'arrête pas etcd, et c'est le piège central de cette procédure. Mesuré le 2026-09-15 sur un cluster kubeadm 1.37, etcd 3.7.0 : le kubelet arrêté, crictl ps --name etcd montre toujours le conteneur en CONTAINER_RUNNING, et /readyz de l'API répond ok. Le kubelet crée les Pods statiques, il ne les tient pas : arrêté, il cesse simplement de les surveiller. etcd garde donc ses descripteurs ouverts sur /var/lib/etcd, même déplacé, et continue d'y écrire. Au redémarrage, le manifeste n'ayant pas changé, le Pod n'est pas recréé et le cluster repart sur l'ancien état : la restauration n'a rien restauré, sans le moindre message d'erreur.

Ce qui détruit réellement le conteneur, c'est de retirer son manifeste du répertoire surveillé.

1. Sortir les manifestes du répertoire surveillé

   Sur chaque control plane. Le manifeste de l'API server part avec celui d'etcd, pour qu'aucune écriture n'arrive pendant l'opération :

   mkdir -p /etc/kubernetes/manifests.hold
   mv /etc/kubernetes/manifests/etcd.yaml /etc/kubernetes/manifests.hold/
   mv /etc/kubernetes/manifests/kube-apiserver.yaml /etc/kubernetes/manifests.hold/

2. Vérifier que les conteneurs ont bien disparu

   C'est le contrôle qui manque le plus souvent, et le seul qui distingue une restauration réelle d'une restauration en apparence :

   crictl ps --name etcd

   La sortie ne doit plus contenir aucune ligne de conteneur. Tant qu'elle en montre une, tout ce qui suit s'écrirait sous un etcd vivant.

3. Écarter le répertoire de données actuel

   mv /var/lib/etcd /var/lib/etcd.backup-$(date +%Y%m%d)

4. Restaurer le snapshot sur chaque membre (avec etcdutl)

   etcdutl snapshot restore /path/to/snapshot.db \
     --name etcd-member-1 \
     --initial-cluster etcd-member-1=https://10.0.0.1:2380,etcd-member-2=https://10.0.0.2:2380,etcd-member-3=https://10.0.0.3:2380 \
     --initial-cluster-token etcd-cluster-1 \
     --initial-advertise-peer-urls https://10.0.0.1:2380 \
     --data-dir /var/lib/etcd

   Répétez sur chaque nœud en adaptant --name et --initial-advertise-peer-urls. Le répertoire visé doit être neuf : restaurer par-dessus un répertoire existant mélangerait l'ancien et le nouveau contenu, d'où l'étape précédente.

5. Remettre les manifestes en place

   mv /etc/kubernetes/manifests.hold/etcd.yaml /etc/kubernetes/manifests/
   mv /etc/kubernetes/manifests.hold/kube-apiserver.yaml /etc/kubernetes/manifests/

   Le kubelet les relit en quelques secondes et recrée les Pods sur le répertoire restauré.

6. Vérifier la santé

   crictl ps --name etcd
   etcdctl --endpoints=https://127.0.0.1:2379 endpoint health --cluster

Une variante existe, et le lab cka-etcd-backup-restore l'emploie : restaurer vers un répertoire différent, puis faire pointer le hostPath du manifeste etcd.yaml vers lui. Elle évite de déplacer l'ancien répertoire et rend le retour en arrière immédiat, au prix d'une modification du manifeste. Dans les deux cas, le principe est le même : etcd doit être réellement arrêté, ce qu'aucune action sur le kubelet seul n'obtient.

kind (lab)

Pour un lab kind, le plus simple est de recréer le cluster :

kind delete cluster --name etcd-lab
kind create cluster --name etcd-lab --config kind-etcd-lab.yaml

Puis restaurer les objets Kubernetes depuis vos manifests GitOps.

Script de backup automatisé

Ce script enchaîne les trois gestes qui font une sauvegarde exploitable : créer le snapshot, vérifier son intégrité juste après, puis purger les archives au-delà de la rétention. Le set -euo pipefail en tête est indispensable, il fait échouer le script au premier problème au lieu de laisser une tâche planifiée signaler un succès sur un fichier vide. Adaptez les chemins de certificats à votre distribution, ceux indiqués sont ceux de kubeadm.

etcd-backup.sh

#!/bin/bash
set -euo pipefail

# Configuration
BACKUP_DIR="/backup/etcd"
RETENTION_DAYS=7
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
SNAPSHOT_FILE="${BACKUP_DIR}/etcd-snapshot-${TIMESTAMP}.db"

# Certificats (kubeadm - adapter selon votre distribution)
CACERT="/etc/kubernetes/pki/etcd/ca.crt"
CERT="/etc/kubernetes/pki/etcd/healthcheck-client.crt"
KEY="/etc/kubernetes/pki/etcd/healthcheck-client.key"
ENDPOINTS="https://127.0.0.1:2379"

# Créer le répertoire de backup
mkdir -p "${BACKUP_DIR}"

# Créer le snapshot
etcdctl snapshot save "${SNAPSHOT_FILE}" \
  --cacert="${CACERT}" \
  --cert="${CERT}" \
  --key="${KEY}" \
  --endpoints="${ENDPOINTS}"

# Vérifier l'intégrité (etcdutl pour compatibilité 3.5/3.6)
etcdutl snapshot status "${SNAPSHOT_FILE}" --write-out=table

# Supprimer les vieux backups
find "${BACKUP_DIR}" -name "etcd-snapshot-*.db" -mtime +${RETENTION_DAYS} -delete

echo "Backup terminé : ${SNAPSHOT_FILE}"

---

Maintenance day-2 : compaction, defrag, quota

Sans intervention, une base etcd ne fait que grossir jusqu'à heurter son quota et bloquer le cluster. Deux opérations distinctes l'en empêchent, et l'ordre compte : la compaction supprime l'historique devenu inutile, la défragmentation rend au système de fichiers l'espace ainsi libéré. Le quota est le garde-fou qui déclenche l'alarme quand ces deux gestes ont été négligés.

Compaction

La compaction supprime les anciennes révisions pour limiter la croissance de la base. Elle est irréversible : après compaction à la révision N, plus aucune lecture historique antérieure à N n'est possible, ce qui interrompt les watches encore accrochées à ces révisions. En pratique, cela ne gêne pas Kubernetes, dont les controllers se resynchronisent automatiquement.

Compaction manuelle

1. Récupérer la révision actuelle

   REV=$(etcdctl endpoint status -w json | grep -o '"revision":[0-9]*' | head -1 | cut -d: -f2)
   echo "Révision actuelle: $REV"

   Sortie attendue :

   Révision actuelle: 713

2. Compacter jusqu'à cette révision

   etcdctl compact $REV

   Sortie attendue :

   compacted revision 713

Auto-compaction

etcd peut compacter automatiquement. Configurez dans les arguments de démarrage :

# Mode périodique : compacte toutes les heures
--auto-compaction-mode=periodic
--auto-compaction-retention=1h

# Mode révision : garde les N dernières révisions
--auto-compaction-mode=revision
--auto-compaction-retention=10000

Défragmentation

La compaction marque les données comme supprimées, mais ne libère pas l'espace disque. La défragmentation récupère cet espace.

Impact performance

La défragmentation bloque les écritures pendant quelques secondes. Faites-la membre par membre, jamais sur tout le cluster en même temps.

Online (cluster running)

# Défragmenter un seul membre (etcd doit tourner)
etcdctl defrag --endpoints=https://127.0.0.1:2379

Sortie attendue :

Finished defragmenting etcd member[https://127.0.0.1:2379]. took 25.969208ms

Offline (maintenance)

Pour défragmenter un etcd arrêté (maintenance offline) :

# Arrêter etcd, puis :
etcdutl defrag --data-dir /var/lib/etcd

La variante hors ligne sert dans deux cas : récupérer beaucoup d'espace d'un coup avant de redémarrer un membre, et profiter d'une fenêtre de maintenance déjà planifiée. Sur un cluster qui tourne, préférez la forme en ligne, membre par membre.

Procédure recommandée (online) :

1. Défragmenter un follower
2. Vérifier sa santé (endpoint health)
3. Défragmenter le follower suivant
4. Défragmenter le leader en dernier

Mesurer ce que la défragmentation récupère

L'intérêt de l'opération se chiffre, et la colonne PERCENTAGE NOT IN USE le donne directement. Voici l'état de deux membres du lab après une compaction, mais avec la défragmentation exécutée sur un seul d'entre eux :

│        ENDPOINT         │ DB SIZE │ IN USE │ PERCENTAGE NOT IN USE │ IS LEADER │
│ https://172.26.0.6:2379 │  2.1 MB │ 741 kB │                   65% │     false │
│ https://172.26.0.7:2379 │  684 kB │ 684 kB │                    0% │      true │

Les deux membres contiennent exactement les mêmes données, Raft s'en charge. Le membre défragmenté occupe pourtant 684 ko contre 2,1 Mo pour l'autre, dont 65 % d'espace mort. Deux enseignements. La compaction seule ne rend rien au disque, elle marque simplement des révisions comme inutiles. Et la défragmentation agit membre par membre : un cluster où un seul membre a été traité reste déséquilibré jusqu'à ce que vous passiez sur les autres.

C'est aussi la mesure qui permet de décider. En dessous de quelques pour cent, défragmenter ne rapporte rien et coûte une interruption d'écriture. Au-delà de plusieurs dizaines, l'opération se justifie.

Quota et alarme NOSPACE

Par défaut, etcd a un quota de 2 GB. Quand il est atteint :

1. etcd déclenche l'alarme NOSPACE
2. Seules les lectures et suppressions sont autorisées
3. Le cluster Kubernetes est bloqué

Runbook de résolution :

1. Vérifier l'alarme

   etcdctl --endpoints=https://127.0.0.1:2379 alarm list

   memberID:4c95f7dc5897214a alarm:NOSPACE

2. Compacter la base

   # Récupérer la révision actuelle (parsing JSON robuste si jq disponible)
   REV=$(etcdctl --endpoints=https://127.0.0.1:2379 endpoint status --write-out=json | \
     grep -o '"revision":[0-9]*' | head -1 | cut -d: -f2)
   echo "Compaction jusqu'à la révision: $REV"
   etcdctl --endpoints=https://127.0.0.1:2379 compact $REV

3. Défragmenter tous les membres (un par un, en commençant par les followers)

   # Récupérer la liste des endpoints
   etcdctl --endpoints=https://127.0.0.1:2379 member list --write-out=table
   
   # Défragmenter chaque membre individuellement
   etcdctl defrag --endpoints=https://<IP_FOLLOWER_1>:2379
   etcdctl defrag --endpoints=https://<IP_FOLLOWER_2>:2379
   etcdctl defrag --endpoints=https://<IP_LEADER>:2379  # En dernier

4. Désarmer l'alarme

   etcdctl --endpoints=https://127.0.0.1:2379 alarm disarm

5. Vérifier que l'alarme est levée

   etcdctl --endpoints=https://127.0.0.1:2379 alarm list
   # (sortie vide = OK)

---

Sécurité : TLS d'abord, contrôle d'accès ensuite

etcd ne connaît ni namespaces, ni ServiceAccounts, ni RBAC Kubernetes : qui accède à la base accède à tout le cluster, y compris aux secrets stockés en clair si le chiffrement au repos n'est pas activé. La priorité est donc de fermer l'accès réseau et d'imposer l'authentification par certificat, avant même de parler de droits fins.

mTLS obligatoire

etcd ne doit jamais être exposé sans TLS. Toutes les communications doivent être chiffrées :

Communication	Ports	Certificats requis
Client → etcd	2379	ca.crt, server.crt, server.key
etcd → etcd (peers)	2380	peer.crt, peer.key

Glissez pour voir

Risque majeur

Un etcd exposé sans authentification permet de lire tous les secrets Kubernetes (tokens, passwords, clés API) et de prendre le contrôle total du cluster.

RBAC etcd (cas avancés)

Pour les clusters etcd externes ou partagés, vous pouvez activer l'authentification. Ce mécanisme d'utilisateurs et de rôles internes à etcd n'a aucun rapport avec le RBAC de Kubernetes : il découpe les droits par préfixe de clés, pas par ressource ou par namespace. Sur un etcd dédié à un seul cluster Kubernetes, il n'apporte rien de plus que le mTLS et complique le renouvellement des accès :

# Activer l'authentification
etcdctl auth enable

# Créer un utilisateur
etcdctl user add admin --new-user-password="***"

# Créer un rôle
etcdctl role add readwrite
etcdctl role grant-permission readwrite readwrite /

# Assigner le rôle à l'utilisateur
etcdctl user grant-role admin readwrite

---

Monitoring et alerting

Les incidents etcd sont presque toujours annoncés : la latence disque dérive, la base approche du quota, le leader change plus souvent. Surveiller les bonnes métriques transforme une panne de control plane en simple opération de maintenance planifiée. Encore faut-il alerter sur les bons signaux et avec des seuils calibrés sur votre matériel.

Métriques Prometheus

etcd expose ses métriques sur /metrics (port 2379 avec TLS). Les métriques clés à surveiller :

Ces valeurs sont des points de départ, pas des vérités. Un seuil d'alerte recopié d'un guide produit soit du bruit, soit du silence. Observez les tendances de votre propre cluster sur sept à trente jours, puis calez les seuils sur ce que vous voyez et sur l'engagement de service que vous devez tenir.

Métrique	Description	Seuil initial	Notes
etcd_server_has_leader	Présence d'un leader	!= 1	Critique, action immédiate
etcd_server_leader_changes_seen_total	Changements de leader	> 3/heure	Ajuster si réseau instable
etcd_disk_backend_commit_duration_seconds	Latence d'écriture disque	p99 > 25ms	Sur SSD NVMe, attendez < 10ms
etcd_network_peer_round_trip_time_seconds	Latence réseau entre peers	p99 > 50ms	Dépend de la distance entre nœuds
etcd_mvcc_db_total_size_in_bytes	Taille de la base	> 80% du quota	Warning à 80%, critique à 95%
etcd_server_proposals_failed_total	Propositions Raft échouées	> 0	Tout échec = investigation

Glissez pour voir

Exemple de PrometheusRule

Ces trois alertes couvrent les urgences réelles : absence de leader, disque trop lent, quota bientôt atteint. Le champ for évite les faux positifs en exigeant que la condition dure, et il est volontairement court sur l'absence de leader, qui ne doit jamais persister au-delà d'une minute. L'objet PrometheusRule suppose l'opérateur Prometheus installé.

etcd-alerts.yaml

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: etcd-alerts
  namespace: monitoring
spec:
  groups:
  - name: etcd
    rules:
    - alert: EtcdNoLeader
      expr: etcd_server_has_leader == 0
      for: 1m
      labels:
        severity: critical
      annotations:
        summary: "etcd n'a pas de leader"

    - alert: EtcdHighDiskLatency
      expr: histogram_quantile(0.99, rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) > 0.025
      for: 5m
      labels:
        severity: warning
      annotations:
        summary: "Latence disque etcd élevée (> 25ms)"

    - alert: EtcdDatabaseSpaceExceeded
      expr: etcd_mvcc_db_total_size_in_bytes / etcd_server_quota_backend_bytes > 0.8
      for: 5m
      labels:
        severity: warning
      annotations:
        summary: "Base etcd proche du quota (> 80%)"

---

Cheat sheet etcdctl

Ce récapitulatif rassemble les commandes du guide sous une forme copiable. Les variables ETCDCTL_CACERT, ETCDCTL_CERT et ETCDCTL_KEY remplacent les options --cacert, --cert et --key : les exporter une fois raccourcit toutes les commandes suivantes.

Ces commandes s'exécutent sur le nœud, avec un etcdctl installé sur la machine, et non dans le conteneur distroless. Dans ce contexte, les variables d'environnement redeviennent utilisables et évitent de répéter les chemins :

export ETCDCTL_CACERT=/etc/kubernetes/pki/etcd/ca.crt
export ETCDCTL_CERT=/etc/kubernetes/pki/etcd/healthcheck-client.crt
export ETCDCTL_KEY=/etc/kubernetes/pki/etcd/healthcheck-client.key

Santé et statut

Ces quatre commandes ne modifient rien et sont sûres en production. L'option --cluster élargit la question à tous les membres à partir d'un seul endpoint joignable.

# Santé d'un endpoint
etcdctl --endpoints=https://127.0.0.1:2379 endpoint health

# Santé de tout le cluster
etcdctl --endpoints=https://127.0.0.1:2379 endpoint health --cluster

# Statut détaillé (leader, taille, index)
etcdctl --endpoints=https://127.0.0.1:2379 endpoint status --cluster --write-out=table

# Liste des membres
etcdctl --endpoints=https://127.0.0.1:2379 member list --write-out=table

Sauvegarde et restauration

Notez la répartition des rôles : etcdctl parle au serveur pour créer le snapshot, etcdutl travaille hors ligne sur le fichier et le répertoire de données. La restauration exige un etcd arrêté et un répertoire cible inexistant.

# Créer un snapshot
etcdctl --endpoints=https://127.0.0.1:2379 snapshot save /path/to/snapshot.db

# Vérifier un snapshot (etcdutl, compatible 3.5/3.6)
etcdutl snapshot status /path/to/snapshot.db --write-out=table

# Restaurer (etcdutl, compatible 3.5/3.6)
etcdutl snapshot restore /path/to/snapshot.db --data-dir /var/lib/etcd

Maintenance

La défragmentation vise un endpoint précis, jamais le cluster entier : c'est la seule commande de cette page qu'il faut lancer membre par membre, en terminant par le leader.

# Compacter jusqu'à la révision N
etcdctl --endpoints=https://127.0.0.1:2379 compact <revision>

# Défragmenter un membre (online)
etcdctl defrag --endpoints=https://<IP>:2379

# Défragmenter offline (etcd arrêté)
etcdutl defrag --data-dir /var/lib/etcd

# Lister les alarmes
etcdctl --endpoints=https://127.0.0.1:2379 alarm list

# Désarmer les alarmes
etcdctl --endpoints=https://127.0.0.1:2379 alarm disarm

Données (debug uniquement)

Lire directement les clés d'etcd court-circuite l'API server, donc tous les contrôles d'accès et d'audit de Kubernetes ; les valeurs sont sérialisées en protobuf et peu lisibles. Réservez ces commandes au diagnostic, sur un cluster de test, et n'écrivez jamais dans etcd à la main.

# Lister toutes les clés (ATTENTION : beaucoup de sortie)
etcdctl --endpoints=https://127.0.0.1:2379 get "" --prefix --keys-only | head -20

# Lire une clé spécifique
etcdctl --endpoints=https://127.0.0.1:2379 get /registry/pods/default/my-pod

# Compter les clés
etcdctl --endpoints=https://127.0.0.1:2379 get "" --prefix --keys-only | wc -l

---

Runbooks "symptôme → diagnostic → action"

Ces quatre procédures se suivent en incident, sans réflexion préalable. Chacune part d'un symptôme observable, confirme l'hypothèse par une commande, puis applique la correction dans un ordre qui ne dégrade pas la situation. Gardez-les accessibles hors du cluster : un control plane indisponible rend souvent la documentation interne inaccessible avec lui.

Les commandes de cette section supposent un etcdctl installé sur le nœud et les certificats déjà configurés, comme indiqué juste au-dessus.

Alarme NOSPACE

Le cluster n'accepte plus aucune écriture tant que l'alarme est armée, et elle ne se lève pas toute seule : le désarmement de l'étape 4 est obligatoire, même après avoir libéré de l'espace.

1. etcdctl --endpoints=https://127.0.0.1:2379 alarm list → confirme NOSPACE
2. Compacter : etcdctl --endpoints=https://127.0.0.1:2379 compact $(etcdctl --endpoints=https://127.0.0.1:2379 endpoint status --write-out=json | grep -o '"revision":[0-9]*' | head -1 | cut -d: -f2)
3. etcdctl defrag --endpoints=https://<IP>:2379 (membre par membre, followers d'abord)
4. Désarmer : etcdctl --endpoints=https://127.0.0.1:2379 alarm disarm
5. Vérifier : etcdctl --endpoints=https://127.0.0.1:2379 endpoint status --cluster --write-out=table (DB SIZE réduit)

Perte de quorum

Sous le quorum, etcd refuse toute écriture : le cluster ne peut plus changer d'état, et l'API peut devenir franchement indisponible, sans mode « lecture seule » sur lequel compter (mesuré dans la leçon sur le plan de contrôle haute disponibilité). La bascule est brutale : sur trois membres, la perte du deuxième fait passer d'un cluster dégradé mais fonctionnel à un cluster inutilisable.

1. Identifier les membres down : etcdctl --endpoints=https://127.0.0.1:2379 member list --write-out=table
2. Si 1 seul membre down sur 3 : attendre son retour ou le remplacer
3. Si 2+ membres down : le quorum est perdu. Tentez d'abord de les relancer (machine, disque, réseau) : si leurs données sont intactes, ils rejoignent le cluster et le quorum revient, sans restauration. Si leurs données sont perdues, la restauration depuis snapshot avec etcdutl snapshot restore devient la seule issue

etcd lent (I/O)

Toute écriture etcd attend une écriture disque synchronisée sur la majorité des membres : la latence du stockage se répercute donc directement sur celle de l'API server. Ce runbook sert à distinguer un problème de disque d'un problème de réseau.

1. etcdctl --endpoints=https://127.0.0.1:2379 endpoint status --cluster --write-out=table → vérifier latence
2. Logs : kubectl logs -n kube-system etcd-xxx | grep "slow\|took too long"
3. Vérifier les IOPS du disque : iostat -x 1
4. Vérifier la latence réseau : ping <IP_PEER>, qui doit rester sous 10 ms
5. Corriger : migrer vers un SSD NVMe, améliorer le réseau

Certificats expirés

Les certificats etcd générés par kubeadm ont une validité d'un an. Sur un cluster jamais mis à jour, ils expirent en silence et le control plane tombe d'un coup, sans le moindre changement de configuration apparent.

Symptômes : transport: authentication handshake failed

1. Vérifier l'expiration : openssl x509 -in /etc/kubernetes/pki/etcd/server.crt -noout -dates
2. Renouveler avec kubeadm : kubeadm certs renew etcd-server && kubeadm certs renew etcd-peer
3. Redémarrer les Pods etcd : kubectl delete pod -n kube-system -l component=etcd

---

Checklist avant production

Ces huit points sont ceux dont l'absence transforme un incident ordinaire en perte de cluster. Les deux premiers priment sur tous les autres : sans sauvegarde restaurée au moins une fois et sans alerte sur la présence d'un leader, le reste ne vous sauvera pas.

• Backups automatisés et testés (restauration réussie)
• Monitoring : alertes sur leader, latence, espace disque
• SSD : stockage avec latence < 10ms
• Réseau : latence < 10ms entre membres etcd
• TLS : mTLS activé pour clients et peers
• Quota : configuré et surveillé
• Maintenance : compaction auto + defrag planifié
• Documentation : runbooks accessibles à l'équipe

---

Tester vos connaissances

Ce quiz reprend les questions etcd du programme de la certification CKA, où la sauvegarde et la restauration d'etcd sont un exercice classique. Un score inférieur à 80 % signale les sections à relire.

À retenir

1. etcd = SPOF logique : même avec 3 nœuds, une mauvaise config bloque le cluster
2. Toujours 3 ou 5 membres : jamais 2, jamais plus de 7
3. SSD obligatoire : la latence disque tue etcd
4. Backup = snapshot + test de restauration : un backup non testé ne vaut rien
5. Compaction + defrag : maintenance obligatoire pour éviter NOSPACE
6. TLS everywhere : etcd exposé = cluster compromis

---

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

7 questions

5 min.

80% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Mettre en pratique

Une restauration etcd ne se répète pas sur un cluster en conteneurs : il faut un control plane réel, que ce lab fournit en machine virtuelle. Vous prenez une sauvegarde fraîche, restaurez depuis l'instantané de la veille, et la validation vérifie qu'etcd tourne sur un répertoire produit pendant le lab, que les objets reviennent avec leur UID d'origine, et que ce qui a été écrit après la sauvegarde a disparu.

Lab guidé Pratique

Apprendre à faire

Sauvegarder etcd, puis restaurer le cluster depuis un instantané

$ dsoxlab run cka-etcd-backup-restore

Environnement : VM·Durée : ~25 min

Vérification : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que DSOXLab et comment l'installer

DSOXLab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Il faut Python 3.11 ou plus récent, uv ou pipx, et git. Le guide d'installation détaille ces prérequis ; sous Windows, ou sur un Mac sans Python, passez plutôt par l'appliance.

Ce lab démarre des machines virtuelles : il demande en plus ansible-playbook, un hyperviseur (KVM ou Incus), Terraform et la virtualisation matérielle (/dev/kvm), c'est-à-dire, dans une VM VirtualBox, la virtualisation imbriquée. La première fois, dsoxlab start cka-etcd-backup-restore vérifie tout cela avant de créer les machines. Préparer le poste pour les labs vm.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/kubernetes-dsoxlab-training

Avant de lancer le lab, vérifiez :

• DSOXLab installé
• catalogue disponible
• environnement compatible (shell isolé ou VM)

Pour le vérifier, rien n'est sondé depuis cette page : lancez dsoxlab doctor. Lire le diagnostic

Lancer ce lab, puis valider votre travail :

dsoxlab run cka-etcd-backup-restore
dsoxlab check cka-etcd-backup-restore

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille le calcul du score et les pièges.

Ressources

Ces quatre références font autorité sur les points que ce guide résume. La documentation Kubernetes couvre l'intégration au control plane, celle du projet etcd détaille la maintenance, la restauration et la supervision.

• Operating etcd clusters for Kubernetes, Documentation officielle Kubernetes
• etcd Maintenance, Compaction, defrag, quotas
• etcd Disaster Recovery, Procédures de restauration
• etcd Monitoring, Métriques et alerting

×

📖 Voir la documentation →