Mar 24, 2026

마지막 업데이트 Mar 30, 2026

Kubernetes Pod Pending 트러블슈팅 가이드

Kubernetes Pod 가 Pending 상태에 오래 머문다면 질문은 아주 단순합니다. 왜 scheduler 또는 runtime 이 이 pod 를 다음 단계로 못 넘기고 있는가입니다. 대개는 “Kubernetes 가 이상하다” 보다는 resource request, node matching, taint/toleration, storage binding, image/setup 지연 같은 몇 가지 범주로 정리됩니다.

짧게 말하면 핵심은 이것입니다. 추측보다 pod event 를 먼저 봐야 합니다. Pending 은 보통 애플리케이션 문제보다 placement 또는 pre-run 문제입니다.

추측보다 scheduling event 부터 본다

Pending 은 이 workload 가 “선언된 상태” 에서 “배치된 상태” 로 아직 못 넘어갔다는 뜻인 경우가 많습니다.

그래서 처음엔 app log 보다 아래 신호가 더 중요합니다.

pod event
node condition
requests / limits
affinity / selector
PVC / storage binding

이걸 건너뛰고 deployment tuning 으로 가면 보통 시간이 오래 걸립니다.

`Pending` 은 실전에서 보통 무엇을 뜻하나

운영 환경에선 대개 이런 경우가 많습니다.

어떤 node 도 resource request 를 수용하지 못한다
selector 나 affinity rule 이 placement 를 너무 좁힌다
taint 가 scheduling 을 막는다
storage 가 아직 준비되지 않았거나 bind 되지 않는다
완전한 unschedulable 은 아니지만 setup 을 기다리는 중이다

대시보드에서는 비슷해 보여도 event 를 보면 대개 빨리 구분됩니다.

흔한 원인

1. request 가 cluster capacity 와 맞지 않는다

CPU 또는 memory request 가 현재 사용 가능한 node 어디에도 들어가지 않을 수 있습니다.

traffic 증가 뒤나 oversized default 가 들어간 뒤 자주 보이는 패턴입니다.

2. node selector, affinity, taint 가 placement 를 막는다

스케줄링 규칙이 eligible node 를 필요 이상으로 줄일 수 있습니다.

예를 들면:

너무 엄격한 node selector
너무 적은 node 와만 맞는 affinity
tainted pool 에 대한 toleration 누락

즉 cluster 전체 capacity 는 있어도, 그 규칙을 만족하는 capacity 가 없는 경우입니다.

3. PVC 또는 storage requirement 가 준비되지 않았다

pod 는 아래를 기다리며 멈출 수 있습니다.

volume binding
storage class 동작
attachment timing
준비되지 않은 backing storage

event 에 volume binding 이나 unbound claim 이 보이면 이쪽 가능성이 큽니다.

4. image pull 또는 setup work 가 지연된다

일부 pod 는 image 나 runtime prerequisite 를 준비하는 동안 Pending 처럼 보이기도 합니다.

이럴 때는 scheduling 과 startup 경계가 흐려지기 때문에 event 문구가 특히 중요합니다.

5. requests / limits 가 해석하기 어렵게 짜여 있다

명백한 실패 하나보다, 시간이 지나며 비현실적이 된 resource model 이 문제일 수도 있습니다.

서류상으론 들어가 보이는 pod 도 실제 cluster 조건에서는 매우 배치하기 어려울 수 있습니다.

실전 점검 순서

1. `kubectl describe pod` event 를 본다

거의 항상 가장 빠른 첫 단계입니다.

주로 볼 단어는:

unschedulable
insufficient CPU
insufficient memory
volume binding delay
taint mismatch

2. requests / limits 와 node capacity 를 비교한다

현재 resource pressure 를 감안했을 때 이 pod 를 실제로 수용할 node 가 있는지 보세요.

3. selector, affinity, taint, toleration 을 점검한다

cluster 전체는 멀쩡해 보여도, pod 스스로 placement 범위를 지나치게 좁혔을 수 있습니다.

4. PVC 와 storage binding 상태를 확인한다

storage 쪽이 준비되지 않으면 scheduling 이 괜찮아 보여도 pod 는 앞으로 나가지 못합니다.

5. 진짜 unschedulable 인지 setup 대기인지 구분한다

이 구분이 중요합니다. 이후 디버깅 경로가 완전히 달라지기 때문입니다.

node 에 올라간 뒤 실패한다면 더 이상 순수한 Pending 문제는 아닙니다.

빠른 명령

kubectl describe pod <pod> -n <ns>
kubectl get nodes
kubectl get pvc -n <ns>

scheduler placement 문제인지, node capacity 문제인지, storage wait 인지 먼저 가르는 기본 조합입니다.

unschedulable event, taint 또는 affinity mismatch, 아직 bind 되지 않은 PVC 를 먼저 확인해 보세요.

blocker 를 찾은 뒤 무엇을 바꾸면 좋나

request 가 너무 크다면

현실적인 node capacity 에 맞게 조정해야 합니다.

affinity 나 taint 규칙이 너무 빡빡하다면

placement rule 을 완화하거나 실제 필요한 toleration 을 추가해야 합니다.

PVC binding 이 문제라면

deployment 보다 claim, storage class, provisioning 동작을 먼저 고쳐야 합니다.

image 또는 runtime setup 이 지연된다면

scheduling 보다 image/startup 경로를 봐야 합니다.

workload 가 어디에도 겨우 들어가는 수준이라면

이건 일회성 장애보다 resource sizing 설계 문제로 보는 편이 맞습니다.

장애 중에 던져볼 질문

이 질문이 꽤 유용합니다.

Kubernetes 가 이 pod 를 배치하거나 시작하기 전에 반드시 만족돼야 할 정확한 조건은 무엇이고, 어떤 event 가 그 조건이 아직 안 맞는다고 말해 주는가?

이 질문이 generic 한 cluster 점검보다 훨씬 빨리 범위를 좁혀 줍니다.

FAQ

Q. `Pending` 이면 무조건 node 가 부족한 건가

아닙니다. scheduling constraint, storage wait, pre-run blocker 일 수도 있습니다.

Q. 가장 빠른 첫 단계는 무엇인가

kubectl describe pod 의 event 를 읽는 것입니다.

Q. `Pending` 인데 app log 를 먼저 봐야 하나

보통은 아닙니다. 컨테이너가 아직 시작도 못 했다면 scheduling/setup 신호가 더 중요합니다.

Q. storage 때문에도 `Pending` 이 오래 갈 수 있나

그렇습니다. unbound claim 과 volume binding 이 흔한 원인입니다.

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.