En corto

En un solo servidor, el que tenga los datos más recientes:

1
2
3
4
5

systemctl stop k3s
k3s server --cluster-reset
# ... termina con:
# Managed etcd cluster membership has been reset, restart without --cluster-reset flag now
systemctl start k3s

En cada uno de los otros servidores, con su /etc/rancher/k3s/config.yaml apuntando al que reseteaste (server: https://node1:6443):

1
2
3

systemctl stop k3s
rm -rf /var/lib/rancher/k3s/server/db
systemctl start k3s

Los agentes no necesitan nada; se reconectan solos.

Cuándo hace falta

etcd necesita mayoría: con tres servidores, dos vivos; con cinco, tres. Si pierdes la mayoría (dos nodos muertos, una partición de red, un cambio de IPs a la vez, un intento de quitar nodos a mano), el que queda no puede escribir y la API se congela:

1
2

kubectl get nodes
Error from server: etcdserver: request timed out

En journalctl -u k3s verás etcd cluster join failed, failed to get raft status o waiting for etcd quorum. --cluster-reset es la salida que documenta k3s para exactamente esto.

Qué hace --cluster-reset

Reescribe la lista de miembros de etcd para que el nodo actual sea el único, conservando todos sus datos (los objetos de Kubernetes, secretos, todo). No toca los pods ni los agentes. Lo único que se pierde son escrituras que no alcanzaron a replicarse a este nodo antes de la caída, que en la práctica son pocas o ninguna si eliges el que estaba más al día.

Con --cluster-reset-restore-path hace lo mismo pero sustituye los datos por los de un snapshot; todo lo posterior al snapshot desaparece.

Paso a paso

  1. Elige el nodo. Si varios servidores siguen vivos pero sin quórum, quédate con el que tenga el snapshot o el db más reciente: ls -la /var/lib/rancher/k3s/server/db/ y k3s etcd-snapshot ls.

  2. Guarda una copia por si acaso, incluido el token:

    1
2

    cp -a /var/lib/rancher/k3s/server/db /root/k3s-db-$(date +%F)
cp /var/lib/rancher/k3s/server/token /root/k3s-token

  3. Resetea y arranca (el bloque del En corto). El comando tarda unos segundos; no lo interrumpas.

  4. Comprueba que la API responde y que el nodo es el único miembro de etcd:

    1
2

    kubectl get nodes -o wide
kubectl get nodes -l node-role.kubernetes.io/etcd=true

    Los otros servidores saldrán NotReady hasta que se unan; los agentes vuelven a Ready solos.

  5. Revisa la configuración de los demás servidores antes de arrancarlos. El primer nodo del clúster suele tener cluster-init: true y ningún server:; si reseteaste otro nodo, ese primero arrancaría un clúster nuevo por su cuenta. Asegúrate de que todos los que se van a unir tienen:

    1
2
3

    # /etc/rancher/k3s/config.yaml
server: https://node1:6443     # el nodo reseteado (o el VIP, si apunta a él)
token: <el mismo token>

  6. Únelos uno a uno: stop, borrar server/db, start. Cada uno entra como learner y tarda uno o dos minutos en ser miembro pleno; espera a que aparezca Ready antes del siguiente.

  7. Snapshot nuevo cuando todo esté verde: k3s etcd-snapshot save --name post-reset.

Restaurar desde un snapshot

Si el db del superviviente está corrupto o quieres volver a un punto anterior:

1
2
3
4

k3s etcd-snapshot ls
systemctl stop k3s
k3s server --cluster-reset --cluster-reset-restore-path=/var/lib/rancher/k3s/server/db/snapshots/etcd-snapshot-node1-1758760000
systemctl start k3s

Y después, el mismo rejoin de los demás servidores. Por defecto k3s guarda un snapshot cada 12 horas (0 */12 * * *) y conserva 5, en /var/lib/rancher/k3s/server/db/snapshots; --etcd-s3 los manda a S3.

Trampas

  • Nunca en dos nodos. --cluster-reset en dos servidores da dos clústeres con el mismo nombre y agentes confundidos entre ambos. Uno resetea, el resto se une.
  • El token manda. El snapshot lleva los certificados y las llaves de cifrado protegidos con el token del clúster. Restaurar en un nodo nuevo sin el mismo token (--token) no arranca. Guarda /var/lib/rancher/k3s/server/token fuera del clúster.
  • SQLite no tiene esto. Un servidor único sin etcd no necesita ni acepta --cluster-reset; su backup es copiar /var/lib/rancher/k3s/server/db/.
  • cluster-init huérfano en un nodo que se va a reunir es la forma más fácil de acabar con dos clústeres. Revisa el punto 5.
  • Balanceador o VIP delante de los servidores: si apunta a un nodo muerto, los agentes tampoco vuelven; revísalo antes de culpar a etcd.

Referencia: etcd-snapshot y Backup and Restore en la documentación de k3s.