infra

쿠버네티스 Pod 트러블슈팅 가이드: 실행되지 않을 때 확인 순서

mirabo01 2026. 2. 9. 09:53

쿠버네티스 트러블슈팅 기본편, Pod가 뜨지 않을 때 확인 순서

쿠버네티스를 어느 정도 쓰다 보면
언젠가는 꼭 이런 상황을 마주하게 된다.

  • 배포는 했는데 Pod가 안 뜬다
  • 계속 재시작만 반복한다
  • 상태가 Pending이나 CrashLoopBackOff에서 멈춰 있다

이 글에서는 Pod가 정상적으로 실행되지 않을 때,
실무에서 많이 사용하는 확인 순서와 사고 흐름을 정리한다.
특정 에러를 외우기보다는, 어디부터 보면 되는지에 초점을 맞췄다.

트러블슈팅의 출발점은 “상태 확인”이다

가장 먼저 해야 할 일은
“무슨 문제가 있는지 추측”하는 게 아니라
쿠버네티스가 보고 있는 상태를 그대로 확인하는 것이다.

보통 이 한 줄에서 시작한다.

kubectl get pod

여기서 가장 많이 마주치는 상태는 다음과 같다.

  • Pending
  • CrashLoopBackOff
  • ImagePullBackOff
  • Error

상태에 따라 접근 순서가 달라진다.

Pod가 Pending 상태에 머물러 있을 때

Pending은 아직 실행조차 되지 못했다는 뜻이다.
즉, 컨테이너 문제 이전에 환경 문제일 가능성이 크다.

가장 먼저 볼 것: 이벤트(Event)

kubectl describe pod <pod-name>

아래쪽 Events 영역을 보면
Pod가 왜 뜨지 못하는지 비교적 명확하게 나온다.

[이미지: kubectl describe pod 이벤트 영역 예시]

자주 나오는 원인

  • requests가 너무 큼
    → Pod를 배치할 Node가 없음
  • 노드 리소스 부족
  • 스케줄링 제약 조건 문제

실제로 운영해보면
requests 값을 과하게 잡아두고
“왜 Pod가 안 뜨지?” 하고 헤매는 경우가 꽤 많다.

ImagePullBackOff: 이미지를 못 가져오는 경우

이 상태는 원인이 비교적 명확하다.

  • 이미지 이름 오타
  • 태그가 존재하지 않음
  • 프라이빗 레지스트리 인증 문제

이 경우에도 describe pod 이벤트를 보면
에러 메시지가 그대로 나온다.

⚠️ 특히 Secret으로 레지스트리 인증 정보를 쓸 때
네임스페이스를 헷갈리는 경우가 자주 발생한다.

CrashLoopBackOff: 가장 흔하지만 가장 헷갈리는 상태

CrashLoopBackOff는 의미 자체는 단순하다.

컨테이너가 실행됐다가 바로 종료되는 상태가 반복되고 있다.

문제는 원인이 다양하다는 점이다.

1단계: 로그 확인

kubectl logs <pod-name>

가장 먼저 애플리케이션 로그를 본다.

  • 애플리케이션 시작 중 에러
  • 설정 값 누락
  • 외부 의존성 연결 실패

이 단계에서 원인이 보이는 경우가 가장 많다.

2단계: 이전 로그 확인

컨테이너가 너무 빨리 죽는 경우,
현재 로그가 비어 있을 수도 있다.

kubectl logs <pod-name> --previous

이 옵션은 생각보다 자주 쓰인다.

3단계: 리소스 제한 확인

로그가 특별히 없어 보인다면
메모리 limits를 의심해볼 필요가 있다.

  • OOMKilled
  • 메모리 부족으로 즉시 종료
kubectl describe pod <pod-name>

여기서 Last State나 Reason 항목을 확인한다.

Error 상태: 여러 원인이 섞여 있을 때

Error는 포괄적인 상태다.
이 경우에도 접근 방식은 같다.

  1. describe pod로 이벤트 확인
  2. logs로 애플리케이션 로그 확인
  3. 설정(ConfigMap, Secret) 점검
  4. 리소스 설정 확인

중요한 점은
한 번에 여러 가설을 세우지 않는 것이다.

자주 놓치는 설정 관련 문제

실무에서 은근히 많이 겪는 케이스들이다.

  • ConfigMap 키 이름 오타
  • Secret은 있는데 환경 변수로 주입 안 됨
  • 설정 변경 후 Pod 재시작 안 함

특히 ConfigMap/Secret은
수정해도 Pod가 자동으로 반영되지 않는 경우가 많다.
“설정은 바꿨는데 왜 그대로지?”라는 상황이 여기서 나온다.

Node 문제인지 Pod 문제인지 구분하기

트러블슈팅이 길어질수록
이 구분이 중요해진다.

  • 여러 Pod가 동시에 이상하다
    → Node 문제 가능성
  • 특정 Pod만 반복적으로 실패
    → 설정 또는 애플리케이션 문제

Node 문제의 경우에는

  • Node 상태(NotReady)
  • 디스크 부족
  • 네트워크 이슈

같은 인프라 레벨 점검이 필요해진다.

트러블슈팅 시 가져가면 좋은 사고 흐름

정리하면 다음 순서가 가장 무난하다.

  1. Pod 상태 확인
  2. describe pod 이벤트 확인
  3. 로그 확인
  4. 리소스 설정 점검
  5. 설정(ConfigMap/Secret) 확인
  6. Node 상태 확인

중요한 건 “빨리 고치는 것”보다
“원인을 이해하고 고치는 것”이다.

정리하며

이번 글에서는 쿠버네티스에서
Pod가 뜨지 않을 때의 기본적인 트러블슈팅 흐름을 정리했다.

  • 상태부터 확인한다
  • 이벤트와 로그가 가장 중요한 단서다
  • Pending과 CrashLoopBackOff는 접근 방식이 다르다
  • 리소스와 설정 문제를 자주 의심하자

다음 글에서는
이번 내용의 연장선으로,
운영 중 자주 마주치는 에러 케이스들
(예: OOMKilled, Evicted, Node 장애)을 중심으로
조금 더 실전적인 트러블슈팅을 정리해볼 예정이다.