5.1.5.1. Чек-лист диагностики etcd

Перед началом диагностики убедитесь, что переменная ETCDCTL_API=3 установлена и доступны TLS-сертификаты для подключения к кластеру.

Предварительные проверки

Здоровье кластера

etcdctl endpoint health \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/healthcheck-client.crt \
  --key=/etc/kubernetes/pki/etcd/healthcheck-client.key

Список участников кластера

etcdctl member list \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/healthcheck-client.crt \
  --key=/etc/kubernetes/pki/etcd/healthcheck-client.key \
  -w table

Статус эндпоинтов

etcdctl endpoint status \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/healthcheck-client.crt \
  --key=/etc/kubernetes/pki/etcd/healthcheck-client.key \
  -w table

Использование диска

etcdctl endpoint status \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/healthcheck-client.crt \
  --key=/etc/kubernetes/pki/etcd/healthcheck-client.key \
  -w json | python3 -m json.tool | grep dbSize

Проверка алармов

etcdctl alarm list \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/healthcheck-client.crt \
  --key=/etc/kubernetes/pki/etcd/healthcheck-client.key

---

Типовые ошибки

connection refused

Симптом	dial tcp 127.0.0.1:2379: connect: connection refused
Причина	Процесс etcd не запущен или слушает на другом адресе/порту.
Решение	Проверьте статус пода/сервиса etcd: crictl ps | grep etcd. Проверьте логи: crictl logs <container-id>. Убедитесь, что --listen-client-urls содержит нужный адрес.

certificate expired

Симптом	certificate has expired or is not yet valid
Причина	Срок действия TLS-сертификата etcd истек.
Решение	Проверьте срок: openssl x509 -in /etc/kubernetes/pki/etcd/server.crt -noout -dates. Перевыпустите сертификаты и перезапустите etcd.

quorum lost

Симптом	etcdserver: request timed out или rafthttp: failed to reach the peer
Причина	Более половины участников кластера недоступны — кворум потерян.
Решение	Восстановите доступность узлов. Если узел не восстанавливается — удалите его из кластера (etcdctl member remove) и добавьте заново. В критическом случае восстановите кластер из snapshot: etcdctl snapshot restore.

database size exceeded

Симптом	mvcc: database space exceeded
Причина	Размер базы данных etcd превысил квоту (по умолчанию 2 GB).
Решение	1. Выполните компактацию: etcdctl compact $(etcdctl endpoint status -w json | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['Status']['header']['revision'])"). 2. Запустите дефрагментацию: etcdctl defrag. 3. Снимите аларм: etcdctl alarm disarm. 4. Рассмотрите увеличение квоты через --quota-backend-bytes.

too many learner members in cluster

Симптом	etcdserver: too many learner members in cluster
Причина	В кластере etcd уже присутствует один или несколько узлов в состоянии learner. При добавлении нового control-plane kubeadm сначала добавляет etcd-узел как learner. etcd допускает ограниченное количество learner-узлов (обычно один), поэтому добавление нового узла завершается ошибкой.
Решение	Проверьте список участников кластера: etcdctl member list. Если обнаружен зависший learner, удалите его: etcdctl member remove <member-id>. После этого повторите процедуру kubeadm join. Если узел должен был стать voter, попробуйте выполнить etcdctl member promote <member-id>.

rpc not supported for learner

Симптом	rpc error: code = Unavailable desc = etcdserver: rpc not supported for learner
Причина	Узел etcd находится в состоянии learner и еще не синхронизирован с кластером. Некоторые операции недоступны для learner-узлов до их продвижения в voter.
Решение	Проверьте состояние узла: etcdctl member list. Убедитесь, что узел синхронизирован. После завершения репликации выполните etcdctl member promote <member-id> или повторите процедуру kubeadm join, чтобы kubeadm автоматически завершил процесс продвижения узла.