Mar 24, 2026

마지막 업데이트 Mar 30, 2026

Kubernetes CrashLoopBackOff: 먼저 볼 것들

Pod 가 CrashLoopBackOff 에 들어가면 Kubernetes 는 컨테이너가 계속 실패하고 재시작된다고 알려 주는 것입니다. 흔한 증상이지만 root cause 는 startup failure, probe 설정, config 누락, dependency timing, 혹은 애플리케이션 실패처럼 보이는 resource pressure 일 수 있습니다.

짧게 말하면 핵심은 이것입니다. deployment 설정을 만지기 전에 컨테이너가 왜 종료되는지 먼저 찾아야 합니다. CrashLoopBackOff 는 restart symptom 이지 root cause 가 아닙니다.

event, log, probe 동작부터 본다

crash loop 를 좁히는 가장 빠른 자료는 보통 아래입니다.

pod event
현재 / 이전 container log
startup command 와 env
probe 설정

이 신호들이 restart count 하나보다 훨씬 많은 걸 설명해 줍니다.

`CrashLoopBackOff` 는 보통 무엇을 뜻하나

실전에선 보통 이런 경우가 많습니다.

앱이 startup 중 바로 종료된다
probe 가 너무 공격적이라 Kubernetes 가 죽인다
boot 시점 dependency 가 준비되지 않았다
resource limit 때문에 exit 또는 kill 된다
config 또는 secret 가정이 틀렸다

그래서 이 incident 는 “앱이 스스로 죽는가” 와 “앱이 외부에서 죽임당하는가” 로 나눠 봐야 합니다.

흔한 원인

1. 앱이 startup 중 실패한다

config 오류, secret 누락, migration 문제, 잘못된 startup command 때문에 readiness 이전에 프로세스가 죽을 수 있습니다.

2. liveness 또는 startup probe 가 너무 공격적이다

앱은 건강하지만 시작이 느린데, Kubernetes 가 안정화 전에 계속 죽일 수 있습니다.

probe 또는 startup 동작을 바꾼 뒤 자주 보이는 패턴입니다.

3. dependency timing 이 어긋난다

DB, queue, upstream service 가 준비되기 전에 pod 가 그걸 당연히 기대하고 부팅하다 실패할 수 있습니다.

restart timing 과 dependency readiness 를 비교해 보면 이 경우가 드러나곤 합니다.

4. resource limit 이 비현실적이다

OOM kill 이나 CPU starvation 도 restart count 만 보면 앱 버그처럼 보일 수 있습니다.

5. mounted config 와 environment 가 기대와 다르다

image 는 맞아도 runtime input 이 틀릴 수 있습니다.

config map 값
secret key
file mount path
command / argument 변경

실전 점검 순서

1. `kubectl describe pod` event 를 본다

Kubernetes 가 아래 중 무엇을 보고 있는지 먼저 알 수 있습니다.

probe failure
OOM kill signal
반복 restart timing
image 또는 startup 문제

2. 현재 / 이전 container log 를 본다

특히 previous log 가 중요할 때가 많습니다. 실패한 프로세스는 너무 빨리 죽어서 현재 실행 로그만으론 맥락이 부족할 수 있기 때문입니다.

3. probe, command, env, mounted config 를 점검한다

runtime input 이 image 기대와 맞는지 가정하지 말고 직접 확인해야 합니다.

많은 crash loop 가 결국 configuration drift 였던 경우가 많습니다.

4. restart timing 과 dependency / resource limit 을 비교한다

질문은 이렇습니다.

pod 가 즉시 죽는가
probe 시작 후에만 죽는가
memory pressure 때만 죽는가
dependency 가 없을 때만 죽는가

5. 진짜 crash 인지, startup 이 느린 것뿐인지 구분한다

이 구분이 앱 수정, probe 수정, 플랫폼 설정 수정 중 어느 길로 갈지 결정합니다.

빠른 명령

kubectl describe pod <pod> -n <ns>
kubectl logs <pod> -n <ns> --previous
kubectl get pod <pod> -n <ns> -o yaml

이 세 가지 조합이면 app startup 문제인지, probe 문제인지, config 문제인지, 이전 container run 문제인지 보통 빠르게 갈립니다.

restart reason, 마지막 fatal log, probe 또는 config mismatch event 를 같이 보세요.

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

앱 자체가 crash 한다면

config, command, startup logic, dependency assumption 을 먼저 고쳐야 합니다.

probe 가 너무 공격적이라면

건강하지만 느린 컨테이너를 죽이지 않도록 startup 또는 liveness 동작을 조정해야 합니다.

dependency 가 늦다면

startup 을 더 관대하게 만들거나, dependency 가 실제로 준비된 뒤에만 강하게 기대하도록 바꿔야 합니다.

limit 이 비현실적이라면

restart symptom 이 아니라 실제 usage 에 맞춰 resource 를 다시 잡아야 합니다.

runtime input 이 drift 했다면

config map, secret, command, image expectation 을 다시 맞춰야 합니다.

장애 중에 던져볼 질문

이 질문이 꽤 유용합니다.

컨테이너가 스스로 죽는 건가, 아니면 적절한 timing 이나 resource 만 있었다면 회복했을 컨테이너를 Kubernetes 가 죽이고 있는 건가?

이 질문이 application bug 와 platform behavior 를 빨리 갈라 줍니다.

FAQ

Q. `CrashLoopBackOff` 자체가 에러인가

아닙니다. 반복 restart 상태를 가리키는 상태값입니다.

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

describe event 와 previous container log 를 같이 보는 것입니다.

Q. restart delay 나 probe threshold 를 먼저 늘려야 하나

컨테이너가 진짜로 crash 하는지, 아니면 startup window 를 공정하게 못 받는지만 먼저 구분하는 게 좋습니다.

Q. OOM 이 crash loop 안에 숨어 있을 수도 있나

그렇습니다. 일부 crash loop 는 사실 memory incident 가 generic restart symptom 으로 보이는 경우입니다.

먼저 읽어볼 가이드

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