2026-11-03 · 10 min
Graceful Shutdown Node.js di Kubernetes: SIGTERM, preStop, Draining
Menjelang musim promo, tim biasanya sibuk menambah replika dan menaikkan limit. Sumber 502 saat deploy yang paling sering diremehkan justru bukan kapasitas, melainkan graceful shutdown Node.js di Kubernetes yang tidak dikerjakan: pod yang mati di tengah request saat deploy atau scale-down. Setiap rolling update dan setiap turunnya HPA adalah satu kesempatan untuk memutus checkout pelanggan yang sedang membayar.
Artikel ini membahas siklus hidup satu proses Node.js di Kubernetes, dari container sampai tuntasnya request terakhir. Ini melengkapi tulisan sebelumnya tentang blue-green deploy di VPS dengan nginx dan systemd. Di sana kita mengatur pergantian trafik di level server. Di sini fokusnya satu proses: bagaimana ia menerima sinyal berhenti, dan bagaimana ia berhenti tanpa memutus siapa pun.
Kenapa 502 muncul saat deploy: urutan graceful shutdown Node.js di Kubernetes
Memahami urutannya menghindarkan banyak tebakan. Ketika pod dihapus (rolling update, scale-down, node drain), Kubernetes melakukan dua hal secara paralel:
- Pod ditandai Terminating dan dicabut dari daftar endpoint Service. Perubahan ini harus menyebar ke kube-proxy dan ingress controller.
- Kubelet menjalankan preStop hook (jika ada), lalu mengirim SIGTERM ke PID 1 container.
Kata kuncinya adalah paralel. Tidak ada jaminan endpoint sudah tercabut di semua node ketika SIGTERM tiba. Jika aplikasi langsung menutup listener, sisa request yang masih diarahkan ke pod itu berujung connection refused atau reset, yang dilihat pengguna sebagai 502. Jika setelah terminationGracePeriodSeconds proses belum selesai, kubelet mengirim SIGKILL. Seluruh desain berikut adalah cara menghormati urutan ini.
Langkah 1: perbaiki masalah PID 1
Sebelum bicara handler, pastikan sinyalnya sampai. Di container, proses pertama adalah PID 1, dan Linux memperlakukannya khusus: tanpa handler eksplisit, SIGTERM tidak punya aksi default untuk PID 1. Dua jebakan klasik untuk sigterm nodejs docker:
# Salah: shell form, sinyal berhenti di /bin/sh
CMD npm start
# Juga bermasalah: npm tidak andal meneruskan sinyal
CMD ["npm", "start"]
# Benar: exec form, Node.js langsung menjadi PID 1
CMD ["node", "dist/server.js"]
Shell form membungkus perintah dengan /bin/sh -c, sehingga shell yang menjadi PID 1 dan Node.js hanya anaknya. Hasilnya, SIGTERM tidak pernah menyentuh aplikasi Anda dan pod mati lewat SIGKILL setelah grace period habis. Gejalanya khas: setiap deploy terasa lambat tepat 30 detik per pod.
Bila Anda memakai child process atau ingin pembersihan zombie process yang benar, tambahkan init kecil seperti tini:
RUN apk add --no-cache tini
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "dist/server.js"]
Untuk uji lokal, docker run --init memberi efek serupa. Di Kubernetes, tini di image adalah pilihan yang lebih portabel karena tidak bergantung pada runtime.
Langkah 2: handler SIGTERM untuk graceful shutdown Node.js yang menggagalkan readiness lebih dulu
Urutan di dalam handler penting. Jangan langsung server.close(). Pertama, tandai diri sebagai tidak siap supaya readiness probe gagal, lalu tunggu endpoint dicabut, baru berhenti menerima koneksi.
// server.js
import http from 'node:http';
import { app } from './app.js';
const server = http.createServer(app);
let shuttingDown = false;
// Dipakai readinessProbe: httpGet /ready
app.get('/ready', (req, res) => {
if (shuttingDown) return res.status(503).send('shutting down');
res.status(200).send('ok');
});
server.listen(3000);
async function shutdown(signal) {
if (shuttingDown) return;
shuttingDown = true;
console.log(JSON.stringify({ msg: 'shutdown_start', signal }));
// Timer pengaman: harus lebih pendek dari terminationGracePeriodSeconds
const force = setTimeout(() => {
console.error(JSON.stringify({ msg: 'shutdown_forced' }));
process.exit(1);
}, 25_000);
force.unref();
try {
await closeServer(server); // langkah 4
await drainWorkers(); // langkah 5
await closePools(); // langkah 5
process.exit(0);
} catch (err) {
console.error(err);
process.exit(1);
}
}
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
Perhatikan force.unref(): timer pengaman tidak boleh menahan proses tetap hidup bila semuanya sudah bersih. Dan nilainya (25 detik) sengaja di bawah grace period, supaya Anda yang memutuskan bagaimana proses berakhir, bukan SIGKILL.
Langkah 3: preStop sleep agar endpoint sempat dicabut
Readiness yang gagal pun butuh waktu untuk berefek. Cara paling sederhana dan paling banyak dipakai adalah kubernetes preStop hook berisi sleep singkat. Selama preStop berjalan, SIGTERM belum dikirim, dan pod tetap melayani request sambil endpoint disebarkan.
# deployment.yaml
spec:
template:
spec:
terminationGracePeriodSeconds: 45
containers:
- name: api
image: registry.example.com/api:1.8.2
ports:
- containerPort: 3000
readinessProbe:
httpGet: { path: /ready, port: 3000 }
periodSeconds: 2
failureThreshold: 1
lifecycle:
preStop:
sleep:
seconds: 10
Field sleep tersedia sebagai fitur bawaan Kubernetes pada versi yang lebih baru. Bila cluster Anda belum mendukungnya, gunakan exec: command: ["sleep", "10"], dengan catatan image harus memuat binary sleep (image distroless tidak punya). Sepuluh detik adalah titik awal yang lazim; ukur sendiri berapa lama ingress Anda menyebarkan perubahan endpoint, lalu tambahkan margin.
Hal yang sering terlewat: waktu preStop dihitung dalam grace period yang sama. Ia tidak menambah jatah. Karena itu angka 45 detik di atas bukan kebetulan, dan akan kita hitung di bagian akhir.
Langkah 4: server.close() dan koneksi keep-alive
Di sinilah banyak implementasi diam-diam bocor. server.close() berhenti menerima koneksi baru, tetapi callback-nya baru terpanggil setelah semua koneksi yang ada tertutup. Koneksi keep-alive yang idle bisa menahannya sampai timeout, sehingga shutdown tidak pernah selesai tepat waktu.
Sejak Node.js 19, server.close() otomatis menutup koneksi idle, dan server.closeIdleConnections() tersedia untuk kontrol eksplisit. Untuk versi sebelumnya atau perilaku yang lebih terukur, lakukan sendiri:
function closeServer(server) {
return new Promise((resolve, reject) => {
server.close((err) => (err ? reject(err) : resolve()));
// Tutup koneksi keep-alive yang sedang idle sekarang juga
server.closeIdleConnections();
// Koneksi yang masih memproses request diberi batas waktu,
// lalu dipaksa tutup agar shutdown tidak menggantung
setTimeout(() => server.closeAllConnections(), 15_000).unref();
});
}
Dua catatan praktis. Pertama, respons yang dikirim saat shutdown sebaiknya menyertakan header Connection: close supaya klien dan load balancer tidak memakai ulang koneksi itu; Anda bisa menambahkannya lewat middleware yang memeriksa flag shuttingDown. Kedua, server.keepAliveTimeout Node.js (default 5 detik) harus lebih besar dari idle timeout load balancer di depannya, kalau tidak Anda akan mendapat 502 sporadis yang tidak ada hubungannya dengan deploy. Itu masalah berbeda dengan gejala mirip, jadi cek keduanya.
Langkah 5: draining worker BullMQ dan pool database
API hanyalah separuh cerita. Proses yang menjalankan worker punya pekerjaan yang lebih berisiko diputus di tengah jalan.
import { Worker } from 'bullmq';
import { pool } from './db.js'; // pg.Pool
import { redis } from './redis.js';
const worker = new Worker('orders', processOrder, { connection: redis });
async function drainWorkers() {
// close() berhenti mengambil job baru dan menunggu job aktif selesai
await worker.close();
}
async function closePools() {
await pool.end(); // tunggu query yang berjalan, lalu lepas koneksi
await redis.quit(); // quit lebih santun daripada disconnect
}
Urutannya sengaja: server HTTP dulu (tidak ada request baru yang butuh DB), lalu worker (job aktif masih butuh DB), terakhir pool dan Redis. Membalik urutan ini menghasilkan error “pool is closed” di tengah job yang sebenarnya tinggal selesai.
Untuk BullMQ, worker.close() yang ditunggu memberi job aktif kesempatan tuntas. Jika proses tetap terkena SIGKILL, job dianggap stalled dan akan diambil ulang, artinya bisa berjalan dua kali. Jadikan job idempoten (kunci idempotensi, upsert, bukan insert buta), dan pastikan job terpanjang yang Anda izinkan muat di grace period. Untuk job yang memang panjang, pecah menjadi langkah-langkah kecil atau pertimbangkan worker di Deployment terpisah dengan grace period yang lebih besar.
Menghitung terminationGracePeriodSeconds
Jangan menebak. terminationGracePeriodSeconds adalah anggaran waktu, dan setiap tahap menarik dari anggaran yang sama:
| Komponen | Contoh |
|---|---|
| preStop sleep | 10 detik |
| Request terpanjang yang diizinkan selesai | 15 detik |
| Menutup worker dan pool | 5 detik |
| Margin | 5 detik |
| Total | 35 detik, dibulatkan menjadi 45 untuk pengaman |
Aturan pegangannya: timer paksa di aplikasi (25 detik pada contoh di atas, dihitung sejak SIGTERM) harus lebih kecil dari terminationGracePeriodSeconds dikurangi durasi preStop. Dengan preStop 10 detik dan grace period 45 detik, aplikasi punya sekitar 35 detik sejak SIGTERM, dan timer 25 detik masih aman.
Menguji sebelum musim promo
Jangan mengandalkan keyakinan. Jalankan beban ringan lalu paksa rolling update, dan lihat apakah ada respons non-2xx:
# Terminal 1: beban konstan, hitung status code
hey -z 90s -c 20 https://staging.example.com/api/health | grep -E "Status|\[5"
# Terminal 2: picu rolling update
kubectl rollout restart deployment/api
kubectl rollout status deployment/api
Targetnya nol 5xx selama rollout. Jika masih ada, periksa berurutan: apakah PID 1 menerima sinyal (log shutdown_start muncul?), apakah preStop cukup panjang, apakah keepAliveTimeout lebih besar dari idle timeout ingress, dan apakah ada log shutdown_forced. Setiap log itu menunjuk langsung ke satu langkah di atas.
Ringkasan
Untuk 502 saat deploy kubernetes, urutan perbaikannya bisa dihafal: pastikan Node.js menjadi PID 1 dengan exec form (dan tini bila perlu); gagalkan readiness saat SIGTERM; beri preStop sleep supaya endpoint sempat dicabut; tutup server dan koneksi keep-alive dengan batas waktu; drain worker lalu pool; dan hitung grace period dari komponen-komponennya. Semua ini sekali dikerjakan, lalu setiap deploy menjadi non-event. Itu persis yang Anda inginkan sebelum trafik promo datang.
Ditulis oleh Reza Pradipta