Kubernetes CrashLoopBackOff 완벽 해결 가이드

CrashLoopBackOff란?

Pod가 시작 → 크래시 → 재시작을 반복하며 대기 시간이 늘어나는 상태입니다.
Kubernetes는 재시작마다 백오프 시간을 2배씩 늘려 최대 5분까지 기다립니다.

NAME          READY   STATUS             RESTARTS   AGE
my-app-xyz    0/1     CrashLoopBackOff   5          8m

원인 5가지

1. 애플리케이션 자체 크래시

가장 흔한 원인. 앱이 시작 직후 예외/패닉으로 종료됩니다.

# 로그 확인 (이미 종료된 컨테이너)
kubectl logs my-app-xyz --previous

# 최근 100줄만
kubectl logs my-app-xyz --previous --tail=100

2. Liveness Probe 실패

앱은 살아있지만 probe 설정이 너무 빡빡한 경우.

livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 30   # 너무 짧으면 시작 전에 실패
  periodSeconds: 10
  failureThreshold: 3

해결: initialDelaySeconds를 앱 기동 시간보다 여유있게 설정.

3. OOMKilled (메모리 부족)

kubectl describe pod my-app-xyz | grep -A5 "Last State"
# State: Terminated
# Reason: OOMKilled

resources:
  requests:
    memory: "256Mi"
  limits:
    memory: "512Mi"   # 실제 사용량보다 여유있게

4. ConfigMap / Secret 마운트 실패

참조하는 ConfigMap이나 Secret이 없을 때.

kubectl describe pod my-app-xyz | grep -A10 "Events"
# Warning  Failed    MountVolume.SetUp failed: secret "db-secret" not found

# Secret 존재 확인
kubectl get secret db-secret -n your-namespace

5. 이미지 실행 권한 / Entrypoint 오류

kubectl describe pod my-app-xyz | grep "Error"
# exec /app/start.sh: permission denied

Dockerfile에서 실행 권한을 부여해야 합니다.

COPY start.sh /app/start.sh
RUN chmod +x /app/start.sh

단계별 디버깅 체크리스트

# 1. Pod 상태 확인
kubectl get pod my-app-xyz -o wide

# 2. 이벤트 확인 (원인의 80%가 여기에)
kubectl describe pod my-app-xyz

# 3. 이전 컨테이너 로그
kubectl logs my-app-xyz --previous

# 4. 임시 셸로 직접 접속 (Pod가 살아있을 때)
kubectl exec -it my-app-xyz -- /bin/sh

# 5. 같은 이미지로 디버그 Pod 실행
kubectl run debug --image=your-image:tag --restart=Never -- sleep 3600
kubectl exec -it debug -- /bin/sh

빠른 원인 판별표

증상	의심 원인
로그에 Java Exception	앱 크래시
OOMKilled	메모리 limit 초과
permission denied	파일 실행권한
secret not found	Secret 누락
로그 없음 + probe 실패	Liveness probe 설정 오류

TestForge로 자동 감지

TestForge의 Scan 기능은 배포 직후 Pod 상태를 자동 모니터링해 CrashLoopBackOff 발생 시 Slack 알림과 함께 원인을 분석해줍니다.