Docker Engine 29, rutin yükseltmeler yayıldıkça eski API client'larını sessizce kırıyor

Oleksandr Kuryzhev'in kendi blogundan dev.to'ya aktardığı bir yazı, üretim ortamındaki Docker hostlarını hazırlıksız yakalayan bir arıza modunu anlatıyor: gözetimsiz yükseltmeler gece yeni bir docker-ce paketi kuruyor, daemon yeniden başlıyor ve sabaha kadar geçen sürede bir reverse proxy artık container'ları keşfedemiyor. Proxy logları client API sürümünün çok eski olduğunu bildirirken, docker ps hâlâ shell'den çalışıyor. Daemon sağlıklı görünüyor; kopukluk ise etrafındaki client'larda.

Yazıya göre Docker Engine 29, 10 Kasım 2025'te yayımlandı ve bu sürüm hattı şu anda 29.9.3'e ulaştı; 29.x artık desteklenen Ubuntu sürümleri için Docker'ın apt deposunda sunuluyor. Hâlâ 28.x'te olan hostlar rutin yamalarla bu sürüme geçiyor ve yüzen (floating) paket kanalındaki her şey yeni major sürümü otomatik olarak alıyor.

Engine 29'da neler değişiyor

Docker'ın sürüm notlarından ve engine dokümantasyonundan yararlanan yazı, planlama yapmayı gerektiren dört değişiklik listeliyor ve ayrıntılar 29.x sürümleri arasında değiştiği için her birini hedeflenen yama sürümünün notlarına göre doğrulamayı öneriyor:

• Daemon artık minimum bir API sürümü zorunlu kılıyor; belgelenen taban sürüm 1.44 ve daha eski bir sürüm konuşan client'ları reddediyor. Bu, eskiyen reverse proxy'lere, izleme agent'larına, CI runner'lara ve sabitlenmiş Docker SDK'ları üzerine kurulu el yapımı scriptlere denk düşüyor.

• Yeni kurulumlarda containerd image deposu varsayılan oluyor. Mevcut hostların mevcut graph driver'larını koruyacağı belgelenmiş, ancak hostları image'lardan veya otomasyonla yeniden inşa eden ve klasik overlay2 düzenini bekleyen herkes risk altında.

• Deneysel bir nftables firewall backend'i, iptables'a alternatif olarak opt-in şekilde sunuluyor. Yalnızca bunu etkinleştiren hostlar etkileniyor; ancak yazı, bir güvenlik ekibinin nftables'a geçiş için baskı yapması durumunda bunun bilinmeye değer olduğunu vurguluyor.

• Live restore, major yükseltmeleri kapsamıyor. Belgelenen kapsamı yama düzeyinde daemon yükseltmeleri; dolayısıyla 29'a geçişte container'ların yeniden başlayacağı varsayılmalı.

Yalnızca aynı paket setinden gelen docker compose ve CLI'yı çalıştıran hostlar büyük ölçüde etkilenmiyor, çünkü client ve daemon birlikte hareket ediyor. Yazı ayrıca compose dosyalarının artık eski üst düzey version anahtarını bırakmış olması gerektiğini not ediyor.

Nasıl hazırlanılır

Yazının kısa özeti: paketi sabitleyin (pin), /var/run/docker.sock ile konuşan her client'ı envanterin ve önce bir kanarya host yükseltin. Pratikte bu şu anlama geliyor:

• Socket client'larının envanterini çıkarın; yani socket'i mount eden veya DOCKER_HOST kullanan her şeyi: proxy'ler, log toplayıcıları, CI agent'ları ve dağıtım araçları. Her aracın changelog'unda Docker API desteğini kontrol edin.

• Server sürümü, API sürümü, storage driver ve çalışan container listesiyle bir taban çizgisi kaydedin; böylece sonucu tahmin etmek yerine sonradan karşılaştırabilirsiniz.

• Herhangi bir şey kurmadan önce hostu load balancer'dan çıkarın, çünkü paket dockerd'yi yeniden başlatıyor ve live restore container'ları major sürüm geçişinde taşımayacak.

• Yapılandırmayı önceden hazırlayın; hedef daemon.json'ı ve varsa systemd drop-in'i önceden yazın, böylece kurulum sırasındaki yeniden başlatma bunları devralır.

• "latest" yerine açık bir sürüm dizesi kurun, ardından docker-ce, docker-ce-cli ve containerd.io paketlerini apt-mark ile sabitleyin.

Yapılandırma tarafında yazı, depolama katmanını açık hale getirmeyi, storage-driver'ı overlay2 olarak ayarlamayı ve containerd-snapshotter feature flag'ini false yapmayı öneriyor; böylece yeniden inşa edilen host, yerini aldığı gibi davranır ve image deposu yalnızca bilinçli olarak değişir. Bakım penceresinden önce yükseltilemeyen client'lar için, DOCKER_MIN_API_VERSION=1.24 ayarlayan bir systemd drop-in'i 1.44 öncesi client'ların bağlanmasını sağlıyor. Yazar bunu kesinlikle kullanımdan kaldırılmış bir yol üzerinde geçici bir köprü olarak çerçeveliyor ve ticket üzerinde bir kaldırma tarihi olduğunu belirtiyor.

Doğrulama ve geri alma

Doğrulama, taban çizgisiyle bir karşılaştırmadır: server 29.x raporlamalı, storage driver kaydedilenle eşleşmeli ve container listesi birebir aynı olmalı. Yazının vurguladığı ince bir nokta: daemon, API reddedilen yanıtları client'a döndürüyor ve bunları varsayılan log seviyesinde kaydetmeyebiliyor; dolayısıyla daemon journal'ında boş bir arama kanıt değildir. Her socket client'ın kendi loglarında "too old" hatalarını kontrol edin ve proxy'nin keşfedilen backend sayısını ile izleme agent'larının container metriklerini düşüş açısından izleyin.

Geri alma, paketlerin pin'ini kaldırıp --allow-downgrades ile önceki sabitlenmiş 28.x sürüm dizesini kurmak ve sonra yeniden pin'lemek anlamına geliyor. Yazı, major sürümler arası geri almanın diskteki her durum için temiz olacağının garanti edilmediği konusunda uyarıyor; bu yüzden önce bir VM veya volume snapshot'ı alınmalı, ancak büyük bir /var/lib/docker'nin snapshot'ının gerçek zaman ve depolama maliyeti olduğu da kabul ediliyor. Bunun çok pahalı olduğu yerlerde kanarya-önce yaklaşımı güvenlik ağı olur.

Geçişten sonra bir tuzak daha: klasik graph driver ile containerd image deposu image'ları ayrı tutuyor, dolayısıyla mevcut bir hostta containerd-snapshotter etkinleştirildiğinde, image'lar yeniden pull veya load edilene kadar docker images listesi boş görünür.

Neden önemli

Buradaki arıza imzası, alışılmışın tersine. docker ps çalışıyor, health check'ler geçiyor ve daemon iyi durumda; buna karşılık keşif, metrik toplama ve CI işleri, daemon'un artık kabul etmediği bir API sürümü konuştuğu için sessizce kötüleşiyor. Tetikleyici tipik olarak planlı bir geçiş değil, rutin bir yama. Paket sürümlerini sabitlemek, Docker socket'ine dokunan her şeyin envanterini tutmak ve önce bir kanarya host yükseltmek, gece yarısı sürprizini planlanmış ve geri alınabilir bir değişikliğe dönüştürüyor.