Kubernetes ETCD Quorum Kaybı: Triage ve Kurtarma Runbook'u

Kubernetes’te API server “önde” görünür; ama kontrol düzleminin kalbi ETCD’dir. Quorum kaybında cluster “tamamen durmamış gibi” davranabilir: node’lar çalışır, pod’lar akar… ama yeni deploy olmaz, ölçekleme çalışmaz, admission/CRD işlemleri patlar.

Bu yazı; ETCD quorum kaybında panik yerine disiplin için hazırlanmış bir runbook’tur.

1) Semptomlar: ETCD şüphesi ne zaman güçlenir?

• kubectl timeout / Unable to connect to the server
• API 5xx dalgası (özellikle etcdserver: request timed out)
• Scheduler/controller-manager davranışında düzensizlik
• Control plane node’larında disk latency artışı

2) İlk 10 dakika: hasarı sınırlama

1. Değişiklikleri durdur: otomasyon (GitOps/CI) varsa “pause”.
2. Control plane node’larında kaynak durumunu kontrol et: disk doluluğu, IOPS, CPU steal.
3. ETCD member’ların gerçekten ayakta olup olmadığını anla (log + endpoint health).

3) Triage: ETCD sağlık kontrolü (örnek komutlar)

Ortamınıza göre TLS parametreleri değişir; prensip aynıdır.

export ETCDCTL_API=3

# Örnek: control plane üzerinde çalıştırın
etcdctl endpoint status --write-out=table
etcdctl endpoint health --write-out=table
etcdctl member list --write-out=table

Okuma:

• Üyelerin bir kısmı “unhealthy” → quorum riski
• Leader yok / sürekli leader değişimi → network/disk problemi

4) Karar ağacı: quorum var mı?

4.1 Quorum VAR (ör. 3 üyeden 2’si healthy)

Hedef: cluster’ı stabilize et.

• Sorunlu member’ı izole et (node drain değil, ETCD bağlantısını izole et)
• Disk latency’yi düşür (noisy neighbor, storage sorunu)
• Gerekiyorsa ETCD compaction/defrag planla (hemen değil, stabilize sonrası)

4.2 Quorum YOK (ör. 3 üyeden 1’i kaldı)

Hedef: tutarlı restore ile kontrol düzlemini geri getir.

Bu noktada iki seçenek vardır:

• Son sağlam snapshot’tan restore (önerilen)
• Kalan tek member’dan “force new cluster” gibi riskli yollar (son çare)

5) Kurtarma: Snapshot restore yaklaşımı (önerilen)

Ön koşullar:

• Düzenli snapshot alınıyor olmalı (başka node/depoya kopyalanmış)
• Snapshot’ın bütünlüğü kontrol edilebilir olmalı

Yüksek seviyeli adımlar:

1. Tüm ETCD instance’larını durdur (kontrolsüz yazmayı bitir)
2. Snapshot’ı seç (en güncel + bütün)
3. Yeni bir ETCD data dir ile restore et
4. Üyeleri yeniden ayağa kaldır ve leader oluşumunu doğrula
5. API server’ları sonra başlat

6) Split-brain’den kaçınma

Quorum kaybında en kritik risk, “iki farklı gerçeklik” oluşmasıdır.

Kaçınma prensipleri:

• Aynı anda birden fazla “kurtarma denemesi” yapma
• Eski data dir ile yeni restore’u karıştırma
• Network partition varken zorla cluster kurma
• Restore edilen cluster’ı stabilize etmeden otomasyonu açma

7) Önleyici kontroller (incident sonrası aksiyon listesi)

• ETCD üyeleri tek arıza alanında mı? (aynı storage / aynı rack / aynı AZ)
• Disk latency alarmları var mı? (fsync, wal yazımı)
• Snapshot sıklığı ve dışa kopya var mı?
• Quorum: 3 veya 5 üyeli tasarım (çift sayıdan kaçın)
• Compaction/defrag bakımı planlı mı?

8) Son söz

ETCD quorum kaybı, “Kubernetes bozuldu” değil; genelde disk, network veya bakım disiplininin bozulmasıdır. Runbook’un amacı hızlı kahramanlık değil; tutarlılığı koruyarak üretimi geri getirmek. Snapshot’ı ciddiye alın, restore’u tatbikat yapın, otomasyonun restart döngüsünü kontrol edin.