On every deploy, the platform sends your Node.js process SIGTERM and, after a grace period, SIGKILL. If the process exits immediately, requests in progress fail; if it calls server.close() and waits, idle keep-alive connections can hold it open until the kill. A graceful shutdown does four things in order: fail the readiness check and wait a few seconds so the load balancer stops sending traffic; stop accepting connections and close idle keep-alive sockets; let in-flight requests finish; and force-close whatever remains before the platform's deadline. Here's a tested implementation with node:http and nothing else.

Why isn't server.close() enough?

server.close() stops new connections and waits for existing ones to end. Two problems:

  • Keep-alive. Clients reuse connections, and on Node.js 18 an idle keep-alive socket keeps close() waiting with nothing actually happening. Node.js 19 and later close idle connections as part of close(); calling closeIdleConnections() explicitly is harmless there and covers older versions.
  • Requests that never end. A hung upstream call or a long stream keeps its connection busy, so close() never completes on any version without a deadline.
  • Traffic still arriving. In Kubernetes, the pod is removed from the Service's endpoints at roughly the same time as SIGTERM is sent, not before. For a few seconds, load balancers and other nodes still route new requests to a pod that has stopped listening. Those requests fail.

The shutdown

```js title="shutdown.mjs: app"
import { createServer } from "node:http";

export function createApp(handler) {
const state = { ready: true };
const server = createServer((req, res) => {
if (req.url === "/readyz") {
res.writeHead(state.ready ? 200 : 503).end(state.ready ? "ok" : "shutting down");
return;
}
if (!state.ready) res.setHeader("Connection", "close"); // tell keep-alive clients to reconnect elsewhere
handler(req, res);
});
return { server, state };
}

 ```js title="shutdown.mjs: shutdown" export async function shutdown( { server, state }, { drainDelayMs = 5_000, timeoutMs = 20_000, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {} ) { state.ready = false; // 1. readiness fails; keep serving while the load balancer notices await sleep(drainDelayMs); const closed = new Promise((resolve) => server.close(resolve)); // 2. stop accepting server.closeIdleConnections(); // and drop idle keep-alive sockets const timer = setTimeout(() => server.closeAllConnections(), timeoutMs); // 4. hard deadline await closed; // 3. in-flight requests finish clearTimeout(timer); } process.on("SIGTERM", async () => { await shutdown(app); process.exit(0); }); 

closeIdleConnections() and closeAllConnections() are built into http.Server since Node.js 18.2. During the drain delay the server still answers, but adds Connection: close, so clients reconnect, and their next connection goes to a pod that's still ready.

The timing

The numbers have to fit inside the platform's grace period (Kubernetes' terminationGracePeriodSeconds defaults to 30 seconds):

Phase Example Must cover
Drain delay 5 s Endpoint removal reaching every load balancer
In-flight requests, up to 20 s Your slowest normal request
Margin before SIGKILL 5 s Exit, flushing logs

An LLM endpoint streaming long answers may need a longer timeout, and so a longer grace period; set both together. A preStop hook that sleeps achieves the same drain delay without code, but it only helps if readiness isn't still reporting healthy, so the in-process version above covers both.

Do the tests pass?

The tests start a real server on a random port:

```js title="shutdown.test.mjs"
// An idle keep-alive socket is open, and a 300 ms request is in flight when shutdown starts.
const keepAlive = new Agent({ keepAlive: true });
await get(port, "/fast", keepAlive);
const inflight = get(port, "/slow");
const done = shutdown(app, { drainDelayMs: 100, timeoutMs: 5_000 });

assert.equal((await get(port, "/readyz")).status, 503); // readiness fails at once
assert.equal((await get(port, "/fast")).connection, "close"); // still served during the drain, told to reconnect
assert.equal((await inflight).body, "done"); // the in-flight request completes
await done; // and the idle keep-alive socket didn't hold shutdown open
await assert.rejects(get(port, "/fast"), { code: "ECONNREFUSED" }); // after close, nothing new gets in

 A second test uses a handler that never responds: shutdown returns after the 200 ms timeout and the stuck client sees `ECONNRESET`, instead of the process waiting for `SIGKILL`. Both pass on Node.js 24, and the first shutdown completes in well under a second because the idle socket is closed immediately. ## What else should shut down? * **Background work.** Stop pulling new jobs from queues and finish or release the current ones. An [outbox relay](https://aliahmed.si/blog/transactional-outbox-nodejs-sqlite/) should finish its current event, not abandon it midway. * **Database pools and clients**, after the server has closed. * **Streaming responses.** SSE connections stay open by design, so they'll hit the hard timeout. Send a final event telling clients to reconnect; see [streaming SSE through a Next.js proxy](https://aliahmed.si/blog/nextjs-sse-proxy-streaming/). For where these processes run in the first place, see [the servers you deploy to](https://aliahmed.si/blog/servers-you-deploy-to/) and [what gets deployed to production](https://aliahmed.si/blog/what-gets-deployed-to-production/). ## Summary * `SIGTERM` arrives while traffic is still routed to you: fail readiness and wait a few seconds first. * `server.close()` plus `closeIdleConnections()`, so idle keep-alive sockets don't hold you open. * Let in-flight requests finish, but force `closeAllConnections()` before the grace period ends. * Fit the drain delay, request timeout and margin inside `terminationGracePeriodSeconds`. --- Written by Ali Ahmed · [Original article](https://aliahmed.si/blog/nodejs-graceful-shutdown-kubernetes/)