İçeriğe geç
KubeAtlas
Kubernetes DevOps SRE Debug Cheat Sheet kubectl

Kubernetes Pod Debug Cheat Sheet

Onur Ömer Tunç 6 dk okuma

Production’da bir pod ayağa kalkmıyorsa her saniye önemlidir. Bu cheat sheet, pod otopsisini sistematik hale getirir: 3 başlangıç komutu, 6 hata senaryosu ve 45 dakika tasarruf ettiren debug sırası.

1 START HERE
bash — pod tanılama
kubectl get pod <pod> -n <ns>
kubectl describe pod <pod> -n <ns>
kubectl logs <pod> -n <ns> -c <container> --previous
Bu Sırayla Oku
  1. 1Status
  2. 2Events
  3. 3Last State
  4. 4Exit Code
  5. 5Restarts
  6. 6Logs
Çok konteynerli pod'larda -c <container> bayrağını kullanın — aksi hâlde yanlış konteynerin loglarına bakıyor olabilirsiniz.
2 Hata Modunu Seç
Pending
Kubernetes pod'u kabul etti, scheduler yerleştiremedi.
Bak
  • kubectl describe pod <pod> -n <ns>
  • kubectl get nodes
  • kubectl get pvc -n <ns>
Ara
  • FailedScheduling
  • Insufficient cpu / memory
  • taint/toleration uyuşmazlığı
  • nodeSelector/affinity uyuşmazlığı
  • Quota aşımı
  • PVC Pending veya bağlı değil
  • storage class uyuşmazlığı
Çözüm
  • Request'leri düşür
  • Kapasite ekle
  • Taint/toleration düzelt
  • Quota güncelle
  • Storage bağla
CrashLoopBackOff
Konteyner başlıyor, çıkıyor; Kubernetes yeniden başlatmayı sürdürüyor.
Bak
  • kubectl logs <pod> -n <ns> -c <container> --previous
  • kubectl describe pod <pod> -n <ns>
Ara
  • Exit Code 1 → app/config hatası
  • Exit Code 137 → OOMKilled
  • Exit Code 126 → çalıştırılamaz komut
  • Exit Code 127 → komut bulunamadı
  • Eksik env var
  • Hatalı başlangıç komutu
  • Başarısız bağımlılık
Çözüm
  • Önceki logları oku
  • Last State/Reason'ı doğrula
  • Exit code'u eşle
  • App, config, komut veya bağımlılığı düzelt
OOMKilled
Konteyner bellek limitini aştı ve sonlandırıldı.
Bak
  • kubectl describe pod <pod> -n <ns>
  • kubectl top pod <pod> -n <ns>
  • kubectl get pod <pod> -n <ns> -o jsonpath='{.spec.containers[*].resources}'
Ara
  • Reason: OOMKilled
  • Exit Code 137
  • Limit kullanıma göre çok düşük
  • Ani bellek spike'ı
  • Trafik sonrası restart
Çözüm
  • Limit'i artır
  • Request'i gerçekçi ayarla
  • Bellek profilini çıkar
  • Memory leak'i düzelt
kubectl top için Metrics Server kurulu olmalıdır.
Init Container Failing
Init container başarısız olduğu için ana konteyner hiç başlamıyor.
Bak
  • kubectl get pod <pod> -n <ns> -o jsonpath='{.status.initContainerStatuses}'
  • kubectl logs <pod> -n <ns> -c <init-container>
Ara
  • DB migration hatası
  • Bağımlılık erişilemiyor
  • Eksik Secret
  • İzin sorunu
  • DNS hatası
  • Hatalı bekleme mantığı
Çözüm
  • Bağımlılığı düzelt
  • Secret, DB bağlantısını kontrol et
  • Migration script'ini doğrula
  • DNS veya bekleme koşulunu düzelt
ImagePullBackOff
Kubernetes konteyner imajını çekemiyor.
Bak
  • kubectl describe pod <pod> -n <ns>
  • kubectl describe serviceaccount <sa> -n <ns>
Ara
  • manifest unknown
  • repository does not exist
  • pull access denied
  • authentication required
  • Hatalı image tag
  • Yanlış registry URL
  • Eksik imagePullSecret
Çözüm
  • Image adı ve tag'i düzelt
  • Registry auth'u doğrula
  • imagePullSecret ekle
  • Registry izinlerini düzelt
  • serviceAccount referansını kontrol et
CreateContainerError / ConfigError
Kubernetes imajı çekti; konteyner oluşturulamıyor.
Bak
  • kubectl describe pod <pod> -n <ns>
  • kubectl get cm -n <ns>
  • kubectl get secret -n <ns>
  • kubectl get pvc -n <ns>
Ara
  • Eksik ConfigMap
  • Eksik Secret
  • Geçersiz env referansı
  • Geçersiz volume mount
  • İzin reddedildi
  • PVC Pending veya bağlı değil
  • Salt okunur dosya sistemi
  • Mount path çakışması
Çözüm
  • Config referanslarını düzelt
  • Secret ve PVC'leri doğrula
  • Mount ve izin ayarlarını düzelt
  • Container runtime hatasını incele
3 45 Dakika Kazandıran Debug Sırası
1
kubectl get pod
Status'u tanımla
2
kubectl describe pod
Event'leri oku
3
kubectl logs --previous
Son crash'i incele
4
kubectl get pod -o yaml
Env, arg, volume, resource
5
kubectl top pod / node
CPU/memory baskısı
6
kubectl debug / netshoot
DNS, ağ, bağımlılık
Network Debug Seçenekleri
bash — network debug
# Mevcut pod'a debug container ekle
kubectl debug -it <pod> -n <ns> \
  --image=nicolaka/netshoot --target=<container>
# Tek seferlik network debug pod'u başlat
kubectl run netshoot -it --rm \
  --image=nicolaka/netshoot \
  --restart=Never -- sh

Sık Yapılan Hatalar

Exit code’ları karıştırmak: Exit Code 137 her zaman OOMKilled değildir — SIGKILL (sinyal 9) ile öldürülmüş olabilir. kubectl describe içindeki Reason alanı kesin cevabı verir.

kubectl logs → --previous kullanmamak: Pod yeniden başladıktan sonra mevcut log boştur. Crash’den önceki loglar için her zaman --previous ekleyin.

Tek konteynere odaklanmak: Init container başarısız olduğunda ana konteyner hiç başlamaz. kubectl get pod -o yaml ile initContainerStatuses listesini kontrol edin.

Resource request/limit karıştırmak: Scheduler kararlarını requests, OOM kararlarını limits belirler. İkisi birbirinden bağımsızdır — ikisini ayrı ayrı kontrol edin.

Etiketler Kubernetes DevOps SRE Debug Cheat Sheet kubectl
Tüm yazılar