Pod 실패 원인 분석

Kubernetes Pod 장애의 체계적인 진단과 해결 완벽 가이드

Kubernetes Pod 장애의 체계적인 진단과 해결 완벽 가이드

목표: 5분 내에 Pod 장애의 원인을 찾고 해결할 수 있는 수준

🔍 진단 체크리스트

[Pod 상태 확인]
    │
    ├── Pending? ──> [리소스/스케줄링/볼륨]
    │
    ├── CrashLoopBackOff? ──> [앱/환경변수/헬스체크]
    │
    ├── ImagePullBackOff? ──> [이미지/인증/네트워크]
    │
    ├── Running but Not Ready? ──> [ReadinessProbe/리소스]
    │
    └── Terminating? ──> [종료 대기/Force Delete]

🚨 Pending 상태

원인 1: 리소스 부족

# 증상 확인
kubectl describe pod my-pod | grep -A 5 Events
# Warning  FailedScheduling  ...  0/3 nodes are available: 3 Insufficient cpu.

# 해결
# 1. 노드 리소스 확인
kubectl top nodes

# 2. Pod 리소스 요청 조정
resources:
  requests:
    cpu: "100m"      # 낮춤
    memory: "128Mi"  # 낮춤

# 3. 또는 노드 추가
kubectl get nodes

원인 2: 스케줄링 제약

# 증상 확인
kubectl describe pod my-pod | grep -A 5 Events
# Warning  FailedScheduling  ...  0/3 nodes are available: 3 node(s) didn't match Pod's node affinity.

# 해결
# 1. 노드 레이블 확인
kubectl get nodes --show-labels

# 2. Pod의 nodeSelector/affinity 수정
# 또는 노드에 레이블 추가
kubectl label nodes worker-1 env=production

원인 3: 볼륨 마운트 실패

# 증상 확인
kubectl describe pod my-pod | grep -A 5 Events
# Warning  FailedMount  ...  Unable to attach or mount volumes...

# 해결
# 1. PVC 상태 확인
kubectl get pvc
kubectl describe pvc my-pvc

# 2. PV 상태 확인
kubectl get pv

# 3. StorageClass 확인
kubectl get storageclass

💥 CrashLoopBackOff

원인 1: 애플리케이션 오류

# 로그 확인
kubectl logs my-pod --previous
# 또는
kubectl logs my-pod -c my-container --previous

# 해결
# 1. 앱 코드 수정
# 2. 환경변수 확인
kubectl describe pod my-pod | grep -A 20 Environment

# 3. 설정 파일 확인
kubectl get configmap my-config -o yaml

원인 2: 환경변수/설정 누락

# 환경변수 확인
kubectl exec my-pod -- env

# ConfigMap/Secret 확인
kubectl get configmap
kubectl get secret

# 해결
# 1. ConfigMap 생성
kubectl create configmap my-config --from-literal=KEY=VALUE

# 2. Pod에 마운트
envFrom:
- configMapRef:
    name: my-config

원인 3: 헬스체크 실패

# 증상 확인
kubectl describe pod my-pod | grep -A 10 Events
# Warning  Unhealthy  ...  Liveness probe failed: HTTP probe failed with statuscode: 500

# 해결
# 1. 헬스체크 경로 확인
kubectl get pod my-pod -o yaml | grep -A 10 livenessProbe

# 2. 임시로 헬스체크 제거 (디버깅용)
# 3. 또는 initialDelaySeconds 증가
livenessProbe:
  initialDelaySeconds: 60  # 늘림

🖼️ ImagePullBackOff

원인 1: 이미지 이름/태그 오류

# 증상 확인
kubectl describe pod my-pod | grep -A 5 Events
# Warning  Failed  ...  Failed to pull image "nginx:latst": rpc error...

# 해결
# 1. 올바른 태그 확인
kubectl set image deployment/my-app my-app=nginx:latest

# 2. 이미지 존재 확인
docker pull nginx:latest

원인 2: Private Registry 인증

# 증상 확인
kubectl describe pod my-pod | grep -A 5 Events
# Warning  Failed  ...  Error: ImagePullBackOff

# 해결
# 1. Secret 생성
kubectl create secret docker-registry regcred \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=USERNAME \
  --docker-password=PASSWORD

# 2. Pod에 추가
imagePullSecrets:
- name: regcred

🔄 Running but Not Ready

원인: ReadinessProbe 실패

# 증상 확인
kubectl get pod my-pod
# NAME     READY   STATUS    RESTARTS   AGE
# my-pod   0/1     Running   0          5m

# 원인 확인
kubectl describe pod my-pod | grep -A 5 Conditions
# Ready    False

# 해결
# 1. ReadinessProbe 확인
kubectl get pod my-pod -o yaml | grep -A 10 readinessProbe

# 2. 앱 상태 확인
kubectl logs my-pod

# 3. 임시로 ReadinessProbe 제거 (디버깅)

🐛 디버깅 명령어 모음

# 1. 기본 정보
kubectl get pod my-pod -o wide
kubectl describe pod my-pod

# 2. 로그
kubectl logs my-pod
kubectl logs my-pod --previous
kubectl logs my-pod -c container-name
kubectl logs my-pod --tail=100 -f

# 3. 이벤트
kubectl get events --field-selector involvedObject.name=my-pod
kubectl get events --sort-by='.lastTimestamp'

# 4. 실행 중인 컨테이너 접속
kubectl exec -it my-pod -- /bin/sh
kubectl exec -it my-pod -c container-name -- /bin/sh

# 5. 리소스 사용량
kubectl top pod my-pod
kubectl top pod my-pod --containers

# 6. 네트워크 테스트
kubectl run debug --rm -it --image=busybox --restart=Never -- sh
# 내부에서: wget, nslookup, ping 테스트

# 7. YAML 추출
kubectl get pod my-pod -o yaml > pod-debug.yaml

# 8. 강제 삭제 (Terminating에서 멈춘 경우)
kubectl delete pod my-pod --force --grace-period=0

📋 체크리스트

🔗 관련 노트

01-02-Pod-생명주기 — 상태 변화
01-04-Deployment-관리 — 워크로드 관리
02-12-클러스터-장애-복구 — 클러스터 장애

마지막 업데이트: 2026-06-01