Kubernetes Troubleshooting Rehberi
Kubernetes cluster yönetimi ve sorun giderme için kapsamlı komut ve çözüm rehberi.
📥 PDF İndir: kubernetes-troubleshooting.pdf (PDF dosyasını assets/pdf/ klasörüne ekledikten sonra bu link çalışacaktır)
İçindekiler
- 🔧 Node İşlemleri
- 🔄 Pod Yeniden Başlatma
- 🧹 Pod Temizleme
- 🔍 Pod Loglarını İnceleme
- 🔁 Pod içinde Komut Çalıştırma
- 🌐 Servis (Service) Problemleri
- 📦 PVC (PersistentVolumeClaim) Problemleri
- 💥 CrashLoopBackOff Sorunları
- 🚨 Pod Scheduling Problemleri
- 📡 LoadBalancer Servis Dış IP Alamıyor
- 🚀 Deployment Sorunları
- 🛠️ ConfigMap Sorunları
- 🔐 Secret Problemleri
- 🧠 Faydalı
kubectlKısayolları - 🔐 NetworkPolicy Sorunları
- ⚙️ Helm Sorunları
- 🌍 Ingress Problemleri
- 📊 Metrics Server Sorunları
- 📁 Pod ile Dosya Transferi (kubectl cp)
- 🧬 etcd Backup ve Geri Yükleme
- ⚙️ Kube-Proxy Problemleri
- 🧩 CNI (Container Network Interface) Sorunları
- 🌐 CoreDNS Sorunları
- 🔒 API Server Ulaşılabilirlik
- 🧠 Kubelet Sorunları
- 🔥 Düşük Seviyeli Network Problemleri
- 📝 Günlük Kayıtları (systemd journal)
- 📥 Log Toplama & İnceleme
- ⛔ Node Drain & Cordoning
- 🧱 Takılı Kalmış PVC/PV Problemleri
- 🧲 Pod Affinity / Anti-Affinity Sorunları
- ⬆️ Upgrade Sonrası Sorunlar
- 🧩 Custom Resource Definition (CRD) Sorunları
- 🔔 Mutating/Validating Webhook Sorunları
- 🔐 RBAC Problemleri
- 📝 Audit Log Problemleri (Kube-apiserver)
- 🛡️ Pod Güvenlik Ayarları
- 🧬 etcd Sorunları
- 📅 Sertifika Süreleri ve Yenileme
- 🧹
kubeadm resetSonrası Temizlik - ⚠️ Control Plane Failover (HA Ortamlar)
🔧 Node İşlemleri
🔹 Node’u Klasik Yöntemle Küme’ye Ekleme
kubeadm join <MASTER_IP>:<PORT> --token <TOKEN> --discovery-token-ca-cert-hash sha256:<HASH>
kubeadm token create --print-join-commandkomutuyla master’dan join komutunu alabilirsin.
🔹 Node’un Sağlığını Kontrol Etme
kubectl get nodes
kubectl describe node <NODE_ADI>
NotReadydurumu görüyorsan geneldekubeletya dacontainer runtimeçalışmıyordur.- SSH ile node’a girip
systemctl status kubeletile bak.
🔹 Node’dan Taint Kaldırma
kubectl taint nodes <NODE_ADI> node-role.kubernetes.io/master-
- Eğer
NoSchedulenedeniyle Pod’lar bu node’a gitmiyorsa bu komutla açarsın.
🔹 Node’a Taint Ekleme
kubectl taint nodes <NODE_ADI> key=value:NoSchedule
- Pod’ların bu node’a gitmesini istemiyorsan (örneğin özel işler için) kullanılır.
🔄 Pod Yeniden Başlatma
kubectl delete pod <POD_ADI> -n <NAMESPACE>
- Deployment varsa otomatik yeniden gelir.
- ConfigMap veya Secret değiştiğinde restart gerekebilir.
🧹 Pod Temizleme
kubectl get pods --all-namespaces | grep Evicted
kubectl delete pod <POD_ADI> -n <NAMESPACE>
- Evicted pod’lar sistemi kirletir, düzenli temizle.
🔍 Pod Loglarını İnceleme
kubectl logs <POD_ADI> -n <NAMESPACE>
kubectl logs <POD_ADI> -c <CONTAINER_ADI> -n <NAMESPACE>
- Hata trace’lerini görmek için birebir.
- Çok eski loglar için
kubectl logs --previouskullanılabilir.
🔁 Pod içinde Komut Çalıştırma
kubectl exec -it <POD_ADI> -n <NAMESPACE> -- /bin/sh
- Bazı imajlarda
/bin/bashyerine/bin/shçalışır.
🌐 Servis (Service) Problemleri
🔹 Service Ulaşılabilirlik Testi
kubectl get svc -n <NAMESPACE>
kubectl describe svc <SERVICE_ADI> -n <NAMESPACE>
- Servis
ClusterIP,NodePort,LoadBalancertiplerinden hangisi? - Hedef Pod’lar gerçekten ayakta mı?
🔹 DNS Çözümleme Problemi
kubectl exec -it <POD_ADI> -- nslookup <SERVICE_ADI>.<NAMESPACE>.svc.cluster.local
- CoreDNS problemi olabilir. Aşağıdaki gibi yeniden başlatılabilir:
kubectl -n kube-system rollout restart deployment coredns
📦 PVC (PersistentVolumeClaim) Problemleri
🔹 PVC Durumlarını Görüntüleme
kubectl get pvc -n <NAMESPACE>
kubectl describe pvc <PVC_ADI> -n <NAMESPACE>
Pendingdurumda kalıyorsa uygun StorageClass yok demektir.kubectl get scile mevcut sınıfları kontrol et.
💥 CrashLoopBackOff Sorunları
🔹 Pod Detaylarına Bak
kubectl describe pod <POD_ADI> -n <NAMESPACE>
- Olayları (Events) incele. Genellikle yanlış environment variable, configmap hatası çıkar.
🔹 Container Logları
kubectl logs <POD_ADI> --previous -n <NAMESPACE>
--previous, çöken son container’ın logunu gösterir.
🚨 Pod Scheduling Problemleri
kubectl describe pod <POD_ADI>
Eventskısmında0/3 nodes are available: 3 Insufficient cpugibi mesajlar varsa kaynak yetersiz.- Yeni node eklemek ya da kaynak limitlerini düşürmek gerekebilir.
📡 LoadBalancer Servis Dış IP Alamıyor
kubectl get svc <SERVICE_ADI>
- Dış IP gelmiyorsa
cloud controller managerloglarına bak. MetalLBgibi bare-metal çözümlerde config hatası olabilir:
kubectl get configmap -n metallb-system config -o yaml
🚀 Deployment Sorunları
🔹 Rollout Durumunu Kontrol Et
kubectl rollout status deployment <DEPLOYMENT_ADI> -n <NAMESPACE>
- Deployment takıldıysa, yeni imaj çekilememiş olabilir. ImagePullBackOff hatasına dikkat.
🔹 Deployment’ı Geri Alma (Rollback)
kubectl rollout undo deployment <DEPLOYMENT_ADI> -n <NAMESPACE>
- Yeni sürüm sorun çıkardıysa bir önceki haline döner.
🛠️ ConfigMap Sorunları
🔹 ConfigMap’i Yeniden Yüklemek
kubectl create configmap <AD> --from-file=dosya.env -o yaml --dry-run=client | kubectl apply -f -
- ConfigMap değişti ama Pod hala eski halindeyse Pod’u yeniden başlatmak gerekebilir.
🔹 Pod’da ConfigMap’in Yüklendiğini Kontrol Et
kubectl exec -it <POD_ADI> -n <NAMESPACE> -- cat /path/in/container/config.env
🔐 Secret Problemleri
🔹 Secret’i Okumak (Base64 Decode ile)
kubectl get secret <SECRET_ADI> -n <NAMESPACE> -o jsonpath="{.data}"
- Çıkan değerler base64 ile encode’dur.
echo "cGFzc3dvcmQ=" | base64 -d
🔹 Secret’i Güncellemek
kubectl create secret generic <AD> --from-literal=key=value -o yaml --dry-run=client | kubectl apply -f -
🧠 Faydalı kubectl Kısayolları
🔹 Etiketle Node veya Pod
kubectl label nodes <NODE_ADI> zone=istanbul
kubectl label pods <POD_ADI> env=prod
🔹 Kaynakları Etiket ile Filtrele
kubectl get pods -l env=prod
🔹 Sık Kullanılan kubectl Kısa Kodu
kubectl get all -n <NAMESPACE>
- Tüm kaynakları (pod, svc, deploy vs) bir anda listeler.
🔐 NetworkPolicy Sorunları
🔹 Pod’lar Arası Erişim Engelleniyor
kubectl get networkpolicy -n <NAMESPACE>
kubectl describe networkpolicy <POLICY_ADI> -n <NAMESPACE>
- Erişim engellenmişse
allow allpolitikası test için yazılabilir:
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-all
namespace: default
spec:
podSelector: {}
ingress:
- {}
egress:
- {}
policyTypes:
- Ingress
- Egress
⚙️ Helm Sorunları
🔹 Helm Release’leri Görüntüleme
helm list -A
- Tüm namespace’lerdeki release’leri gösterir.
🔹 Helm ile Kurulu Kaynağı Silmek
helm uninstall <RELEASE_ADI> -n <NAMESPACE>
- Helm ile kuruluysa
kubectl deleteile silmek eksik temizlik yapabilir.
🌍 Ingress Problemleri
🔹 Ingress Kaynaklarını Görmek
kubectl get ingress -A
- IP/hostname çözülmüyorsa DNS kaydı eksik olabilir.
- Ingress controller (örneğin nginx) çalışıyor mu?
kubectl get pods -n ingress-nginx
📊 Metrics Server Sorunları
🔹 kubectl top Çalışmıyor
kubectl top nodes
- Hata alıyorsan Metrics Server kurulu değil demektir.
- Kurulum sonrası
--kubelet-insecure-tlsparametresi gerekebilir:
--kubelet-insecure-tls
🔹 Metrics Server Pod Loglarına Bak
kubectl logs <POD_ADI> -n kube-system
📁 Pod ile Dosya Transferi (kubectl cp)
🔹 Pod’dan Host’a Dosya Kopyalama
kubectl cp <NAMESPACE>/<POD_ADI>:/path/in/container /local/path
🔹 Host’tan Pod’a Dosya Kopyalama
kubectl cp /local/path <NAMESPACE>/<POD_ADI>:/path/in/container
- Pod çalışır durumda olmalı. Hedef yol mevcut değilse hata verir.
🧬 etcd Backup ve Geri Yükleme
🔹 etcd Yedeği Alma (Kubeadm Kurulumları İçin)
ETCDCTL_API=3 etcdctl snapshot save snapshot.db --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key
🔹 etcd Yedeği Geri Yükleme
ETCDCTL_API=3 etcdctl snapshot restore snapshot.db --data-dir=/var/lib/etcd-from-backup
- Dikkat: Mevcut etcd klasörünü yedekleyip kapatmadan restore yapma.
⚙️ Kube-Proxy Problemleri
🔹 Kube-Proxy Loglarını İncele
kubectl -n kube-system logs -l k8s-app=kube-proxy
- Servis routing problemi varsa burada ipucu bulabilirsin.
🔹 iptables Kuralları Doğru mu?
iptables -t nat -L -n | grep KUBE
- Kube-proxy
iptablesmodundayken bu kuralları yazar. Eksikse proxy çalışmıyor olabilir.
🧩 CNI (Container Network Interface) Sorunları
🔹 Pod’lar Arası Erişim Yoksa
kubectl get pods -o wideile IP’leri kontrol et.- CNI plugin (Flannel, Calico, vs.) podları çalışıyor mu?
kubectl get pods -n kube-system
🔹 Yeni Node Ekledin, Ama Pod’lar IP Almıyor
- CNI plugin node üzerinde düzgün yüklenmemiş olabilir.
- Node’da aşağıdakileri kontrol et:
ls /etc/cni/net.d/
🌐 CoreDNS Sorunları
🔹 CoreDNS Pod’larını Görüntüle
kubectl get pods -n kube-system -l k8s-app=kube-dns
CrashLoopBackOffdurumundaysaConfigMaphatalı olabilir:
kubectl -n kube-system edit configmap coredns
🔒 API Server Ulaşılabilirlik
🔹 Apiserver Durumu
kubectl get componentstatuses
etcd,scheduler,controller-manager,apiserverburadan izlenebilir.
🔹 API Server Logları
journalctl -u kube-apiserver
- Hata durumlarında burada detaylı log bulursun.
🧠 Kubelet Sorunları
🔹 Kubelet Hizmeti Çalışıyor mu?
systemctl status kubelet
Failedise genellikle yanlış config veya/etc/kubernetes/kubelet.confdosyası bozulmuştur.
🔹 Kubelet Logları
journalctl -u kubelet
🔥 Düşük Seviyeli Network Problemleri
🔹 iptables ya da ipvs Doğrulama
iptables-save | grep KUBE
ipvsadm -Ln
- Pod’lara trafik yönlenmiyorsa burada sıkıntı olabilir.
📝 Günlük Kayıtları (systemd journal)
🔹 Belirli Süre İçin Kayıtları Görüntüle
journalctl -u kubelet --since "2 hours ago"
🔹 En Son Kayıtları Canlı Takip Etmek
journalctl -u kubelet -f
📥 Log Toplama & İnceleme
🔹 Namespace Bazlı Tüm Pod Logları
for pod in $(kubectl get pods -n <NAMESPACE> -o jsonpath="{.items[*].metadata.name}"); do
echo "== $pod ==";
kubectl logs $pod -n <NAMESPACE>;
done
- Geniş hata taraması için faydalı.
🔹 Crashloop Olaylarını Çekmek
kubectl get events --all-namespaces | grep -i crash
⛔ Node Drain & Cordoning
🔹 Node Drain (Pod’ları Taşıyarak Boşaltma)
kubectl drain <NODE_ADI> --ignore-daemonsets --delete-emptydir-data
- Genelde bakım veya silme öncesi yapılır.
- StatefulSet varsa dikkatli olunmalı, veri kaybı yaşanabilir.
🔹 Node’u Scheduling’e Kapatmak
kubectl cordon <NODE_ADI>
🔹 Node Scheduling’i Açmak
kubectl uncordon <NODE_ADI>
🧱 Takılı Kalmış PVC/PV Problemleri
🔹 PVC Terminating Durumunda Kalıyor
kubectl get pvc -n <NAMESPACE>
- Finalizer’ı temizlemek gerekebilir:
kubectl patch pvc <PVC_ADI> -n <NAMESPACE> -p '{"metadata":{"finalizers":null}}'
🔹 PV Released Durumunda Kalıyor
- Manüel olarak temizlenmeli ya da reclaim policy
Retainise silinip yeniden oluşturulmalı.
🧲 Pod Affinity / Anti-Affinity Sorunları
🔹 Scheduling Neden Olmuyor?
kubectl describe pod <POD_ADI>
MatchExpressionsveyarequiredDuringSchedulingIgnoredDuringExecutionkuralları hatalı olabilir.- Etiket uyuşmazlığı varsa
0/3 nodes match pod affinity rulesşeklinde uyarı verir.
⬆️ Upgrade Sonrası Sorunlar
🔹 API Version Deprecated (Örneğin apps/v1beta1)
kubectl get deploy -o yaml | grep apiVersion
- API değişikliklerinde önce tüm CRD ve manifest’ler yeni versiyona uyumlu hale getirilmeli.
🔹 CoreDNS, kube-proxy veya CNI Uyuşmazlıkları
kubectl get ds -n kube-systemileDaemonSetdurumlarını kontrol et.- Yeni versiyona uygun imaj tag’leri kullanıldığından emin olun.
🧩 Custom Resource Definition (CRD) Sorunları
🔹 CRD’yi Listele ve Detaylarını Gör
kubectl get crd
kubectl describe crd <CRD_ADI>
- CRD eksikse ona bağlı controller çalışmaz.
- CRD versiyonu (v1beta1 vs v1) uyumsuzluğu problem yaratabilir.
🔹 CRD ile Oluşturulan Kaynaklar
kubectl get <KAYNAK_TÜRÜ> -n <NAMESPACE>
- Örneğin:
kubectl get prometheuses.monitoring.coreos.com -n monitoring
🔔 Mutating/Validating Webhook Sorunları
🔹 Webhook’lar Neden Sorun Çıkarır?
- API server webhook’a ulaşamazsa Pod yaratma işlemi takılır.
- TLS sertifikası geçersizse
x509: certificate signed by unknown authorityhatası çıkar.
🔹 Webhook’ları Listele
kubectl get mutatingwebhookconfigurations
kubectl get validatingwebhookconfigurations
- Detay için
kubectl describekullan.
🔹 Webhook’u Geçici Olarak Devre Dışı Bırak
kubectl delete mutatingwebhookconfiguration <ADI>
- Acil çözüm için geçici bir yaklaşımdır.
🔐 RBAC Problemleri
🔹 Kullanıcı/POD Yetkisini Test Etme
kubectl auth can-i get pods --as=some-user -n <NAMESPACE>
- Erişim verilmemişse
nosonucu döner.
🔹 Role ve RoleBinding Kontrolü
kubectl get role,rolebinding -n <NAMESPACE>
- Cluster-wide için
clusterroleveclusterrolebindingbakılır.
📝 Audit Log Problemleri (Kube-apiserver)
🔹 Audit Log Etkin mi?
- API sunucusu başlatılırken
--audit-log-pathve--audit-policy-fileparametreleri verilmiş mi? - Dosya sisteminde audit log var mı?
cat /var/log/kubernetes/audit.log | grep <USER_ADI>
🛡️ Pod Güvenlik Ayarları
🔹 SecurityContext Kontrolü
securityContext:
runAsUser: 1000
runAsGroup: 3000
readOnlyRootFilesystem: true
allowPrivilegeEscalation: false
- Container’ların root yetkisi olmaması için önemlidir.
🔹 PodSecurityPolicy (Deprecated) Yerine OPA/Gatekeeper
- Kubernetes v1.25 sonrası PSP kaldırıldı.
- Yerine Gatekeeper veya Kyverno gibi policy engineleri kullanılır.
🧬 etcd Sorunları
🔹 etcd Durumu ve Üyeler
ETCDCTL_API=3 etcdctl member list --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key
- Bir node erişilemiyorsa quorum kaybı olabilir (3 üyeli cluster için en az 2 erişilebilir olmalı).
🔹 etcd Snapshot Yedekten Geri Yüklemek
ETCDCTL_API=3 etcdctl snapshot restore snapshot.db --data-dir=/var/lib/etcd-from-backup
- Geri yükleme sonrası static pod manifest dosyası (
/etc/kubernetes/manifests/etcd.yaml) bu dizine göre güncellenmeli.
📅 Sertifika Süreleri ve Yenileme
🔹 Sertifika Sürelerini Kontrol Etme
kubeadm certs check-expiration
- Kubernetes bileşenleri genellikle 1 yıl geçerli sertifikalarla başlatılır.
🔹 Tüm Sertifikaları Yenilemek
kubeadm certs renew all
systemctl restart kubelet
- Ardından kube-apiserver, controller, scheduler vs. restart olur.
🧹 kubeadm reset Sonrası Temizlik
🔹 reset Komutu
kubeadm reset
- Ardından iptables ve CNI kalıntıları temizlenmeli:
iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X
rm -rf /etc/cni/net.d
- Yeni
kubeadm initöncesi bu adım önemlidir.
⚠️ Control Plane Failover (HA Ortamlar)
🔹 API Server Ulaşılmıyor
- Tüm control-plane node’ları down olduysa quorum kaybı olabilir.
- Load balancer varsa altındaki node’lar kontrol edilmeli.
🔹 etcd Yedeği Yoksa Tek Noda Dönme (Tehlikeli)
- Yalnızca bir
etcddatası kalan node varsa--force-new-clusterile yeniden başlatma yapılabilir. - DİKKAT: Bu yöntem diğer üyelerle uyumsuzluk yaratır, en son çare olarak kullanılmalı.