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

Public cible

Ce guide s'adresse aux administrateurs Kubernetes et SRE qui gèrent des clusters en production ou préparent la certification CKA/CKS. Les concepts s'appliquent à kubeadm, k3s, RKE, et tout cluster utilisant etcd.

Compatibilité etcd 3.5 vs 3.6

etcd 3.6 (sorti fin 2024) introduit des changements importants :

• etcdctl snapshot status et etcdctl snapshot restore → supprimés, utilisez etcdutl
• etcdctl defrag reste disponible (online), mais etcdutl defrag --data-dir pour l'offline
• Toujours exporter ETCDCTL_API=3 (même si c'est le défaut depuis 3.4)

Ce guide utilise les commandes compatibles 3.5 et 3.6.

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.

SPOF logique

Même avec 3 nœuds etcd, une mauvaise configuration (disque lent, réseau instable, quota atteint) peut rendre le cluster inutilisable. etcd exige des SSD et un réseau stable (<10ms de latence 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 :

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

Pourquoi 3 ou 5 membres ?

• 3 membres : standard pour la plupart des clusters (tolère 1 panne)
• 5 membres : clusters critiques (tolère 2 pannes)
• Plus de 5 : rarement utile, la latence d'écriture augmente

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, k3s, RKE2 et la plupart des distributions. 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.

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.

Objectif

Apprendre les gestes etcd sans risquer un cluster de production. Les chemins des certificats diffèrent selon la distribution (kubeadm, k3s, etc.) mais les commandes etcdctl restent identiques.

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.31.2) 🖼
    ✓ 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"

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          46s   172.19.0.5   etcd-lab-control-plane
   etcd-etcd-lab-control-plane2   1/1     Running   0          40s   172.19.0.4   etcd-lab-control-plane2
   etcd-etcd-lab-control-plane3   1/1     Running   0          33s   172.19.0.3   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 -- sh -c '
  export ETCDCTL_API=3
  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>
'

Pourquoi ce pattern ?

• ETCDCTL_API=3 : garantit l'API v3 (obligatoire, même si c'est le défaut depuis 3.4)
• --endpoints=https://127.0.0.1:2379 : plus robuste que les IPs des nœuds (évite les problèmes d'adressage Docker/kind)
• sh -c '...' : permet d'exporter la variable d'environnement

Alias pratique (shell local)

Pour éviter de répéter les options, créez une fonction :

etcdctl-lab() {
  kubectl exec -n kube-system etcd-etcd-lab-control-plane -- sh -c "
    export ETCDCTL_API=3
    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 \
      $*
  "
}

Puis utilisez simplement : etcdctl-lab endpoint health

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 l'état interne de chacun, member list donne la composition déclarée du cluster. Un membre peut figurer dans member list tout en étant injoignable, c'est justement l'écart entre ces deux vues qui révèle une 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 -- sh -c '
  export ETCDCTL_API=3
  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 = 3.837182ms

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 -- sh -c '
  export ETCDCTL_API=3
  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 :

+-------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
|        ENDPOINT         |        ID        | VERSION | DB SIZE | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS |
+-------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
| https://172.19.0.5:2379 | 4c95f7dc5897214a |  3.5.15 |  1.6 MB |      true |      false |         2 |        812 |                812 |        |
| https://172.19.0.4:2379 | 66fb782b14ae096a |  3.5.15 |  1.6 MB |     false |      false |         2 |        812 |                812 |        |
| https://172.19.0.3:2379 | ee098f6d097e6ce5 |  3.5.15 |  1.6 MB |     false |      false |         2 |        812 |                812 |        |
+-------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+

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 de la base	Similaire sur tous les membres
RAFT INDEX	Index de réplication	Identique sur tous les membres
ERRORS	Alarmes actives	Vide

Glissez pour voir

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 -- sh -c '
  export ETCDCTL_API=3
  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 |
+------------------+---------+-------------------------+-------------------------+-------------------------+------------+
| 4c95f7dc5897214a | started |  etcd-lab-control-plane | https://172.19.0.5:2380 | https://172.19.0.5:2379 |      false |
| 66fb782b14ae096a | started | etcd-lab-control-plane2 | https://172.19.0.4:2380 | https://172.19.0.4:2379 |      false |
| ee098f6d097e6ce5 | started | etcd-lab-control-plane3 | https://172.19.0.3:2380 | https://172.19.0.3:2379 |      false |
+------------------+---------+-------------------------+-------------------------+-------------------------+------------+

---

Santé et diagnostic : les checks qui sauvent

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

Check baseline (2 minutes)

Voici la séquence de diagnostic à exécuter en cas de problème. Toujours exporter ETCDCTL_API=3 avant d'exécuter ces commandes.

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

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

   ✅ Tous les endpoints doivent être healthy

2. Identifier le leader

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

   ✅ Un seul membre doit avoir 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

   ✅ La sortie doit être vide (aucune alarme)

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

Les symptômes remontés par les utilisateurs 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 elles se distinguent par la commande de diagnostic associée. 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 brièvement les écritures : quelques changements de leader par heure suffisent à rendre l'API server erratique. Le compteur ci-dessous n'est significatif 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

   ⚠️ 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>

   ⚠️ > 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 logs etcd sont volumineux et majoritairement sans intérêt en exploitation courante. Quatre motifs concentrent l'information utile, 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 -- sh -c '
     export ETCDCTL_API=3
     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 /tmp/etcd-snapshot.db
   '

   Sortie attendue :

   {"level":"info","ts":"2026-02-02T09:24:53.263527Z","caller":"snapshot/v3_snapshot.go:97","msg":"saved","path":"/tmp/etcd-snapshot.db"}
   Snapshot saved at /tmp/etcd-snapshot.db

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 /tmp/etcd-snapshot.db --write-out=table

   Sortie attendue :

   +----------+----------+------------+------------+
   |   HASH   | REVISION | TOTAL KEYS | TOTAL SIZE |
   +----------+----------+------------+------------+
   | 8213414f |      822 |        835 |     1.7 MB |
   +----------+----------+------------+------------+

   etcdctl vs etcdutl

   etcdctl snapshot status est déprécié en 3.5 et supprimé en 3.6. Utilisez toujours etcdutl pour les opérations snapshot.

3. Copier le snapshot hors du conteneur

   kubectl cp kube-system/etcd-etcd-lab-control-plane:/tmp/etcd-snapshot.db ./etcd-snapshot-$(date +%Y%m%d-%H%M%S).db

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 une identité différente. 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

La restauration réécrit l'identité du cluster (member ID, cluster ID). C'est normal et attendu. Tous les membres doivent être restaurés avec le même snapshot.

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_API=3
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

1. Arrêter le kubelet sur tous les control planes

   systemctl stop kubelet

2. Sauvegarder le répertoire etcd actuel

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

3. 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.

4. Redémarrer le kubelet

   systemctl start kubelet

5. Vérifier la santé

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

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
export ETCDCTL_API=3
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: 911

2. Compacter jusqu'à cette révision

   etcdctl compact $REV

   Sortie attendue :

   compacted revision 911

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]

Offline (maintenance)

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

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

Quand utiliser offline ?

L'offline defrag est utile pour récupérer beaucoup d'espace avant de redémarrer un membre, ou lors d'une maintenance planifiée.

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

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 :

Seuils de départ

Ces seuils sont des valeurs initiales à ajuster selon votre SLO. Surveillez les tendances sur 7-30 jours avant de finaliser vos alertes.

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 ; 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é et le namespace monitoring existant.

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 d'environnement ETCDCTL_CACERT, ETCDCTL_CERT et ETCDCTL_KEY remplacent les options --cacert, --cert et --key : les exporter une fois raccourcit toutes les commandes suivantes.

Prérequis

Toujours exporter ETCDCTL_API=3 et les certificats avant d'utiliser ces commandes :

export ETCDCTL_API=3
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 sur 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 sont conçues pour être suivies 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 peut aussi rendre votre documentation interne inaccessible.

Convention

Toutes les commandes supposent ETCDCTL_API=3 exporté et les certificats configurés.

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. 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 et le cluster Kubernetes se fige en lecture seule. 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 : restauration depuis snapshot obligatoire avec etcdutl snapshot restore

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 IOPS du disque : iostat -x 1
4. Vérifier latence réseau : ping <IP_PEER> (doit être < 10ms)
5. Solution : migrer vers SSD NVMe, améliorer réseau

Certificats expirés

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

Symptômes : transport: authentication handshake failed

1. Vérifier 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 à 70 % signale les sections à relire.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

10 questions

8 min.

70% 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

À 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

---

Pour aller plus loin

• Haute disponibilité du control plane : Le dimensionnement du quorum etcd sur trois ou cinq membres.
• Backup et Restore : La procédure de snapshot et de restauration qui protège ces données.
• Troubleshooting cluster : Le diagnostic d'un control plane qui ne répond plus, etcd compris.

---

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 les opérations de maintenance, de restauration et de 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 →