Etcdctl

De wiki.nexiat.fr
Aller à la navigation Aller à la recherche
Fiche express
Type Client CLI d'etcd (magasin clé/valeur du control plane Kubernetes)
Rôle Inspection, sauvegarde et restauration de l'état du cluster
API v3 (par défaut depuis etcd ≥ 3.4, à vérifier selon version)
Voir aussi Kubernetes HA · Kubernetes rancher · Kubernetes troubleshooting

etcdctl est l'outil en ligne de commande officiel d'etcd, le magasin clé/valeur distribué (algorithme de consensus Raft) sur lequel repose l'ensemble de l'état d'un cluster Kubernetes. Tous les objets créés via l'API server — pods, services, secrets, configmaps... — sont in fine sérialisés et stockés dans etcd, qui reste la seule source de vérité du cluster. La disponibilité et l'intégrité d'etcd conditionnent donc directement celles du cluster entier, ce qui fait de sa sauvegarde une priorité opérationnelle.

Connexion et authentification

etcd expose son API sur le port 2379 (client) et communique en TLS mutuel dans une installation Kubernetes standard : etcdctl a donc besoin, en plus de l'adresse du ou des membres du cluster, du certificat d'autorité et d'un couple certificat/clé client. 

export ETCDCTL_API=3   # inutile sur les versions récentes où v3 est la seule API (à vérifier)

etcdctl get <clé> \
  --endpoints=https://<endpoint-etcd>:2379 \
  --cacert=/etc/etcd/pki/ca.pem \
  --cert=/etc/etcd/pki/server.crt \
  --key=/etc/etcd/pki/server.key

Sur un cluster kubeadm, ces certificats se trouvent généralement sous /etc/kubernetes/pki/etcd/ ; sur une distribution comme RKE2, l'emplacement diffère (voir Kubernetes rancher).

Sauvegarde (snapshot)

La sauvegarde d'etcd se fait via un snapshot cohérent de l'ensemble des données, pris à un instant T : 

etcdctl snapshot save /backup/etcd-$(date +%F).db \
  --endpoints=https://<endpoint-etcd>:2379 \
  --cacert=/etc/etcd/pki/ca.pem \
  --cert=/etc/etcd/pki/server.crt \
  --key=/etc/etcd/pki/server.key

Ce snapshot doit être pris régulièrement (via une tâche planifiée) et stocké hors du nœud lui-même : en cas de perte totale du cluster, c'est le seul moyen de reconstruire l'état de tous les objets Kubernetes sans tout redéployer manuellement.

Restauration

La restauration ne modifie pas un cluster etcd en place : elle reconstruit un nouveau répertoire de données à partir du snapshot, que l'on substitue ensuite à l'ancien. 

# 1. Arrêter etcd
sudo systemctl stop etcd

# 2. (Cluster à un seul membre) repartir d'un répertoire de données vide
sudo rm -rf /var/lib/etcd

# 3. Restaurer le snapshot dans un nouveau data-dir
sudo etcdctl snapshot restore /backup/etcd-<date>.db \
  --name etcd-restore \
  --initial-cluster etcd-restore=https://<endpoint-etcd>:2380 \
  --initial-advertise-peer-urls https://<endpoint-etcd>:2380 \
  --data-dir /var/lib/etcd

# 4. Corriger les droits, puis redémarrer
sudo chown -R etcd:etcd /var/lib/etcd
sudo systemctl start etcd

# 5. Vérifier qu'une clé connue est bien de retour
etcdctl get <clé> --endpoints=https://<endpoint-etcd>:2379 ...

Sur un cluster à plusieurs membres (voir Kubernetes HA), la procédure est plus délicate : la restauration doit être coordonnée sur chaque membre avec un nom et une liste initial-cluster cohérents, généralement en s'appuyant sur les procédures spécifiques à la distribution utilisée (kubeadm, RKE2...) plutôt que sur etcdctl brut.

Inspection courante

# Lister les membres du cluster etcd
etcdctl member list --endpoints=https://<endpoint-etcd>:2379 ...

# Vérifier l'état de santé
etcdctl endpoint health --endpoints=https://<endpoint-etcd>:2379 ...

# Lire une clé (les objets Kubernetes sont stockés sous /registry/...)
etcdctl get /registry/ --prefix --keys-only ... | head

Attention : écrire ou supprimer directement une clé sous /registry/ avec etcdctl contourne l'API server (pas de validation, pas de webhooks, pas de mise à jour des resourceVersion attendues côté clients). À réserver au dépannage encadré ; toute opération applicative normale doit passer par kubectl.

Voir aussi

Récupérée de "https://wiki.nexiat.fr/index.php?title=Etcdctl&oldid=2625"