graceful shutdown을 어떻게 구현하나요?

Question

Accepted Answer

**graceful shutdown**은 종료 시그널을 받았을 때 서버를 깔끔하게 멈추는 것을 의미합니다. 진행 중인 요청을 끝내고, 연결(DB 등)을 닫고, 리소스를 해제하는 것이지, 갑자기 죽여 진행 중인 작업을 버리는 것이 아닙니다. 무중단 배포와 신뢰성에 필수적입니다.

## 갑작스러운 종료가 문제인 이유

```text
Without graceful shutdown, when the process is killed (deploy, scale-down, crash):
  ✗ In-flight requests are dropped → users get errors
  ✗ DB transactions left incomplete
  ✗ Connections not closed cleanly → leaks/locks
```

배포와 오토스케일링 중에 프로세스는 끊임없이 멈춥니다. 이를 깔끔하게 하는 것이 배포를 매끄럽게 만듭니다.

## 구현하기

```js
import http from "http";
const server = http.createServer(app);
server.listen(3000);

async function shutdown(signal) {
  console.log(`${signal} received — shutting down gracefully`);

// 1. Stop accepting NEW connections; finish existing ones
  server.close(async () => {
    // 2. This callback runs once all active requests have completed
    await db.end();            // close database pool
    await redis.quit();        // close other connections
    console.log("clean shutdown complete");
    process.exit(0);           // exit successfully
  });

// 3. Safety net: force-exit if cleanup hangs too long
  setTimeout(() => {
    console.error("forced shutdown — cleanup timed out");
    process.exit(1);
  }, 10_000).unref();
}

// Listen for termination signals
process.on("SIGTERM", () => shutdown("SIGTERM")); // sent by orchestrators (k8s, Docker)
process.on("SIGINT", () => shutdown("SIGINT"));   // Ctrl+C in dev
```

순서: 시그널 포착 → `server.close()`(새 연결 중단, 기존 연결 소진) → DB/Redis/기타 리소스 닫기 → 종료. **타임아웃 폴백**은 무언가 멈추면 강제 종료하여, 멈춘 연결이 종료를 영원히 막지 못하게 합니다.

## 시그널들

```text
SIGTERM → the standard "please terminate" signal from orchestrators on deploy/scale-down
SIGINT  → Ctrl+C (development)
SIGKILL → cannot be caught (force kill) — graceful shutdown can't help here
```

## 컨테이너 환경에서

```text
Kubernetes/Docker send SIGTERM, wait a grace period (e.g. 30s), THEN SIGKILL.
Your app must finish within that window → keep the shutdown timeout shorter.
Readiness probes should mark the pod unready so the load balancer stops sending traffic.
```

## 왜 중요한가

graceful shutdown은 프로세스가 일상적으로 멈추고 재시작되는 현대(특히 컨테이너화/오케스트레이션) 환경에서 **무중단 배포**와 신뢰할 수 있는 운영을 가능하게 합니다.

이것이 없으면 모든 배포나 스케일 다운이 진행 중인 요청을 버리고 데이터 불일치를 초래합니다.

시그널 포착 → 수신 중단 → 소진 → 리소스 닫기 → 종료 순서(타임아웃 안전망과 함께)를 구현하는 것은 프로덕션 준비가 된 Node 서비스의 특징이며, 자주 간과되지만 중요한 운영 고려사항입니다.