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

• Vérifier la santé d'un cluster etcd en 2 minutes
• Créer et restaurer des snapshots (procédure complète)
• Gérer les alarmes NOSPACE et la maintenance day-2
• Monitorer etcd avec Prometheus

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.

Ce que tu vas apprendre

À la fin de ce guide, tu sauras :

• Expliquer ce que Kubernetes attend d'etcd (cohérence, latence, sécurité)
• Diagnostiquer rapidement un etcd lent/instable (health, status, quorum, disque)
• Mettre en place une stratégie backup/restore fiable (et testée)
• Faire la maintenance day-2 : compaction, defrag, quota, alarmes NOSPACE
• Surveiller etcd via métriques (Prometheus) et interpréter les signaux

---

Pourquoi etcd est critique dans Kubernetes

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

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 :

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   LEADER    │────▶│  FOLLOWER   │────▶│  FOLLOWER   │
│  (écritures)│     │  (réplique) │     │  (réplique) │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       └───────────────────┴───────────────────┘
                    QUORUM = 2/3

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

etcd "stacked" (sur les control planes)

C'est la topologie par défaut avec kubeadm, k3s, RKE2 et la plupart des distributions.

┌───────────────────────────────────────────────────────────┐
│                    Control Plane Node 1                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │ API Server  │  │ Controller  │  │  Scheduler  │       │
│  └──────┬──────┘  └─────────────┘  └─────────────┘       │
│         │                                                 │
│         ▼                                                 │
│  ┌─────────────┐                                          │
│  │    etcd     │◀───────────────────────────────────────┐ │
│  └─────────────┘                                        │ │
└─────────────────────────────────────────────────────────┼─┘
                                                          │
┌─────────────────────────────────────────────────────────┼─┐
│                    Control Plane Node 2                 │ │
│  ┌─────────────┐                                        │ │
│  │    etcd     │◀───────────────────────────────────────┼─┤
│  └─────────────┘                                        │ │
└─────────────────────────────────────────────────────────┼─┘
                                                          │
┌─────────────────────────────────────────────────────────┼─┐
│                    Control Plane Node 3                 │ │
│  ┌─────────────┐                                        │ │
│  │    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

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

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é

Vérifier la santé d'un endpoint

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

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

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

API server lent ou timeouts

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)

# 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

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

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

É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

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

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é

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

Compaction

La compaction supprime les anciennes révisions pour limiter la croissance de la base.

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

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 :

# 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

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

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

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

# 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

# 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

# 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)

# 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"

Convention

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

Alarme NOSPACE

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

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)

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

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

• 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

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

---

Prochaines étapes

Kubectl : les commandes essentielles Maîtriser l'outil CLI principal de Kubernetes

Prometheus : monitoring Kubernetes Collecter et alerter sur les métriques etcd

Sécurité Kubernetes Durcir votre cluster au-delà d'etcd

---

Ressources

• 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 →