쿠버네티스 실습: Liveness와 Readiness Probe로 헬스체크 적용하기

쿠버네티스 실습: Liveness와 Readiness Probe로 헬스체크 적용하기

앞선 글에서는 Loki + Grafana로 로그 수집 및 모니터링 환경을 구축했습니다.
이번 글에서는 쿠버네티스의 헬스체크(Probe) 기능을 적용해 Pod가 죽었는지, 준비됐는지를 자동으로 감지하고 관리하는 방법을 실습합니다.

---

1) 왜 헬스체크가 필요한가?

쿠버네티스는 기본적으로 Pod가 실행 중인지(Running) 여부만 확인합니다.
하지만 애플리케이션 내부 상태까지 알 수는 없습니다.
예를 들어:

• 프로세스는 살아 있지만 DB 연결이 끊겼을 때
• 서버는 실행됐지만 초기 부팅이 아직 끝나지 않았을 때

이럴 때 헬스체크 Probe가 필요합니다.

---

2) Probe의 종류

• Liveness Probe:
  애플리케이션이 살아 있는지 확인. 실패하면 컨테이너를 재시작.
• Readiness Probe:
  요청을 받을 준비가 됐는지 확인. 실패하면 Service의 엔드포인트에서 제외.
• Startup Probe:
  애플리케이션의 초기 시작 시간이 긴 경우, 시작이 끝날 때까지 다른 Probe 실행을 지연.

---

3) NestJS Deployment에 Probe 추가하기

nestjs-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nestjs-deployment
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nestjs
  template:
    metadata:
      labels:
        app: nestjs
    spec:
      containers:
      - name: nestjs
        image: <DOCKER_USERNAME>/nestjs-app:latest
        ports:
        - containerPort: 3000
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 10
          periodSeconds: 10
          failureThreshold: 3
        readinessProbe:
          httpGet:
            path: /ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5
          failureThreshold: 3

---

4) NestJS에 헬스체크 엔드포인트 추가

NestJS 프로젝트에 @nestjs/terminus 라이브러리를 사용해 /health, /ready 엔드포인트를 만듭니다.

npm install @nestjs/terminus @nestjs/axios

app.module.ts

import { Module } from '@nestjs/common';
import { TerminusModule } from '@nestjs/terminus';
import { HealthController } from './health.controller';

@Module({
  imports: [TerminusModule],
  controllers: [HealthController],
})
export class AppModule {}

health.controller.ts

import { Controller, Get } from '@nestjs/common';
import { HealthCheck, HealthCheckService, HttpHealthIndicator } from '@nestjs/terminus';

@Controller()
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private http: HttpHealthIndicator,
  ) {}

  @Get('health')
  @HealthCheck()
  checkLiveness() {
    return this.health.check([]);
  }

  @Get('ready')
  @HealthCheck()
  checkReadiness() {
    // DB나 Redis 체크도 추가 가능
    return this.health.check([
      () => this.http.pingCheck('nestjs-app', 'http://localhost:3000'),
    ]);
  }
}

---

5) 배포 및 확인

반응형

적용:

kubectl apply -f nestjs-deployment.yaml

Pod 상태 확인:

kubectl get pods

자세히 보기:

kubectl describe pod <POD_NAME>

출력에서 Liveness와 Readiness Probe 결과를 확인할 수 있습니다.

---

6) 테스트 (강제로 실패 상황 만들기)

Pod 내부에서 /ready 엔드포인트를 의도적으로 에러를 반환하도록 수정하면, 쿠버네티스는 해당 Pod를 Service에서 제외합니다.
/health가 실패하면 컨테이너를 재시작합니다.

---

7) 정리

• Liveness Probe → 컨테이너가 죽으면 자동 재시작
• Readiness Probe → 준비되지 않은 Pod는 트래픽에서 제외
• Startup Probe → 시작 시간이 긴 앱의 안정적 구동 보장

이제 쿠버네티스가 단순히 실행 여부만이 아니라, 실제 애플리케이션의 정상 동작 상태까지 자동 관리할 수 있게 되었습니다.

다음 글에서는 리소스 관리 (Requests & Limits)와 Pod QoS Class를 다루어, 쿠버네티스가 CPU/메모리를 효율적으로 사용하는 방법을 실습하겠습니다.

---

 

쿠버네티스,LivenessProbe,ReadinessProbe,NestJS헬스체크,DevOps,애플리케이션모니터링,Minikube,컨테이너안정성,K8s실습,클라우드네이티브

 

 

보완해야 할 핵심 항목

1. Helm 설치 및 Loki Stack 설정 방식 (더 깔끔한 구성)

• loki-stack Helm 차트를 사용할 때는 --set promtail.enabled=true를 명시하는 것이 좋습니다. promtail.enabled가 기본값으로 true일 수도 있지만, 명백히 지정하면 실수 방지에 효과적입니다.(Artifact Hub)
• helm upgrade --install loki grafana/loki-stack \ --namespace monitoring --create-namespace \ --set grafana.enabled=true,promtail.enabled=true,prometheus.enabled=true

---

2. Grafana 로그인 계정 안내

• Loki Stack 설치 시, Grafana의 기본 로그인 정보는 admin / prom-operator 입니다.
  많은 원문에서는 admin/admin이라고 안내하지만, loki-stack 기반 Helm 차트에서는 기본 패스워드가 prom-operator인 경우가 많습니다.
  (Stack Overflow, GitHub)

---

3. 네임스페이스 일관성 유지

• 예시에서는 --namespace monitoring을 사용했는데, 일부 설명에서는 loki-stack 등의 네임스페이스가 언급될 수 있습니다.
  혼동을 피하려면 문서 전반에 하나의 네임스페이스 (예: monitoring)로 통일해서 사용하는 게 좋습니다.
  (Artifact Hub)

---

4. Grafana 비밀번호 확인 방법

• 설치 후 Grafana 패스워드가 헷갈린다면, 아래 명령어로 Kubernetes Secret에서 실제 패스워드를 확인할 수 있습니다:(Artifact Hub)
• kubectl get secret -n monitoring loki-grafana -o jsonpath="{.data.admin-password}" | base64 --decode

---

5. Grafana Persistence 설정 권장 (Minikube 실습 지속성 확보)

• 기본 설정은 Grafana 서버가 재시작될 때 저장된 데이터가 사라지는 ephemeral storage 기반입니다.
  실습 중에도 Dashboard 설정이나 데이터를 유지하려면, persistence.enabled=true와 같은 설정을 이용해 PersistentVolume를 사용하는 것을 권장드립니다.
  (Grafana Labs)

---

요약 테이블

항목 권장 보강 사항

Helm 설치 시 promtail 명시	--set promtail.enabled=true 명시
Grafana 기본 패스워드	admin / prom-operator로 안내
네임스페이스 통일	monitoring 등으로 일관성 유지
비밀번호 확인 방법	secret에서 직접 확인 (kubectl get secret...)
Grafana Persistence	persistence.enabled=true로 설정 권장

---