ECR Hub Hatası Nedir, Nasıl Çözülür – Pratik Çözüm Adımları

TLDR (Hızlı Çözüm): ECR Hub hatası genellikle AWS kimlik doğrulama başarısız olduğunda veya sistem saati yanlış olduğunda ortaya çıkar. En hızlı çözüm: AWS CLI'de `aws ecr get-login-password` komutu çalıştırın, aldığınız tokeni Docker'a giriş için kullanın, sistem saatini senkronize edin ve Docker daemon'ı yeniden başlatın. Sorun genellikle 5 dakika içinde çözülür.

ECR Hub Hatası Ne Anlama Gelir?

ECR (Elastic Container Registry), AWS'nin yönetilen Docker imaj deposudur. ECR Hub hatası, Docker uygulamanız Amazon'un bu sunucularına imaj yükleyemediğinde (push) veya indiremedığinde (pull) çıkar. Hata mesajı genellikle şöyle görünür: "no basic auth credentials", "authentication required" veya "access denied". Bu, Docker daemon'ınızın ECR sunucuları ile güvenli haberleşme kuramadığı anlamına gelir.

Neden Oluşur?

• Geçersiz AWS Kimlik Doğrulama: AWS Access Key ID ve Secret Access Key yanlış, güncelliğini yitirmiş veya silinmiş olabilir.
• Süresi Dolan ECR Token: AWS CLI ile alınan giriş token'ı 12 saat geçerlidir. Süresi biterse yeniden alınması gerekir.
• Sistem Saati Yanlış: Bilgisayarınızın saati AWS sunucularının saatinden 5 dakikadan fazla farklıysa imzalama başarısız olur.
• Docker Daemon Kapalı veya Çalışmıyor: Docker Desktop veya Docker servisini başlatmadıysanız bağlantı kurulamaz.
• AWS IAM İzni Eksik: Kullanıcı hesabınızda ECR push/pull yapma izni bulunmayabilir.
• Region Uyuşmazlığı: İmaj farklı AWS bölgesinde (region) oluşturulmuşsa ve siz başka bölgeden erişmeye çalışıyorsanız hata çıkar.
• Ağ Bağlantı Sorunu: Proxy, firewall veya VPN ayarları ECR sunucularına erişimi engelleyebilir.

Çözüm Adımları

1. Docker Daemon'ı Başlatın

   Windows/Mac: Docker Desktop uygulamasını açın ve tray'deki simgeyi kontrol edin (yeşil olmalı). Linux'te terminal'de çalıştırın:

   sudo systemctl start docker

   docker ps komutu hata vermeden sonuç göstermeli.

2. Sistem Saatini Senkronize Edin

   Windows: Saat ve Saate Sağ Tıkla > Saat ve Saat Ayarları > Saati Otomatik Ayarla açık olmalı.

   Mac: Sistem Ayarları > Genel > Tarih ve Saat > Saati Otomatik Ayarla etkin olsun.

   Linux'te: sudo timedatectl set-ntp true

   Tarih/saatin hata margin'i 5 dakikadan az olmalı. Kontrol: date komutu çalıştırın.

3. AWS CLI'yi Kurup Yapılandırın

   AWS.amazon.com'dan AWS CLI indirin ve kurun:

   aws --version ile kurulumu doğrulayın.

   Sonra yapılandırın: aws configure

   Sorular çıkacak – yanıtlayın:

   • AWS Access Key ID: Hesabınızdan alın (AWS Console > IAM > Users > Security Credentials)
   • AWS Secret Access Key: Aynı yerde bulunur
   • Default region: Örn., eu-west-1 (ECR repository'nizin bölgesini kullanın)
   • Output format: json yazın
4. ECR Token Alın ve Docker'a Giriş Yapın

   Terminal/CMD'de çalıştırın (AWS bölgesi EU-WEST-1 ise):

   aws ecr get-login-password --region eu-west-1 | docker login --username AWS --password-stdin ACCOUNT_ID.dkr.ecr.eu-west-1.amazonaws.com

   ACCOUNT_ID yerine AWS hesap numaranızı yazın (12 haneli) Örn.: 123456789012.dkr.ecr.eu-west-1.amazonaws.com

   Başarılı olursa: Login Succeeded mesajı göreceksiniz. Bu adımdan sonra ECR'ye erişebilirsiniz.

5. Docker Image Push/Pull Test Edin

   Eğer push yapacaksanız:

   docker tag LOCAL_IMAGE:tag ACCOUNT_ID.dkr.ecr.eu-west-1.amazonaws.com/REPO_NAME:tag

   docker push ACCOUNT_ID.dkr.ecr.eu-west-1.amazonaws.com/REPO_NAME:tag

   Eğer pull yapacaksanız:

   docker pull ACCOUNT_ID.dkr.ecr.eu-west-1.amazonaws.com/REPO_NAME:tag

   Hata çıkmazsa sorun çözülmüştür.

6. 12 Saatlik Token Sorunu için Otomatasyon

   Token 12 saatte süresi biterse yeniden giriş yapması gerekir. Bunu otomatikleştirmek için bir script oluşturun.

   Linux/Mac'te cron job ekleyin: crontab -e

   Şu satırı ekleyin (her 10 saatte bir çalıştır):

   0 */10 * * * aws ecr get-login-password --region eu-west-1 | docker login --username AWS --password-stdin ACCOUNT_ID.dkr.ecr.eu-west-1.amazonaws.com

   Windows'ta Görev Zamanlayıcı'da batch script oluşturun veya docker-credential-ecr-login ek aracını kurun (kalıcı çözüm).

7. IAM İzinlerini Kontrol Edin

   AWS Console > IAM > Kullanıcılar > İlgili kullanıcı > Permissions sekmesi açın. Şu policy'ler ekli olmalı:

   AmazonEC2ContainerRegistryPowerUser (push/pull için) veya

   AmazonEC2ContainerRegistryReadOnly (sadece pull için)

   Eksikse Add Permission > Attach policies > Search "ECR" > İlgili policy seçin.

8. Region Uyuşmasını Kontrol Edin

   AWS Console'da hangi bölgede ECR repository oluşturdunuz? Örn., Ireland (eu-west-1).

   AWS CLI komutunda --region eu-west-1 yazırken aynı bölgeyi kullanın. Bölge yanlışsa "repository not found" hatası çıkar.

9. Firewall/Proxy Arkasındaysanız

   Docker daemon'ı proxy'nin ardından çalışıyorsa Docker'ı yapılandırın:

   Windows/Mac: Docker Desktop > Settings > Resources > Proxies > Manual proxy configuration etkinleştir, HTTP ve HTTPS proxy adresini gir.

   Linux'te: /etc/docker/daemon.json dosyasını düzenle, proxy ayarları ekle, sudo systemctl restart docker çalıştır.

Servis/Teknisyen Ne Zaman Gerekir?

Yukarıdaki adımlar sonrası hata devam ediyorsa:

• AWS hesabınızda ödeme sorunu varsa (suspended), AWS Support ile iletişime geçin.
• Kurumsal network'te ise ve proxy/SSL (SSL sertifika güvenliği) sorunları çıkıyorsa, şirket IT ekibine haber verin.
• Docker daemon özellikleri ile ilgili sorun (Linux'te daemon.json çakışması) varsa, sistem yöneticisine sorun.

Kendi özel Linux sunucusu/VPS'te çalışıyorsanız ve sorun gidermezse, sunucu sağlayıcının teknik desteğinden yardım isteyin.

Önleyici İpuçları

• AWS Anahtarlarını Gizli Dosyada Saklayın: `~/.aws/credentials` dosyasında saklanır. Asla GitHub'a commit etmeyin. `.gitignore`'a ekleyin.
• IAM Rol Kullanın: Access Key yerine EC2/ECS sunucusu çalıştırıyorsanız IAM role (kRole) atayın. Token otomatik yenilenir.
• Düzenli Anahtar Rotasyonu: Her 90 gün Access Key'inizi yenileyin. AWS Console > IAM > Security Credentials sekmesinde yapın.
• Dedicate Kullanıcı Oluşturun: Root hesabı yerine ECR-only izni olan IAM kullanıcısı yaratın. Güvenlik artar.
• System Saatini Düzenli Kontrol Edin: NTP (Network Time Protocol) aktif tutun. Bulut ortamında saat kayması çok olur.
• Region'u Belgeyin: Proje README'sinde ECR bölgesini yazın. Takım içinde karışıklık önler.