Kubernetes Liveness / Readiness Probe로 헬스 체크하기

쿠버네티스는 컨테이너가 정말 살아 있는지, 그리고 외부 요청을 받아도 되는 상태인지 자동으로 체크할 수 있는 기능을 제공한다.
핵심은 두 가지 프로브다.

• Liveness Probe: 컨테이너가 살아 있는가
• Readiness Probe: 트래픽을 받을 준비가 되었는가

---

1. Health Check 개념 정리

1-1. Liveness Probe

컨테이너가 죽지는 않았지만 응답이 멈춘 상태가 될 수 있다.
예를 들어:

• 무한 루프에 빠짐
• 스레드 데드락
• 내부 에러로 더 이상 정상 동작하지 않음

이런 상황을 Liveness Probe가 체크한다.

• Liveness Probe 실패 → Kubernetes가 컨테이너를 자동 재시작
• 목적: 죽어버린 애플리케이션을 다시 살리는 것에 가깝다

1-2. Readiness Probe

애플리케이션이 살아 있어도, 아직 요청을 받으면 안 되는 상태일 수 있다.

• 초기 로딩 중
• DB 연결 준비 중
• 캐시 warm-up 중
• 일시적으로 과부하 상태

이때 Readiness Probe가 실패하면:

• 그 Pod는 서비스 엔드포인트에서 제외
• 즉, 트래픽이 들어가지 않도록 차단

Liveness Probe와 달리, Readiness 실패는 재시작이 아니라 트래픽 차단에 초점이 있다.

1-3. 두 프로브의 차이 한눈에

항목	Liveness Probe	Readiness Probe
질문	컨테이너가 살아 있는가	트래픽을 받을 준비가 되었는가
실패 시 동작	컨테이너 재시작	서비스 엔드포인트에서 제외
용도	먹통이 된 프로세스 강제 복구	준비 안 된 Pod로 트래픽 들어가는 것 방지
서비스 영향	재시작 동안 잠깐 영향 있을 수 있음	트래픽 라우팅에만 영향

---

2. 예제 Deployment로 보는 Liveness / Readiness Probe

2-1. 기본 Deployment 설정 예시 (vue006dep.yml)

아래 예시는 Vue 앱 컨테이너에 HTTP 기반 Liveness / Readiness Probe를 설정한 것이다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vue006dep
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vue006kube
  template:
    metadata:
      labels:
        app: vue006kube
    spec:
      containers:
        - name: vue-container
          image: limu810/k8s-vue-ing:latest
          ports:
            - containerPort: 80

          # 살아 있는지 확인
          livenessProbe:
            httpGet:
              path: /
              port: 80              # 8080으로 바꾸면 실패 테스트 가능
            initialDelaySeconds: 5  # 컨테이너 시작 후 5초 뒤부터 검사
            periodSeconds: 5        # 5초마다 검사
            failureThreshold: 1     # 1번만 실패해도 재시작

          # 트래픽 받을 준비 됐는지 확인
          readinessProbe:
            httpGet:
              path: /
              port: 80              # 8080으로 바꾸면 실패 테스트 가능
            initialDelaySeconds: 3  # 컨테이너 시작 후 3초 뒤부터 검사
            periodSeconds: 5        # 5초마다 검사
            failureThreshold: 1     # 1번 실패 시 Ready 상태 해제

주요 필드 의미:

• httpGet.path: 프로브가 요청을 보낼 경로
• httpGet.port: 검사에 사용할 컨테이너 포트
• initialDelaySeconds: 컨테이너 시작 후 처음 체크까지 대기 시간
• periodSeconds: 체크 주기
• failureThreshold: 연속 실패 허용 횟수

2-2. Service 설정 예시 (vue006ser.yml)

apiVersion: v1
kind: Service
metadata:
  name: vue006ser
spec:
  type: ClusterIP
  ports:
    - port: 8000      # 서비스 포트
      targetPort: 80  # 컨테이너 포트
  selector:
    app: vue006kube

서비스는 app: vue006kube 레이블을 가진 Pod를 찾아, 그중 Ready인 Pod로만 트래픽을 보낸다.

---

3. 정상 포트(80)로 동작 확인

3-1. 리소스 적용

기존 리소스가 있다면 먼저 정리하고 진행하는 편이 깔끔하다.

# 필요 시 네임스페이스 내 리소스 정리
kubectl delete deployment vue006dep
kubectl delete service vue006ser

# Deployment, Service 생성
kubectl apply -f vue006dep.yml
kubectl apply -f vue006ser.yml

3-2. Pod 상태 확인

kubectl get pods

• STATUS: Running
• READY: 1/1
  → Liveness, Readiness 모두 통과한 상태

3-3. Service 엔드포인트 확인

kubectl get endpoints vue006ser

• 여기에서 Pod의 IP가 보이면, Readiness Probe를 통과해 서비스 트래픽 대상에 포함된 상태다.

---

4. 잘못된 포트(8080)로 실패 상황 관찰

이제 livenessProbe와 readinessProbe의 port를 8080으로 바꾼 뒤, 실제로 어떻게 동작하는지 볼 수 있다.

livenessProbe:
  httpGet:
    path: /
    port: 8080      # 존재하지 않는 포트로 실패 유도

readinessProbe:
  httpGet:
    path: /
    port: 8080      # 마찬가지로 실패 유도

적용 후 다시 배포:

kubectl apply -f vue006dep.yml
kubectl apply -f vue006ser.yml

4-1. Pod 재시작 관찰 (Liveness 실패)

kubectl get pods -w

• RESTARTS 컬럼 값이 계속 증가하는 모습 확인 가능
• 이유: Liveness Probe가 계속 실패 → Kubernetes가 컨테이너를 반복해서 재시작

4-2. Probe 실패 이벤트 확인

kubectl describe pod <pod-name>

• Events 섹션에 다음과 같은 로그가 나타난다.

  • Liveness Probe 실패 → 컨테이너 재시작
  • Readiness Probe 실패 → Pod가 NotReady로 전환

4-3. 서비스 엔드포인트에서 제외되는지 확인

kubectl get endpoints vue006ser

• Readiness Probe가 실패하면 해당 Pod IP가 목록에 나타나지 않는다.
• 즉, 서비스 입장에서 보면 그 Pod는 존재하지 않는 것처럼 취급된다.

---

5. 정리

• Liveness Probe

  • 애플리케이션이 죽었거나 먹통인지 감시한다.
  • 실패 시 컨테이너를 재시작해 자기 회복력을 높인다.

• Readiness Probe

  • 애플리케이션이 트래픽을 받을 준비가 되었는지 판단한다.
  • 실패하면 서비스 엔드포인트에서 제외되어 트래픽이 들어가지 않는다.

• 두 프로브를 적절히 설정하면:

  • 장애 상황에서 자동 복구
  • 초기화 중인 Pod로 트래픽이 들어가는 문제 방지
  • 전체 서비스 안정성이 크게 올라간다.

헬스 체크는 쿠버네티스에서 거의 모든 프로덕션 워크로드에 필수로 들어가는 설정이니, HTTP 기반 프로브부터 익숙하게 다루는 게 좋다.