파드가 안 뜨거나, 떴는데 응답이 없거나, 자꾸 재시작될 때 가장 흔한 실수는 kubectl delete pod로 다시 띄워 보는 것입니다. 운이 좋으면 살아나지만 원인은 그대로 남습니다. 쿠버네티스는 무슨 일이 일어났는지 이미 다 기록해 두고 있습니다. 추측하지 말고 네 곳을 순서대로 보면 대부분의 문제는 몇 분 안에 좁혀집니다.
1단계 — 상태와 이벤트부터 본다
Kubernetes
kubectl get pod <pod> -o wide
kubectl describe pod <pod>
describe 출력 맨 아래 Events: 섹션이 첫 단서입니다. 이미지 풀 실패, 스케줄링 실패, 프로브 실패가 전부 여기 한국어가 아닌 영어로 또렷이 찍힙니다. STATUS 컬럼도 같이 봅니다.
| STATUS | 의미 | 다음에 볼 곳 |
|---|---|---|
Pending | 스케줄 안 됨(자원·노드 부족, PVC 대기) | describe의 Events |
ImagePullBackOff | 이미지 못 받음(태그 오타·인증) | Events의 Failed to pull |
CrashLoopBackOff | 떴다가 죽기를 반복 | logs --previous |
Running인데 응답 없음 | 앱은 살아있으나 동작 이상 | logs, exec |
2단계 — 로그로 앱이 뱉은 말을 본다
Kubernetes
kubectl logs <pod> # 현재 컨테이너
kubectl logs <pod> --previous # 죽기 직전 컨테이너
kubectl logs <pod> -c <container> # 멀티 컨테이너일 때 지정
kubectl logs <pod> -f --tail=50 # 실시간 추적
CrashLoop 상태라면 현재 컨테이너 로그는 비어 있기 쉽습니다. **반드시 --previous**로 죽은 컨테이너의 마지막 로그를 봐야 스택트레이스가 나옵니다.
3단계 — exec로 컨테이너 안에 들어간다
Kubernetes
kubectl exec -it <pod> -- sh
# 안에서 직접 확인
env | grep DB # 주입된 환경변수 확인
cat /etc/config/app.yaml
wget -qO- localhost:8080/healthz # 앱이 정말 듣고 있나
"설정은 맞는데 왜 안 되지" 싶을 때, 컨테이너 안에서 본 환경변수·파일·포트가 진짜입니다. 매니페스트에 적은 것과 다를 때가 의외로 많습니다.
4단계 — 클러스터 전체 이벤트
Kubernetes
kubectl get events --sort-by=.lastTimestamp -A | tail -20
특정 파드가 아니라 노드 압박, OOM, 볼륨 마운트 실패 같은 더 넓은 신호를 잡을 때 유용합니다.
30초 체크리스트
Kubernetes
kubectl describe pod <pod> # Events·State·Exit code
kubectl logs <pod> --previous # 죽기 직전 로그
kubectl exec -it <pod> -- env # 실제 주입된 설정
kubectl get events --sort-by=.lastTimestamp
이 네 명령이면 "왜 안 되는지 모르겠다"는 거의 사라집니다.
문제 파드를 직접 만들어 보고 네 명령으로 원인을 좁히는 실습은 쿠버네티스 트랙에서 회원가입 없이 무료로 해볼 수 있습니다.