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 ofclose(); callingcloseIdleConnections()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
SIGTERMis 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/)
Top comments (0)