CrashLoopBackOff 진단 절차 — 순서대로 좁혀나가기
Kubernetes CrashLoopBackOff 진단 및 ConfigMap/Secret 주입 방식 공식 문서·운영 블로그 종합 (웹 리서치, 2026) — Kubernetes 공식 문서(concepts/configuration/secret), Komodor/GKE 운영 문서 GKE 공식 문서 Troubleshoot CrashLoopBackOff events, Komodor How to Fix CrashLoopBackOff
이 모듈을 다 읽으면
- CrashLoopBackOff이 무엇을 뜻하는지, kubelet이 왜 계속 재시작을 시도하는지 설명할 수 있다
- kubectl logs --previous와 kubectl describe pod를 각각 언제, 왜 먼저 봐야 하는지 순서를 설명할 수 있다
k8s-learn-05의 OOMKilled(메모리 limits 초과 강제종료)와 k8s-learn-06의 livenessProbe 재시작을 전제로, 컨테이너가 계속 죽고 다시 뜨는 CrashLoopBackOff 상황을 순서대로 진단하는 절차를 정리한다.
CrashLoopBackOff란 — kubelet이 재시작을 계속 시도하고 있다는 신호
CrashLoopBackOff는 Pod가 반복적으로 실패하고 있다는 상태다 — 컨테이너가 시작 도중 크래시하고, kubelet이 그걸 다시 시작시키는 과정이 계속 반복되고 있다는 뜻이다. 흔한 원인은 컨테이너 진입점(entrypoint) 자체의 문제(잘못 설정된 환경변수, 없는 파일, 실패하는 의존성, 처리 안 된 예외)다. Pod 상태에서 재시작 횟수(RESTARTS)가 높다면 Kubernetes가 컨테이너를 계속 시도하고 계속 실패하고 있다는 뜻이다.
핵심 포인트
- CrashLoopBackOff: 컨테이너가 시작 도중 크래시 → kubelet이 재시작 → 다시 크래시가 반복되는 상태
- 흔한 원인: 잘못된 환경변수, 없는 파일, 실패하는 의존성, 처리 안 된 예외 등 진입점 자체의 문제
1단계 — kubectl logs --previous로 크래시 직전 로그부터 확인
가장 먼저 볼 것은 죽기 '직전' 컨테이너 인스턴스의 로그다. 현재 컨테이너는 이미 재시작돼 새 프로세스가 떠 있으므로, kubectl logs <pod이름> -c <컨테이너이름> --previous로 직전에 죽은 인스턴스의 로그를 봐야 실제 크래시 원인을 담은 로그를 얻을 수 있다 — --previous 없이 보면 방금 새로 시작한(아직 크래시 전인) 컨테이너의 로그만 보여 원인을 놓치기 쉽다.
핵심 포인트
- kubectl logs <pod> -c <container> --previous로 직전에 죽은 컨테이너 인스턴스의 로그를 확인 — 크래시 원인이 담긴 로그
- --previous 없이 보면 방금 새로 시작한 컨테이너 로그만 보여 원인을 놓칠 수 있음
2단계 — kubectl describe pod로 종료 코드와 Events 타임라인 확인
kubectl describe pod <pod이름>으로는 각 컨테이너의 종료 코드(exit code)와 마지막 상태(lastState), 그리고 Events 섹션의 타임라인을 확인할 수 있다. 예를 들어 lastState.Reason이 OOMKilled이고 Exit Code가 137이면(k8s-learn-05에서 다룬 메모리 limits 초과로 인한 강제종료), 원인이 애플리케이션 로직이 아니라 리소스 설정이라는 쪽으로 진단이 좁혀진다. 반대로 Exit Code가 애플리케이션이 자체적으로 종료할 때 쓰는 값(예: 1)이면, 원인은 애플리케이션 내부 로직이나 설정 쪽으로 좁혀진다.
핵심 포인트
- kubectl describe pod로 exit code, lastState.Reason, Events 타임라인 확인
- Exit Code 137 + Reason: OOMKilled면 k8s-learn-05의 메모리 limits 초과 강제종료 — 원인이 리소스 설정 쪽으로 좁혀짐, 애플리케이션 자체 종료 코드면 로직·설정 쪽으로 좁혀짐
진단 흐름 요약 — 로그(무엇이 실패했나)와 Events(왜 재시작됐나)를 함께 본다
컨테이너의 애플리케이션 로그는 '프로세스 내부에서 왜 실패했는지'를 보여주고, Kubernetes Events는 '그 Pod가 크래시하고 있다는 사실 자체'와 재시작 이력을 확인해준다 — 둘을 함께 봐야 전체 그림이 맞춰진다. 원인이 리소스 제약이면 requests/limits(k8s-learn-05)를 조정하고, 설정·이미지 문제면 설정을 고치거나 이미지를 다시 빌드하고, 의존성 누락이면 필요한 패키지를 포함시키는 식으로 각 원인 유형에 맞는 조치로 이어진다.
핵심 포인트
- 애플리케이션 로그(무엇이 실패했나)+Kubernetes Events(재시작 이력·크래시 확인)를 함께 봐야 전체 그림 완성
- 원인 유형별 대응: 리소스 제약→requests/limits 조정, 설정/이미지 문제→재설정·재빌드, 의존성 누락→패키지 포함