Docker Healthcheck untuk Kesiapan Layanan

Container berstatus berjalan belum tentu aplikasinya siap dipakai. Proses utama bisa tetap hidup saat database belum menerima koneksi, aplikasi masih memuat konfigurasi, atau endpoint web terus mengembalikan error. Tanpa pemeriksaan kesehatan, Docker hanya mengetahui bahwa proses container belum berhenti. Docker healthcheck menambahkan sinyal yang lebih berguna: apakah layanan benar-benar merespons pemeriksaan yang ditentukan.

Fitur ini berguna untuk server rumahan yang menjalankan beberapa layanan sekaligus. Status kesehatan membantu operator membedakan gangguan proses dari gangguan kesiapan aplikasi. Healthcheck juga dapat dipakai oleh Docker Compose untuk menunda layanan yang bergantung pada database sampai database dinyatakan sehat. Namun, healthcheck bukan sistem pemulihan otomatis dan tidak menggantikan pemantauan dari luar host.

Status berjalan dan status sehat berbeda

Docker memiliki status proses seperti running, exited, dan restarting. Container dengan status running berarti proses utama masih aktif. Status itu tidak menjamin aplikasi berfungsi. Sebagai contoh, server web dapat tetap hidup tetapi gagal membuka koneksi ke database. Demikian juga database dapat sedang melakukan pemulihan setelah restart, sementara prosesnya sudah berjalan.

Healthcheck menjalankan perintah di dalam container pada jeda tertentu. Jika perintah selesai dengan kode keluar nol, pemeriksaan dianggap berhasil. Kode selain nol menandakan kegagalan. Docker menampilkan hasilnya sebagai healthy, unhealthy, atau starting. Periode starting memberi waktu bagi aplikasi yang perlu melakukan inisialisasi sebelum diperiksa.

Pemeriksaan sebaiknya menguji fungsi yang memang penting bagi konsumen layanan. Untuk web server, pemeriksaan HTTP lokal dapat memastikan proses menerima permintaan. Untuk database, pemeriksaan dapat memanggil utilitas bawaan untuk menguji kesiapan menerima query. Hindari pemeriksaan yang sekadar mencari proses dengan ps: proses ada tidak berarti layanan dapat digunakan.

Menambahkan healthcheck pada Compose

Contoh berikut menambahkan pemeriksaan HTTP untuk layanan yang memiliki curl:

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://127.0.0.1/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

Sesuaikan alamat /health dengan endpoint yang benar-benar disediakan aplikasi. Image minimal tidak selalu berisi curl atau wget; pastikan alat yang dipakai tersedia. Bila aplikasi menyediakan perintah pemeriksaan internal, gunakan perintah tersebut agar pemeriksaan tidak bergantung pada paket tambahan.

interval menentukan jarak antar pemeriksaan. timeout membatasi lama satu perintah. retries menentukan jumlah kegagalan berurutan sebelum Docker menandai container unhealthy. start_period memberi toleransi saat proses baru mulai. Nilai terlalu pendek dapat menandai aplikasi sehat-sementara sebagai gagal, sedangkan nilai terlalu panjang membuat gangguan baru terdeteksi lambat.

Pemeriksaan harus ringan. Jangan menjalankan query mahal, mengunduh file besar, atau melakukan operasi yang mengubah data pada setiap interval. Healthcheck berjalan terus-menerus, sehingga perintah yang berat dapat menambah beban justru ketika server sedang sibuk.

Mengatur urutan layanan yang bergantung

Compose dapat menunggu kondisi sehat dari dependency sebelum membuat layanan lain. Contohnya, aplikasi dapat menunggu database:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: change-this-secret
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s

  app:
    image: example/app:latest
    depends_on:
      db:
        condition: service_healthy

Contoh ini menunjukkan pola konfigurasi, bukan rekomendasi untuk menyimpan rahasia secara langsung di file Compose. Gunakan mekanisme secrets atau environment yang sesuai dengan cara deployment Anda. Pastikan juga perintah pemeriksaan memakai user dan database yang memang dikonfigurasi.

depends_on dengan kondisi sehat mengatur kesiapan pada saat startup. Ini tidak berarti Compose akan terus mengatur ulang aplikasi setiap kali dependency kelak menjadi tidak sehat. Aplikasi tetap perlu menangani putusnya koneksi dan mencoba kembali dengan jeda yang wajar. Ketahanan pada tingkat aplikasi penting karena gangguan jaringan dan restart database dapat terjadi setelah semua container awalnya sehat.

Memeriksa hasil healthcheck

Gunakan perintah berikut untuk melihat status ringkas:

docker compose ps

Untuk melihat status dan keluaran pemeriksaan tertentu:

docker inspect --format '{{json .State.Health}}' nama-container

Keluaran healthcheck menyimpan beberapa hasil terakhir, termasuk kode keluar dan potongan output. Informasi itu membantu mencari penyebab seperti endpoint salah, perintah tidak tersedia, autentikasi gagal, atau aplikasi belum siap sebelum batas waktu.

Jika container menjadi unhealthy, periksa log aplikasi dan hasil pemeriksaan sebelum mengubah retries atau interval. Memperlonggar ambang tanpa memahami penyebab hanya menyembunyikan gejala. Jika perintah pemeriksaan gagal karena binary tidak ada, gunakan alat yang sudah tersedia atau buat pemeriksaan yang sesuai dengan image. Jika pemeriksaan gagal karena endpoint membutuhkan autentikasi, hindari menaruh kredensial sensitif langsung dalam argumen yang mudah terlihat.

Batasan dan praktik yang aman

Status unhealthy sendiri tidak otomatis me-restart container pada Docker Engine standar. Kebijakan restart seperti unless-stopped umumnya bereaksi ketika proses utama keluar, bukan semata-mata karena pemeriksaan kesehatan gagal. Jangan menganggap healthcheck sebagai pengganti alert, watchdog, atau prosedur pemulihan. Untuk layanan penting, pantau status dari host lain dan kirim notifikasi saat kegagalan bertahan melewati ambang tertentu.

Pilih pemeriksaan yang menguji kemampuan minimum layanan. Endpoint yang hanya menjawab status proses dapat memberi sinyal sehat meskipun integrasi penting rusak. Sebaliknya, pemeriksaan yang mengetes seluruh dependency pada setiap request dapat menyebabkan kegagalan berantai ketika satu komponen lambat. Tentukan cakupan yang jelas: apakah pemeriksaan menguji proses lokal, endpoint aplikasi, atau semua dependency kritis.

Setelah mengubah konfigurasi, validasi file sebelum menerapkannya:

docker compose config
docker compose up -d

Kemudian pantau sampai layanan melewati fase starting dan mencapai kondisi yang diharapkan. Uji juga skenario kegagalan secara terkendali di lingkungan yang aman. Misalnya, hentikan dependency sementara dan pastikan aplikasi mencatat error dengan jelas lalu dapat tersambung kembali. Jangan melakukan simulasi gangguan pada layanan produksi yang menyimpan data tanpa backup dan rencana pemulihan.

Healthcheck yang dirancang dengan tepat membuat status container lebih bermakna dan mengurangi tebakan saat troubleshooting. Mulailah dari pemeriksaan sederhana, gunakan endpoint atau utilitas bawaan, atur waktu sesuai karakter aplikasi, lalu kombinasikan dengan logging dan pemantauan eksternal. Hasilnya bukan jaminan layanan selalu tersedia, tetapi sinyal operasional yang jauh lebih baik daripada sekadar melihat bahwa container masih berjalan.

Ringkasan

Docker healthcheck mengukur kesiapan layanan, bukan hanya keberadaan proses. Gunakan pemeriksaan ringan dan spesifik, atur start_period, interval, timeout, serta retries sesuai kebutuhan. Untuk startup berurutan, gunakan depends_on dengan condition: service_healthy, tetapi tetap buat aplikasi tahan terhadap dependency yang gagal setelah startup. Periksa keluaran healthcheck dan jangan mengandalkan status unhealthy untuk memicu restart otomatis.