---
id: backend-health-check-patterns
title: Health Check — Liveness vs Readiness
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [backend, health, kubernetes, observability, vibe-coding]
tech_stack: { language: "Any backend / Kubernetes", applicable_to: ["Backend"] }
applied_in: []
aliases: [liveness probe, readiness probe, startup probe, /healthz]
---

# Health Check — Liveness vs Readiness

> 두 종류 — **Liveness = "살아있나? 죽었으면 재시작"**, **Readiness = "트래픽 받을 준비됐나? 안 됐으면 LB에서 빼라"**. 두 개를 같은 endpoint 로 하면 cascading failure.

## 📖 핵심 개념
- **Liveness**: 프로세스 자체. 단순. 외부 의존성 검사 X.
- **Readiness**: 트래픽 처리 가능. DB / 캐시 / 의존 서비스 검사 OK.
- **Startup**: 초기화 오래 걸리는 앱용. liveness 무시 기간.

## 💻 코드 패턴

### Express 기준
```ts
let isReady = false;

app.get('/healthz', (req, res) => res.status(200).json({ status: 'ok' })); // liveness

app.get('/ready', async (req, res) => {
  if (!isReady) return res.status(503).json({ ready: false });
  const checks = await Promise.allSettled([
    pingDB(),       // 1s timeout
    pingRedis(),
    pingDownstream(),
  ]);
  const failed = checks.filter(c => c.status === 'rejected');
  if (failed.length > 0) {
    return res.status(503).json({ ready: false, failed: failed.length });
  }
  res.status(200).json({ ready: true });
});

// 부팅 끝나면
async function bootstrap() {
  await db.connect();
  await loadCaches();
  await warmup();
  isReady = true;
}

// graceful shutdown
process.on('SIGTERM', async () => {
  isReady = false;          // LB 빼지게
  setTimeout(async () => {  // 진행 중 요청 처리 후 종료
    await db.disconnect();
    process.exit(0);
  }, 30_000);
});
```

### Kubernetes manifest
```yaml
livenessProbe:
  httpGet: { path: /healthz, port: 8080 }
  periodSeconds: 30
  failureThreshold: 3
  timeoutSeconds: 1
readinessProbe:
  httpGet: { path: /ready, port: 8080 }
  periodSeconds: 5
  failureThreshold: 2
  timeoutSeconds: 3
startupProbe:
  httpGet: { path: /healthz, port: 8080 }
  periodSeconds: 10
  failureThreshold: 30   # 5분 init 허용
```

### Detailed health (옵션)
```ts
app.get('/health/detail', async (req, res) => {
  const [db, redis, queue] = await Promise.allSettled([dbCheck(), redisCheck(), queueCheck()]);
  res.status(200).json({
    db: db.status === 'fulfilled' ? db.value : 'down',
    redis: redis.status === 'fulfilled' ? redis.value : 'down',
    queue: queue.status === 'fulfilled' ? queue.value : 'down',
    version: process.env.GIT_SHA,
    uptime: process.uptime(),
  });
});
```

## 🤔 의사결정 기준
| 의존 | Readiness 포함 |
|---|---|
| 핵심 DB (없으면 절대 안 됨) | ✅ |
| 보조 서비스 (analytics, search) | ❌ — degraded 모드 |
| 외부 SaaS (이메일 provider) | ❌ — 큐로 흡수 |
| Cache (Redis) | 보통 ❌ — fallback to DB |
| 의존 마이크로서비스 | depends — 핵심이면 ✅ |

## ❌ 안티패턴
- **Liveness 가 DB ping**: DB 일시 장애 → 모든 pod 재시작 → 폭주. liveness 는 프로세스만.
- **Readiness 가 너무 무거움**: probe 자체가 부하. 캐시 + 짧은 timeout.
- **graceful shutdown 없음**: SIGTERM 즉시 죽음 → 진행 중 요청 cut. preStop hook + drain.
- **probe timeout = period**: 마지막 호출이 끝나기 전 다음 호출 → 누적.
- **dependency 트리 따라 cascading liveness**: A 가 B 보고, B 가 C 보면 C 일시 장애가 A 까지 재시작.
- **버전 / git SHA 노출 안 함**: 어떤 빌드가 도는지 디버깅 어려움.
- **public / private 구분 안 함**: 외부 노출 시 정보 누설. internal /metrics 와 분리.

## 🤖 LLM 활용 힌트
- liveness = simple, readiness = dependency-aware 분리.
- SIGTERM → readiness false → drain → exit 표준 시퀀스.

## 🔗 관련 문서
- [[Backend_Circuit_Breaker]]
- [[Observability_RED_USE_Metrics]]