Docker HEALTHCHECK aslında neyi test eder: tek bir exit code ve sınırları

jtorchia'nın dev.to'da yayımlanan, aslen juanchi.dev'de yayınlanan bir yazı, Docker HEALTHCHECK'in gerçekte ne yaptığını açıklıyor: tam olarak tek bir soruya cevap veriyor — yapılandırdığınız komut, çalıştığı anda 0 exit code'uyla mı sonlandı. Mühendislerin "sağlık" hakkında varsaydığı diğer her şeyin bu komuta elle inşa edilmesi gerekiyor.

Komut gerçekte neyi çalıştırıyor

Docker'ın kendi dokümantasyonu HEALTHCHECK'i Docker'a bir container'ın "hâlâ çalışıp çalışmadığını" nasıl test edeceğini söylemenin bir yolu olarak tanımlıyor ve standart örneği, üç saniyelik timeout ile root path'e yapılan bir curl çağrısı. dev.to yazısının da belirttiği gibi, bu kontrol yalnızca tek bir şeyi kanıtlar: web sunucusu, timeout süresi içinde o path'te bir yanıt verdi. Veritabanının ayakta olup olmadığından, message queue worker'larının canlı olup olmadığından ya da uygulamanın bağımlı olduğu kimlik doğrulama servisinin yanıt verip vermediğinden hiçbir şey söylemez. Endpoint herhangi bir yanıt döndürürse — yanlış yapılandırılmış bir hata sayfası 200 status koduyla döndürülse bile — kontrol başarılı sayılır.

Docker hiçbir zaman yanıt gövdesini incelemez veya uygulama mantığını doğrulamaz. Sonucu yalnızca exit code belirler: 0 container'ı healthy, 1 unhealthy yapar ve 2 rezervedir. Sabit kodlanmış bir JSON payload'unu 200 status koduyla döndüren bir /health endpoint'i, arkasındaki gerçek uygulama mantığı bozuk olsa bile container'ı süresiz olarak healthy işaretleyecektir.

Liveness ile gerçek sağlık arasındaki fark

Yazının yaptığı ayrım, yüzeysel liveness ile gerçek sağlık arasındaki ayrımdır. Liveness kontrolü, sürecin yanıt verdiğini doğrular: takılmamıştır, sonsuz bir döngüye kilitlenmemiştir, port dinlemektedir. Docker'ın dokümantasyonu özelliği tam olarak bu şekilde çerçeveler ve sunucu süreci hâlâ çalışırken yeni bağlantıları artık kabul edemeyecek şekilde döngüye takılı kalmış bir web sunucusu örneğini gösterir.

Kapsamın tamamı budur. Süreç yanıt veriyor ama veritabanı bağlantısını kaybetmişse, yalnızca root path'e curl atan bir kontrol bunu asla fark edemez — sunucu o path'te 200 döndürmeye devam ederken uygulamaya yapılan her gerçek istek başarısız olur. docker ps'teki healthy durumu, tek bir faydalı işlemi bile tamamlayamayan bir uygulamayla bir arada var olabilir.

start_period ve retries

İki HEALTHCHECK seçeneği, Docker'ın bir container'ı unhealthy olarak işaretlemadan önce ne kadar sabırlı olacağını kontrol eder: --start-period ve --retries. Yazının dayandığı dokümantasyona göre, başlangıç dönemindeki başarısızlıklar retry sayısına dahil edilmez ve bu, yavaş açılan container'lara initialization için alan tanır. Ancak ince bir nokta var: başlangıç döneminde kontrol bir kez bile başarılı olursa, container başlamış sayılır ve bu noktadan itibaren art arda gelen her başarısızlık gerçekten sayılır.

Bunun sonucu olarak, kısa bir start_period ile yavaş açılan bir uygulamanın birleşimi, "hâlâ başlıyor" durumunu gerçek bir başarısızlık olarak yeniden sınıflandırabilir ve yanlış bir unhealthy durumu üretebilir. Doğru değerler tamamen uygulamanın gerçek bootstrap süresine bağlıdır — her image için işe yarayan evrensel bir ayar yoktur.

İyi bir kontrolün bile ölçemediği şeyler

Yazı, hiçbir HEALTHCHECK komutunun tek başına kurtulamayacağı sınırları listeliyor:

• Komutun hiç dokunmadığı harici bağımlılıklar. Veritabanını sorgulamıyorsa, healthcheck onun hakkında hiçbir şey bilmez.
• Kısmi bozulma. Timeout içindeki yavaş bir yanıt, anlık bir yanıtla tamamen aynı şekilde geçer; exit code'un gradyanları yoktur.
• İş durumu. Kontrol yalnızca HTTP status'u doğruluyorsa, bozuk veya boş içerikle dönen 200 yanıtı geçer.
• Container dışındaki her şey. HEALTHCHECK onun içinde çalışır; dolayısıyla komut doğrudan sorgulamadıkça host'u, daha geniş ağı veya komşu container'ları göremez.

Bu boşlukların her biri, Docker'ın sonucu yorumlama şeklini değiştirerek değil, kontrole mantık eklenerek kapatılır. Kontrolün bir servisin gerçek durumunu yansıtması gerekiyorsa, emek aralıkları veya retry sayılarıyla uğraşmak yerine, önemli bağımlılıkları gerçekten test eden bir endpoint veya script yazmaya harcanmalıdır.

Neden önemli

Sağlık durumu gerçek operasyonel kararlara beslenir: orchestrator'lar, load balancer'lar ve docker ps okuyan herkes "healthy" durumuna güvenilmeye değer bir sinyal olarak davranır. dev.to yazısının temel uyarısı, bu sinyalin yalnızca arkasındaki komut kadar derin olduğudur. Yeşil bir durum, "süreç bir portta yanıt verdi" anlamından fazlasını taşımayabilir. Container teslim eden ekipler HEALTHCHECK'i bir garanti değil bir mekanizma olarak görmeli ve veritabanı bağlantılarını, queue'ları ve kritik harici servisleri gerçekten test eden kontrol scriptlerine yatırım yapmalıdır — ya da status kolonunun, kelimenin çağrıştırdığından çok daha dar bir şeyi ölçtüğünü kabul etmelidir.