쿠버네티스 장애는 “상태 이름”이 이미 원인 계층의 절반을 알려준다
K8s 트러블슈팅의 공통 골격은 상태 → 이벤트 → 로그 → 연결이다. 그리고 그 첫 단계인 상태 문자열만 정확히 읽어도 어느 계층 문제인지 반쯤 좁혀진다. 개별 증상 가이드로 들어가기 전, 이 지도를 먼저 본다.
1) 상태 이름으로 계층을 가른다
kubectl get pod -n <ns> -o wide- Pending — 스케줄 단계. 노드 리소스 부족, taint/toleration, PVC 미바인딩.
- ImagePullBackOff / ErrImagePull — 이미지 가져오기. 이름·인증·네트워크.
- CreateContainerConfigError — ConfigMap/Secret 참조 오류(기동 전).
- CrashLoopBackOff — 기동은 됐는데 프로세스가 죽거나 probe가 죽임.
- Running인데 트래픽 안 감 — Ready가 아니거나 Service/Endpoints 문제.
2) describe의 Events·Conditions가 증거다
kubectl describe는 스케줄 실패 사유, probe 결과, 리소스 압박을 시간순으로 보여준다. 로그보다 먼저 이 줄들을 읽으면 헛다리를 줄인다.
3) 계층 순서로 좁힌다
스케줄(노드/taint/리소스) → 기동(이미지/설정) → 준비(probe) → 연결(Service·Endpoints) → 정책(NetworkPolicy). 위 계층이 막히면 아래는 볼 필요가 없다. 이 순서를 지키는 것만으로 대부분의 “왜 안 되지”가 빠르게 정리된다.
가장 큰 함정
상태 이름을 곧 원인으로 착각하는 것. CrashLoopBackOff는 원인이 아니라 “재시작이 반복된다”는 현상이고, Running은 “정상”이 아니라 “컨테이너가 떠 있다”일 뿐이다. 증상과 원인을 분리하는 데서 진단이 시작된다.
빠른 진단 체크리스트
- 먼저
kubectl get pod로 상태 이름을 정확히 읽는다 - Pending이면 스케줄(노드 리소스·taint·PVC)을 본다
- ImagePullBackOff면 이미지 이름·인증·네트워크를 본다
- CreateContainerConfigError면 ConfigMap·Secret 참조를 본다
- CrashLoopBackOff면 종료 코드·probe를 본다
- Running인데 트래픽 안 가면 Ready·Endpoints를 본다
- describe의 Events·Conditions를 로그보다 먼저 읽는다
- 스케줄→기동→준비→연결→정책 순으로 계층을 좁힌다