AlestaSoft

Kubernetes pod'unuzda ImagePullBackOff veya ErrImagePull hatası mı alıyorsunuz? Container image'ınız indirilmiyor mu? Alesta Web olarak bu DevOps dünyasının en sık karşılaşılan hatalarından birini 7 farklı yöntemle nasıl çözeceğinizi adım adım anlatıyoruz. Bu rehberde hem sorunun nedenlerini hem de pratik çözümlerini öğreneceksiniz.
ImagePullBackOff Nedir? (What is ImagePullBackOff?)
ImagePullBackOff, Kubernetes'in bir container image'ını registry'den (Docker Hub, Google Container Registry vb.) indirmeye çalışırken başarısız olması durumunda verdiği bir hata mesajıdır.
Şöyle düşünün: Kubernetes bir pod başlatmak istiyor. Pod tanımında "nginx:latest" image'ını kullan demiş. Kubernetes gidiyor, bu image'ı indirmeye çalışıyor ama bir şeyler ters gidiyor. İşte tam burada ImagePullBackOff devreye giriyor.
"BackOff" kelimesi aslında Kubernetes'in akıllı bir mekanizması. İlk denemede başarısız olunca hemen pes etmiyor. 5 saniye bekliyor, tekrar deniyor. Olmadı mı 10 saniye bekliyor, yine deniyor. Bu şekilde exponential backoff (üstel geri çekilme) stratejisi kullanarak maksimum 5 dakikaya kadar denemeye devam ediyor.
Alesta Web ekibi olarak yüzlerce Kubernetes deployment'ında bu hatayla karşılaştık. Deneyimlerimize göre, bu hatanın %80'i basit yapılandırma hatalarından kaynaklanıyor.
ErrImagePull vs ImagePullBackOff Farkı
Çoğu kişi bu iki hatayı karıştırıyor, ama aslında aralarında önemli bir fark var:
Hata Sıralaması / Error Sequence
| Sıra | Hata Türü | Açıklama |
|---|---|---|
| 1 | ErrImagePull |
İlk deneme başarısız olduğunda gösterilen hata |
| 2 | ImagePullBackOff |
Kubernetes birkaç kez denedikten sonra "geri çekildiğinde" gösterilen hata |
Yani ErrImagePull hatası görüyorsanız, problem yeni başlamış demektir. Eğer ImagePullBackOff görüyorsanız, Kubernetes zaten birkaç kez denemiş ve başarısız olmuş demektir.
6 Yaygın Neden (Common Causes)
Alesta Web uzmanları olarak karşılaştığımız en yaygın ImagePullBackOff nedenlerini derledik:
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:latest2️⃣ 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.06️⃣ 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.3Hatayı Nasıl Tespit Ederiz?
Alesta Web rehberiyle adım adım hatayı tespit edebilirsiniz:
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 2mSTATUS 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: ErrImagePullEvents 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.
kubectl describe pod çıktısını bir dosyaya kaydedin. Gelecekte benzer problemlerle karşılaştığınızda hızlı karşılaştırma yapabilirsiniz:
kubectl describe pod myapp-deployment-abc > debug-imagepull-2025-12-07.txtÇözüm 1: Image Adı ve Tag Kontrolü (Verify Image Name and Tag)
İlk ve en önemli adım: Image adınızın doğru olduğundan emin olun.
Kontrol Listesi:
- Yazım hatası var mı? nginxx → nginx
- Tag doğru mu? nginx:latst → nginx:latest
- 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Çözüm 2: Registry Kimlik Doğrulama (Authentication)
Eğer private bir registry kullanıyorsanız (Docker Hub private repo, Google Container Registry, AWS ECR vb.), Kubernetes'e kimlik bilgilerini vermelisiniz.
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 kaydedilirProduction ortamlarında docker login yerine Kubernetes Secret kullanın. Docker credentials dosyası güvenli değildir!
Çözüm 3: Network ve Registry Erişimi (Network Connectivity)
Alesta Web ekibi olarak en çok göz ardı edilen sebeplerden biri network sorunlarıdır.
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 refusedFirewall 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Çözüm 4: Rate Limit Sorunları (Docker Hub Rate Limits)
Docker Hub'ın rate limit'ine takılmış olabilirsiniz. Alesta Web olarak bu durumla sık karşılaşıyoruz.
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:
- Docker Hub'a Login Olun: Ücretsiz hesap ile limit 200/saat olur
Bash
docker login - Docker Hub Pro Alın: Unlimited pull (aylık $5)
- 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
- Image'ları Cache'leyin: Kendi private registry'nizde mirror oluşturun
Production cluster'larınızda Docker Hub'a doğrudan bağımlı olmayın. Image'ları kendi registry'nize kopyalayın (mirror). Böylece hem rate limit sorununu hem de dış bağımlılığı çözmüş olursunuz.
Çözüm 5: Private Registry için imagePullSecrets
Private registry kullanıyorsanız, Kubernetes'e kimlik bilgilerini imagePullSecrets ile vermek en güvenli yöntemdir.
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-secretAdım 3: Deployment'ı Uygulayın
# YAML'ı uygula
kubectl apply -f deployment.yaml
# Pod durumunu kontrol et
kubectl get pods
# Artık ImagePullBackOff hatası kaybolmalı!Pod'ların STATUS'ü Running olmalı. kubectl describe pod ile Events bölümünde "Successfully pulled image" mesajını görmelisiniz.
Çözüm 6: Registry URL Yapılandırması
Kubernetes varsayılan olarak Docker Hub'a bakar. Başka bir registry kullanıyorsanız tam URL belirtmelisiniz.
Registry URL Formatları:
| Registry | Image Format |
|---|---|
| Docker Hub | nginx:latest veya myusername/myapp:v1.0 |
| Google GCR | gcr.io/PROJECT_ID/myapp:v1.0 |
| AWS ECR | 123456789.dkr.ecr.REGION.amazonaws.com/myapp:v1.0 |
| Azure ACR | myregistry.azurecr.io/myapp:v1.0 |
| GitHub | ghcr.io/username/myapp:v1.0 |
| Quay.io | quay.io/username/myapp:v1.0 |
# ❌ Yanlış - Kubernetes bunu Docker Hub'da arar
image: myapp:v1.0
# ✅ Doğru - GCR'da olduğunu belirtin
image: gcr.io/my-project/myapp:v1.0Çözüm 7: Manuel Test ve Debug (Manual Testing)
Alesta Web debug stratejisi: Önce manuel test edin, sonra Kubernetes'e verin.
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 existImage 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 edinKubectl 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- ✅ Image adı doğru mu? (Yazım hatası yok mu?)
- ✅ Tag mevcut mu? (Docker Hub'da var mı?)
- ✅ Registry URL tam mı? (gcr.io, ECR vb. için)
- ✅ Private ise credentials var mı? (imagePullSecrets)
- ✅ Network erişimi var mı? (Node'dan registry'ye ping/wget)
- ✅ Rate limit aşılmadı mı? (Docker Hub rate limit kontrolü)
- ✅ Manuel docker pull çalışıyor mu?
? Kaynaklar ve Referanslar / References
Bu rehberi hazırlarken aşağıdaki kaynaklardan faydalanılmıştır:
- Komodor - Troubleshooting Kubernetes ImagePullBackOff and ErrImagePull Errors
- Groundcover - Demystifying Kubernetes ImagePullBackOff
- Spacelift - Kubernetes ImagePullBackOff Troubleshooting
- Lumigo - What Is Kubernetes ImagePullBackOff Error and How to Fix It
- Gremlin - How to fix and prevent ImagePullBackOff events in Kubernetes
- Stack Overflow - How can I debug ImagePullBackOff?
- Tutorial Works - Kubernetes ImagePullBackOff error: what you need to know
- Sysdig - Kubernetes ErrImagePull and ImagePullBackOff in detail
- KodeKloud - How to Fix ImagePullBackOff & ErrImagePull in Kubernetes
Alesta Web olarak Kubernetes, Docker ve DevOps konularında sürekli güncel içerikler üretiyoruz. Daha fazla bilgi için alestaweb.com adresini ziyaret edebilirsiniz.
✅ ImagePullBackOff Hatası Çözüldü! (Error Solved!)
Artık Kubernetes ImagePullBackOff ve ErrImagePull hatalarını tanıyor ve çözebiliyorsunuz. Alesta Web olarak bu rehberde 7 farklı çözüm yöntemini detaylı şekilde anlattık.
Hızlı Özet / Quick Summary:
- ✅ ImagePullBackOff ne demek anladık (What is ImagePullBackOff)
- ✅ ErrImagePull farkını öğrendik
- ✅ 6 yaygın nedeni keşfettik (Common causes)
- ✅ kubectl describe ile debug yaptık
- ✅ Image adı ve tag kontrolü
- ✅ imagePullSecrets ile authentication (Private registry credentials)
- ✅ Network ve registry erişimi test ettik
- ✅ Docker Hub rate limit sorununu çözdük
ImagePullBackOff hatası genellikle basit yapılandırma hatalarından kaynaklanır. Panik yapmayın, yukarıdaki checklist'i sırayla uygulayın. Deneyimlerimize göre %95 durumda Çözüm 1, 2 veya 5 ile problem çözülüyor.
Faydalı Linkler / Useful Links:
- Kubernetes Resmi Dokümanlar: kubernetes.io/docs
- Docker Hub: hub.docker.com
- kubectl Cheat Sheet: kubectl Reference
- Alesta Web Ana Sayfa: alestaweb.com
- Diğer Kubernetes Hataları: Kubernetes Sorunları Rehberi
© 2025 AlestaWeb - Tüm hakları saklıdır.

