Docker Hub Pull Limiti: 429 Too Many Requests Hatası Nasıl Çözülür?

Docker Hub çekme limitleri

Belgelerdeki tablo, adil kullanım koşuluna bağlı olarak her kullanıcı türü için 6 saatlik çekme limitini verir:

Sunucu açısından en önemli satır sonuncusudur. Oturum açmamış bir sunucunun limiti kişiye değil IP adresine bağlıdır. Aynı IPv4 adresini ya da aynı IPv6 /64 alt ağını paylaşan tüm makineler aynı 100 çekmelik kotayı kullanır. Bu, bir CI ortamında ya da aynı çıkış adresini kullanan birçok sunucuda limitin beklenenden çok daha hızlı dolabileceği anlamına gelir.

Limitlerin yanında bir de adil kullanım politikası vardır. Belgelere göre aşırı veri aktarımı, çekme oranı veya veri depolama kısıtlamaya ya da ek ücretlere yol açabilir; Docker aşırı tüketim gösteren hesaplara kısıtlama uygulama hakkını saklı tutar.

Ne bir "pull" sayılır?

Limitin nasıl tüketildiğini anlamak, onu aşmamanın ilk adımıdır. Belgelerdeki tanım şöyledir:

• Bir Docker pull, hem bir sürüm kontrolünü (version check) hem de bunun sonucunda yapılan indirmeyi kapsar. İstemciye bağlı olarak docker pull, bir imaj veya etiketin varlığını indirmeden, yalnızca sürüm kontrolüyle doğrulayabilir.
• Sürüm kontrolleri kullanım ücretlendirmesine sayılmaz.
• Normal bir imajın çekilmesi, tek bir manifest için bir çekme sayılır.
• Çok mimarili (multi-arch) bir imajın çekilmesi, farklı her mimari için ayrı bir çekme sayılır.

Son madde sık gözden kaçar. Aynı imajın hem amd64 hem arm64 sürümünü çeken bir iş akışı iki çekme harcar. Çok platformlu imaj üretimi ve çekimi için multi-platform build yazısına bakabilirsiniz.

Oturum açarak limiti artırmak ve doğru hesaba yazdırmak

Çekmelerinizin doğru hesaba atfedilmesi için Docker Hub'da kimlik doğrulaması yapmanız gerekir. Docker Engine'i Docker Desktop olmadan çalıştırıyorsanız, yani tipik bir Linux VPS'teyseniz, terminalden docker login komutunu kullanırsınız. Kişisel erişim belirteci (personal access token, PAT) belgesine göre komutu Docker ID'nizle çalıştırır, parola sorulduğunda PAT'i yapıştırırsınız:

docker login --username <YOUR_USERNAME>

PAT, parolanızı kullanmadan Docker Hub'a giriş yapmanızı sağlar. Birden fazla belirteç oluşturabilir, parolanızı değiştirmeden birini iptal edebilirsiniz. Belgeler PAT'leri parola gibi korumanızı, bir kimlik bilgisi yöneticisinde saklamanızı ve asla kaynak koda eklememenizi ister. İki faktörlü doğrulama açıksa ya da SSO zorunluysa CLI parolanızı kabul etmez ve PAT gerekir. Belirteç oluştururken varsayılan depo izni Public Read-only'dir; yalnızca herkese açık imajları çeken bir sunucu için bu yeterlidir ve en az yetki ilkesine uyar. Kuruluşa ait otomasyon için belgeler kişisel hesaba bağlı olmayan kuruluş erişim belirteçlerini (OAT) önerir; OAT'lerin bireysel hesaplardan ayrı kendi kullanım limitleri vardır.

Swarm, CI ve üçüncü taraf platformlar

Swarm kullanıyorsanız Docker Hub kimlik doğrulaması için servis oluştururken --with-registry-auth bayrağını kullanmanız gerekir; Compose dosyasıyla stack dağıtıyorsanız docker stack deploy belgesine bakın. Bu konu docker stack deploy yazısında ele alınıyor. GitHub Actions ile imaj üretip gönderiyorsanız kimlik doğrulama için resmî login action kullanılır; ayrıntılar GitHub Actions CI/CD rehberinde.

Üçüncü taraf platformlarla ilgili bir not daha var: bu platformlar birçok kullanıcı için aynı IPv4 adresini ya da IPv6 /64 alt ağını kullanabilir. Oturum açmış olsanız bile tek bir adrese atfedilen çok sayıda çekme, kötüye kullanım limitine takılmanıza yol açabilir.

İki farklı 429 hatası

Docker Hub'da 429 yanıtı veren iki ayrı limit vardır ve çözümleri farklıdır. Çekme limiti aşıldığında Docker CLI'de ya da Docker Engine loglarında belgede gösterilen şu uzun mesaj görünür:

You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits

Belgelere göre bunun iki olası nedeni vardır: oturum açmış bir Personal kullanıcı olarak limitinizi doldurmuşsunuzdur ya da oturum açmadan IPv4 adresinizin veya IPv6 /64 alt ağınızın limitine ulaşmışsınızdır. Çözüm oturum açmak veya hesabı yükseltmek, ya da limitinizi kontrol edip azalmasını bekleyip yeniden denemektir.

İkinci hata kötüye kullanım limitidir (abuse rate limit) ve kısa bir "Too Many Requests" mesajıyla gelir. Bu limit web sayfaları, API'ler ve imaj çekmeleri dahil Docker Hub'a yapılan tüm istekleri kapsar, IPv4 adresi veya IPv6 /64 alt ağı başına uygulanır, hesap türünden bağımsız olarak herkese eşittir ve yüke göre değişse de dakikada binlerce istek mertebesindedir. Belgelerin önerdiği çözüm, Docker Hub'a erişen bozuk CI/CD hatlarını bulup düzeltmek ve otomatik betiklerde dakikada binlerce istek göndermemek için geri çekilmeli (back-off) yeniden deneme uygulamaktır.

Kalan limitinizi görmek

Belgeler kalan çekme hakkınızı görmek için bir yöntem verir; bunun için curl ve jq kurulu olmalıdır. Önce bir belirteç alırsınız. Oturum açmadan çekiyorsanız anonim belirteç alınır; oturum açarak çekiyorsanız aynı istek kullanıcı adı ve parolayla yapılır:

TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)

Ardından limit bilgisini taşıyan başlıkları istersiniz. Bu başlıklar hem GET hem HEAD isteklerinde döner, ama arada kritik bir fark vardır: GET gerçek bir çekmeyi taklit eder ve limitten düşer, HEAD ise düşmez. Bu yüzden belgelerdeki komut --head kullanır:

curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest

Belgelerdeki örnek yanıtta şu başlıklar görünür:

ratelimit-limit: 100;w=21600
ratelimit-remaining: 20;w=21600
docker-ratelimit-source: 192.0.2.1

Bu örnekte limit 21600 saniyede (6 saat) 100 çekmedir ve 20 çekme hakkı kalmıştır. docker-ratelimit-source limitin hangi kaynağa, burada bir IP adresine, uygulandığını gösterir. Hiç ratelimit başlığı görmüyorsanız belgelere göre bunun birkaç nedeni olabilir: imaj veya IP adresiniz bir yayıncı, sağlayıcı ya da açık kaynak kuruluşuyla ortaklık kapsamında sınırsızdır ya da çektiğiniz kullanıcı ücretli bir aboneliğin parçasıdır. Bu durumda o imajı çekmek limitinize sayılmaz.

Oturum açmış hesaplar için Docker Hub'daki kullanım sayfası aylık çekmeleri gösterir ve ayrıntılı bir CSV raporu e-postayla gönderilebilir. Raporda datehour, repository, access_token_name, ips, tag, version_checks ve pulls gibi sütunlar bulunur; hangi otomasyonun ya da hangi IP'nin en çok çekme yaptığını bu sütunlardan çıkarabilirsiniz.

Compose'da pull_policy ile gereksiz çekmeleri azaltmak

Sunucuda limitin en sık sebebi, her dağıtımda imajların gereksiz yere yeniden çekilmesidir. Compose'da servis düzeyindeki pull_policy bu davranışı belirler. Değerler şunlardır: always her seferinde çeker; never hiç çekmez ve yerel önbellekteki imaja güvenir, imaj yoksa hata verir; missing yalnızca imaj yerelde yoksa çeker; build imajı oluşturur; daily ve weekly son çekmenin üzerinden 24 saat veya 7 gün geçtiyse kayıt defterini kontrol eder; every_<süre> ise verdiğiniz süreye göre kontrol eder.

services:
  web:
    image: nginx:1.27-alpine
    pull_policy: daily
  cache:
    image: redis:7-alpine
    pull_policy: missing

Bu dosya docker compose config --quiet ile hatasız doğrulandı. missing, build tanımı kullanmayan servisler için zaten varsayılandır. Ancak belgedeki bir istisnaya dikkat edin: missing politikası kullanılsa bile latest etiketi her zaman çekilir. Etiket vermediğiniz bir image: nginx satırı latest anlamına geldiği için her dağıtımda bir çekme harcayabilir. Belirli sürüm etiketleri kullanmak hem limit hem öngörülebilirlik açısından daha iyidir; temel imaj seçimi ve etiket sabitleme için base image seçimi yazısına bakın.

Kullanımı azaltmanın diğer yolları

Docker Hub kullanımını iyileştirme belgesi şu adımları önerir: kullanım verisine bakarak en çok tüketen hesapları, yoğun saatleri ve en çok veri aktaran imajları belirlemek; sık erişilen depolarda önbelleklemenin iyileştirilip iyileştirilemeyeceğini değerlendirmek; CI/CD hatları gibi gereksiz çekme yapan otomasyonları yapılandırmak; aynalama veya CI/CD içi önbellekleme ile tekrarlanan çekmeleri azaltmak ve otomatik sistemleri yalnızca yeni bir imaj sürümü çıktığında çekecek şekilde ayarlamak.

Docker Hub için pull-through önbellek (registry mirror)

Ortamınızda birden fazla Docker sunucusu varsa her daemon yerelde olmayan imajları internetten, Docker Hub'dan çeker. Belgelerin önerdiği çözüm, yerel bir kayıt defteri aynası çalıştırıp tüm daemon'ları ona yönlendirmektir. Resmî Registry imajı bir pull-through önbellek olarak çalıştırılabilir: ilk istekte imajı Docker Hub'dan çekip yerelde saklar, sonraki istekleri kendi deposundan karşılar. Etiketle yapılan bir çekmede en güncel içeriğe sahip olup olmadığını uzak kaynaktan kontrol eder. Bunun için Registry yapılandırmasına bir proxy bölümü eklenir:

proxy:
  remoteurl: https://registry-1.docker.io
  username: [username]
  password: [password]

Daemon tarafında ayna /etc/docker/daemon.json içindeki registry-mirrors anahtarıyla kalıcı hale getirilir ve Docker yeniden yüklenir:

{
  "registry-mirrors": ["https://<my-docker-mirror-host>"]
}

Kullandığınız imaj kümesi iyi tanımlıysa belgeler daha basit bir alternatif de sunar: imajları elle çekip basit bir yerel özel kayıt defterine göndermek. İmajlarınızın tamamı kurum içinde üretiliyorsa Hub'ı hiç kullanmadan tamamen yerel kayıt defterine dayanmak en basit senaryodur. daemon.json düzenlemenin genel kuralları için daemon.json yapılandırma yazısına bakın.

Sık yapılan hatalar

• Üretim sunucusunda hiç oturum açmadan çalışmak. Limit IP başına uygulanır ve aynı adresi paylaşan her şey aynı kotayı tüketir.
• Kalan limiti kontrol ederken GET isteği kullanmak. GET gerçek bir çekme sayılır; belgelerdeki gibi HEAD kullanın.
• Etiketsiz image: satırları yazmak. latest etiketi missing politikasında bile her seferinde çekilir.
• Çok mimarili imajlarda gereksiz mimarileri çekmek; her mimari ayrı bir çekme sayılır.
• "Too Many Requests" hatasını çekme limiti sanıp hesabı yükseltmek. Bu kötüye kullanım limitidir; bozuk bir CI döngüsünü ya da yeniden deneme fırtınasını düzeltmek gerekir.
• Docker Hub parolasını betiklerde veya depoda tutmak. PAT kullanın ve onu bir kimlik bilgisi yöneticisinde saklayın.
• Disk temizliğinde docker image prune -a ile sık kullanılan imajları silip her dağıtımda yeniden çekmek. Temizlik stratejisi için Docker prune yazısına bakın.

Sık Sorulan Sorular

Limit ne zaman sıfırlanır?

Çekme limiti 6 saatlik bir pencere üzerinden hesaplanır; yanıt başlığındaki w=21600 değeri de bu 21600 saniyelik pencereyi gösterir. Limitinizi kontrol edip azalmasını bekledikten sonra yeniden deneyebilirsiniz.

docker login yaptım, yine de limit hatası alıyorum. Neden?

Ücretsiz Personal hesap da 6 saatte 200 çekmeyle sınırlıdır. Ayrıca aldığınız hata "Too Many Requests" ise bu çekme limiti değil, oturum açmış olsanız da uygulanan kötüye kullanım limitidir. Hangisi olduğunu hata mesajından ayırt edin.

Sürüm kontrolleri limitten düşer mi?

Hayır. Belgelere göre sürüm kontrolleri kullanım ücretlendirmesine sayılmaz. İndirme yapılan çekmeler ise sayılır.

Aynı sunucudaki her container ayrı çekme mi harcar?

Çekme imaj başına yapılır; imaj yerelde varsa ve Compose'un pull_policy değeri missing ise yeniden çekilmez. Aynı imajdan birden fazla container başlatmak ek indirme gerektirmez, ama latest etiketi ve always politikası bu tasarrufu ortadan kaldırır.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Docker öğrenme rehberi · Docker prune ve disk temizleme · Base image seçimi · daemon.json yapılandırma · GitHub Actions CI/CD