Kubernetes Pod 'CrashLoopBackOff' 원인 분석 및 해결 가이드

🎯 타겟 독자: kubectl 명령어가 익숙지 않은 백엔드 개발자, 배포 직후 파드(Pod)가 빨간불로 켜졌다 꺼지기를 반복하는 상황에 처한 데브옵스 입문자.


📝 요약: CrashLoopBackOff는 쿠버네티스에서 가장 흔하지만 가장 당혹스러운 에러 상태입니다. 컨테이너가 시작되자마자 죽고, K8s가 이를 살리려다 다시 죽는 루프에 빠진 것입니다. 이 글에서는 로그 확인(Logs), 상태 상세 조회(Describe), 프로브(Probe) 설정을 통해 원인을 핀포인트로 찾아내는 3단계 디버깅 기법을 다룹니다.

크래시 루프 백오프 상태의 클러스터

1. 상황 파악: "파드가 자꾸 죽었다 살아나요"

배포 스크립트를 실행하고 kubectl get pods를 쳤는데, STATUS 컬럼이 Running이 아니라 CrashLoopBackOff 또는 Error로 바뀌며 RESTARTS 횟수가 계속 올라가는 상황입니다.

NAME READY STATUS RESTARTS AGE my-api-pod 0/1 CrashLoopBackOff 12 5m

이는 컨테이너 내부의 애플리케이션이 '실행 직후 비정상 종료(Exit Code 1, 137 등)'되었음을 의미합니다. 쿠버네티스는 이를 감지하고 재시작 정책(Restart Policy)에 따라 살려내지만, 원인이 해결되지 않았기에 다시 죽는 과정이 반복되는 것입니다.

2. 디버깅 1단계: 죽기 직전의 유언(Logs) 확인

가장 먼저 해야 할 일은 애플리케이션이 죽으면서 남긴 표준 출력(Standard Output) 로그를 확인하는 것입니다.

# 현재 로그 확인 kubectl logs my-api-pod # 방금 죽은 이전 컨테이너의 로그 확인 (핵심!) kubectl logs my-api-pod --previous

특히 --previous 옵션이 중요합니다. 현재 컨테이너는 막 재시작되어 로그가 없을 수 있지만, 방금 죽은 녀석은 "DB 연결 실패"나 "환경 변수 누락" 같은 결정적인 단서를 남겼을 확률이 높습니다.

3. 디버깅 2단계: 쿠버네티스의 시선(Describe) 확인

애플리케이션 로그에 아무것도 없다면, 쿠버네티스 레벨의 문제일 수 있습니다. 파드의 상세 명세와 이벤트를 확인합니다.

kubectl describe pod my-api-pod

출력 결과의 맨 아래 Events 섹션과 중간의 State 섹션을 주목하세요.

  • OOMKilled (Exit Code 137): 메모리 부족으로 강제 종료됨.
    👉 해결: resources.limits.memory를 늘리거나 메모리 누수를 잡으세요.
  • Liveness probe failed: 헬스 체크 실패로 K8s가 스스로 파드를 죽임.
    👉 해결: 초기 구동 시간이 길다면 `initialDelaySeconds`를 늘리세요.
  • Back-off restarting failed container: 반복적인 재시작 시도 중.

4. 주요 원인 BEST 3 및 해결책

원인 증상 해결법
설정 오류 로그에 'ConfigMap not found' 또는 'Panic' 발생 환경변수/ConfigMap 마운트 경로 확인
즉시 종료됨 CMD/ENTRYPOINT가 백그라운드 프로세스가 아님 포그라운드 실행 유지 (`nginx -g 'daemon off;'` 등)
리소스 부족 Status: OOMKilled (Code 137) `resources` 요청/제한 값 증설

💡 꿀팁: 디버깅용으로 강제 실행하기

원인을 도저히 모르겠다면, 파드를 일단 살려놓고 내부에 접속해서 직접 실행해 보는 방법이 있습니다.

# YAML 파일의 command를 덮어씌워 일단 죽지 않게 함 command: ["/bin/sh", "-c", "sleep 3600"]

이렇게 설정하고 배포하면 파드가 Running 상태를 유지합니다. 이때 kubectl exec -it my-pod -- /bin/sh로 접속하여 원래 실행 명령어를 수동으로 입력해보면 에러 원인을 실시간으로 볼 수 있습니다.

5. 결론

CrashLoopBackOff는 "나 좀 봐줘, 설정이 틀렸거나 아파서 못 뜨겠어"라는 컨테이너의 비명입니다. 당황하지 말고 로그(Logs) -> 상세 상태(Describe) -> 리소스(Resource) 순으로 접근하면 99% 해결할 수 있습니다.

이 블로그의 인기 게시물

Docker 컨테이너 'Connection Refused' (Errno 111) 오류 해결 가이드

이미지
🎯 타겟 독자: Docker 입문자, 컨테이너를 띄웠으나 localhost 로 접속이 안 되는 백엔드 개발자, MSA(마이크로서비스) 구축 중 통신 오류를 겪는 엔지니어. 📝 요약: Docker 접속 오류(Errno 111)의 90%는 애플리케이션이 '0.0.0.0'이 아닌 '127.0.0.1' 로 바인딩 되어 있거나, 포트 포워딩(-p) 설정이 누락되어 발생합니다. 이 글에서는 네트워크 인터페이스의 차이를 이해하고, 외부 접속을 허용하는 올바른 설정법을 정리합니다. 1. 문제 정의: "컨테이너는 떴는데 접속이 안 돼요" Docker 입문자들이 가장 흔하게 겪는 상황입니다. docker ps 로 확인하면 상태(STATUS)는 분명히 Up 인데, 브라우저나 Postman으로 접속하면 즉시 연결이 거부됩니다. curl: (7) Failed to connect to localhost port 8080: Connection refused Python: ConnectionRefusedError: [Errno 111] Connection refused 이 문제는 방화벽 때문이 아닙니다. "누구의 요청을 들을 준비가 되었는가(Listen Address)" 에 대한 설정이 잘못되었기 때문입니다. 2. 원인 분석: 127.0.0.1의 함정 핵심은 Loopback(127.0.0.1) 과 Any Address(0.0.0.0) 의 차이입니다. 로컬 PC에서 개발할 때 서버를 localhost 로 띄우는 건 보안상 좋은 습관입니다. 하지만 Docker 컨테이너는 독립된 IP를 ...
자세한 내용 보기

Redis 캐싱 전략 완벽 가이드: Look Aside부터 Write Back까지 (DB 부하 줄이기)

이미지
🎯 타겟 독자: 사용자가 몰릴 때마다 DB CPU가 100%를 치는 상황을 겪는 백엔드 개발자, Redis를 단순히 get/set 으로만 쓰고 있는 주니어 엔지니어. 📝 요약: 캐시(Cache)는 성능 향상의 치트키지만, 잘못 쓰면 데이터 불일치(Inconsistency) 라는 재앙을 부릅니다. 이 글에서는 가장 대중적인 Look Aside(Lazy Loading) 패턴과 쓰기 성능을 극대화하는 Write Back 패턴의 작동 원리, 장단점, 그리고 언제 무엇을 써야 하는지 명확한 기준을 제시합니다. 1. 캐싱 패턴이 왜 중요한가요? "그냥 Redis에 넣으면 되는 거 아닌가요?"라고 묻는다면 반은 맞고 반은 틀립니다. 캐시를 데이터베이스(DB)와 어떤 순서로 연동하느냐에 따라 시스템의 데이터 정합성 과 성능 이 완전히 달라지기 때문입니다. 2. 패턴 ① Look Aside (Lazy Loading) - 국룰 전략 현업에서 80% 이상 사용되는 가장 일반적인 읽기 전략입니다. 캐시를 옆(Aside)에 두고 필요할 때만 데이터를 가져옵니다. 작동 순서 앱이 데이터를 찾을 때 먼저 캐시(Redis)를 찌릅니다. 캐시에 데이터가 있으면(Cache Hit) 바로 반환합니다. (DB 부하 0) 없으면(Cache Miss) DB에서 조회 하여 가져옵니다. 가져온 데이터를 캐시에 저장 하고 반환합니다. public User getUser(Long id) { // 1. 캐시 조회 User user = redisTemplate.opsForValue().get("user:" +...
자세한 내용 보기

브라우저 렌더링 원리: Reflow와 Repaint 최적화 가이드 (CRP 심층 분석)

이미지
📌 핵심 요약 CRP(Critical Rendering Path) 의 5단계: DOM → CSSOM → Render Tree → Layout → Paint 성능의 주범 Reflow(Layout) 와 Repaint 의 차이점 애니메이션 성능 최적화: 왜 top/left 대신 transform 을 써야 하는가? (GPU 가속과 Composite) "사용자가 주소창에 URL을 입력하고 엔터를 쳤을 때, 화면에 네이버 메인이 뜨기까지 무슨 일이 일어나는가?" 이 질문은 네트워크 관점(DNS, TCP/IP)에서도 답변할 수 있지만, 프론트엔드 개발자라면 렌더링 엔진(Rendering Engine)이 HTML과 CSS를 해석해서 픽셀로 바꿔주는 과정, 즉 CRP(Critical Rendering Path)를 설명할 수 있어야 합니다. 이 원리를 알아야 "왜 리액트가 Virtual DOM을 쓰는지", "왜 애니메이션이 버벅이는지" 이해할 수 있습니다. 1. 렌더링 파이프라인 (The Pipeline) 브라우저는 다음 5단계를 거쳐 화면을 그립니다. DOM 트리 생성: HTML 문서를 파싱 하여 태그 간의 관계(부모-자식)를 트리 구조로 만듭니다. CSSOM 트리 생성: CSS 파일과 인라인 스타일을 파싱 하여 스타일 규칙 트리를 만듭니다. Render Tree 생성: DOM과 CSSOM을 결합하여 "실제로 화면에 표시될 노드" 만 추려냅니다. Layout (Reflow): 각 노드가 화면의 어느 위치에, 어떤 크기(px) 로 배치될지 기하학적 계산을 수행합니다. ...
자세한 내용 보기