Hata Sıralaması / Error Sequence

1️⃣ Yanlış Image Adı veya Tag (Wrong Image Name or Tag)

En yaygın sebep budur! Pod tanımında yazılan image adı registry'de yoktur.

# ❌ Yanlış
image: nginxx:latest  # "nginxx" diye bir image yok!

# ✅ Doğru
image: nginx:latest

2️⃣ Private Registry için Kimlik Bilgisi Eksik (Missing Credentials)

Docker Hub, Google Container Registry veya özel bir registry kullanıyorsanız ve image private ise, Kubernetes'in erişim yetkisi yoktur.

3️⃣ Registry Rate Limit Aşıldı

Docker Hub 2020'den beri rate limit uyguluyor:

• Kimlik doğrulamasız: Saatte 100 request
• Ücretsiz hesap: Saatte 200 request
• Pro hesap: Unlimited

Aktif bir Kubernetes cluster'ınız varsa bu limiti kolayca aşabilirsiniz.

4️⃣ Network Bağlantı Sorunu (Network Connectivity Issues)

Kubernetes node'ları registry'ye erişemiyordur. Firewall, proxy veya DNS sorunu olabilir.

5️⃣ Registry URL Eksik veya Yanlış

Kubernetes varsayılan olarak Docker Hub'a bakar. Eğer image'ınız başka bir yerdeyse (Google Artifact Registry, Amazon ECR vb.), tam URL vermelisiniz:

# ❌ Eksik (Kubernetes Docker Hub'da arar)
image: myapp:v1.0

# ✅ Tam URL (Google Container Registry örneği)
image: gcr.io/my-project/myapp:v1.0

# ✅ AWS ECR örneği
image: 123456789.dkr.ecr.us-east-1.amazonaws.com/myapp:v1.0

6️⃣ Image Tag Mevcut Değil

Image var ama belirttiğiniz tag yok:

# ❌ "v2.0" tag'i registry'de yok
image: nginx:v2.0

# ✅ Var olan bir tag kullan
image: nginx:1.25.3

Adım 1: Pod Durumunu Kontrol Edin

# Tüm pod'ları listele
kubectl get pods

# Çıktı örneği:
# NAME                    READY   STATUS              RESTARTS   AGE
# myapp-deployment-abc    0/1     ImagePullBackOff    0          2m

STATUS sütununda ImagePullBackOff veya ErrImagePull görüyorsanız problem bu.

Adım 2: Detaylı Bilgi Alın (Describe Pod)

# Pod detaylarını incele
kubectl describe pod myapp-deployment-abc

# Events bölümüne dikkat edin:
# Events:
#   Type     Reason     Age   From               Message
#   ----     ------     ----  ----               -------
#   Normal   Scheduled  2m    default-scheduler  Successfully assigned...
#   Normal   Pulling    2m    kubelet            Pulling image "myapp:v1.0"
#   Warning  Failed     2m    kubelet            Failed to pull image "myapp:v1.0": rpc error: code = Unknown desc = Error response from daemon: pull access denied for myapp, repository does not exist or may require 'docker login'
#   Warning  Failed     2m    kubelet            Error: ErrImagePull

Events bölümü size tam olarak neyin yanlış gittiğini söyler. Yukarıdaki örnekte "repository does not exist" diyor, yani image adı yanlış veya private.

Kontrol Listesi:

1. Yazım hatası var mı? nginxx → nginx
2. Tag doğru mu? nginx:latst → nginx:latest
3. Image registry'de var mı? Docker Hub'da arayın: hub.docker.com

Manuel Test (Docker ile):

# Image'ı manuel olarak çekmeyi deneyin
docker pull nginx:latest

# Başarılı olursa image adı doğru demektir
# Hata alırsanız image adı veya tag yanlış

Deployment YAML'ınızı Kontrol Edin:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: nginx:1.25.3  # ← Burayı kontrol edin!
        ports:
        - containerPort: 80

Docker Hub için Kimlik Doğrulama:

# Docker Hub'a login olun
docker login

# Username ve password girin
# Success mesajı gelirse credentials ~/.docker/config.json'a kaydedilir

Node'dan Registry'ye Erişimi Test Edin:

# Kubernetes node'una SSH yapın (eğer erişiminiz varsa)
# veya debug pod oluşturun:

kubectl run test-net --image=busybox --rm -it -- /bin/sh

# Pod içinde:
# Docker Hub'a erişim testi
wget -O- https://registry-1.docker.io/v2/

# Google Container Registry testi
wget -O- https://gcr.io/v2/

# Başarılı erişim: HTTP 200 veya 401 (auth gerekiyor ama erişilebilir)
# Başarısız: timeout veya connection refused

Firewall ve Proxy Kontrolü:

Eğer corporate network'te çalışıyorsanız:

• Firewall registry URL'lerini engelliyor olabilir
• HTTP proxy yapılandırması gerekebilir
• DNS çözümleme sorunu olabilir

# DNS testi
nslookup registry-1.docker.io

# Ping testi
ping registry-1.docker.io

Rate Limit Kontrolü:

# Docker Hub rate limit durumunuzu kontrol edin
curl -s -I https://auth.docker.io/token\?service\=registry.docker.io\&scope\=repository:ratelimitpreview/test:pull | grep ratelimit

# Çıktı örneği:
# ratelimit-limit: 100;w=21600
# ratelimit-remaining: 95;w=21600

Çözüm Seçenekleri:

1. Docker Hub'a Login Olun: Ücretsiz hesap ile limit 200/saat olur

   docker login
   

2. Docker Hub Pro Alın: Unlimited pull (aylık $5)
3. Alternatif Registry Kullanın:
   • Google Container Registry (gcr.io) - rate limit yok
   • AWS ECR - rate limit yok
   • GitHub Container Registry (ghcr.io) - rate limit yok
4. Image'ları Cache'leyin: Kendi private registry'nizde mirror oluşturun

Adım 1: Docker Registry Secret Oluşturun

# Docker Hub için secret oluşturma
kubectl create secret docker-registry dockerhub-secret \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=YOUR_USERNAME \
  --docker-password=YOUR_PASSWORD \
  --docker-email=YOUR_EMAIL

# Google Container Registry için
kubectl create secret docker-registry gcr-secret \
  --docker-server=gcr.io \
  --docker-username=_json_key \
  --docker-password="$(cat ~/gcr-key.json)" \
  --docker-email=YOUR_EMAIL

# AWS ECR için
kubectl create secret docker-registry ecr-secret \
  --docker-server=123456789.dkr.ecr.us-east-1.amazonaws.com \
  --docker-username=AWS \
  --docker-password=$(aws ecr get-login-password --region us-east-1)

Adım 2: Deployment'ta imagePullSecrets Kullanın

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: myusername/myapp:v1.0
        ports:
        - containerPort: 80
      imagePullSecrets:  # ← Burayı ekleyin!
      - name: dockerhub-secret

Adım 3: Deployment'ı Uygulayın

# YAML'ı uygula
kubectl apply -f deployment.yaml

# Pod durumunu kontrol et
kubectl get pods

# Artık ImagePullBackOff hatası kaybolmalı!

Registry URL Formatları:

Docker ile Manuel Pull Testi:

# Image'ı Docker ile manuel olarak çekin
docker pull nginx:latest

# Başarılı olursa:
# latest: Pulling from library/nginx
# Digest: sha256:...
# Status: Downloaded newer image for nginx:latest

# Başarısız olursa hata mesajını inceleyin:
# Error response from daemon: pull access denied for nginx, repository does not exist

Image Inspect (Detaylı Bilgi):

# Image'ı indirdikten sonra detaylarını inceleyin
docker image inspect nginx:latest

# Architecture, OS, Size gibi bilgileri gösterir
# Bu bilgiler Kubernetes node'unuzla uyumlu mu kontrol edin

Kubectl Debug Pod Oluşturun:

# Test amaçlı basit bir pod oluşturun
kubectl run test-nginx --image=nginx:latest --dry-run=client -o yaml > test-pod.yaml

# YAML'ı inceleyin ve uygulayın
kubectl apply -f test-pod.yaml

# Pod durumunu izleyin
kubectl get pods -w

# Hata alırsanız describe ile inceleyin
kubectl describe pod test-nginx