🔍 검색 키워드: Kubernetes CrashLoopBackOff 원인, CrashLoopBackOff 재시작 대기 시간, kubectl logs --previous, restartPolicy Always 백오프, maxContainerRestartPeriod 설정, 쿠버네티스 파드 계속 재시작
요약: CrashLoopBackOff는 컨테이너가 시작 직후 계속 종료되어 kubelet이 재시작 간격을 점점 늘리는 중이라는 상태 표시이며, 그 자체가 원인은 아닙니다. kubectl describe로 컨테이너 상태와 재시작 횟수를 보고, kubectl logs --previous로 직전에 죽은 컨테이너의 로그를 확인해 실제 원인을 찾아야 합니다.
CrashLoopBackOff는 무엇을 뜻하나요?
Kubernetes 공식 문서(Pod Lifecycle)는 이 상태를 "백오프 지연 메커니즘이 현재 적용 중이며, 컨테이너가 실패와 재시작을 반복하는 크래시 루프에 있음을 나타낸다"는 취지로 설명합니다. 같은 문서는 CrashLoopBackOff가 kubectl로 파드를 조회하거나 describe할 때 볼 수 있는 상태 또는 이벤트이며, 컨테이너가 제대로 시작하지 못하고 계속 실패하는 경우에 나타난다고 설명합니다. 즉 CrashLoopBackOff는 에러 이름이 아니라 "재시작을 반복하고 있고 대기 중"이라는 현상입니다.
재시작은 얼마 간격으로 일어나나요?
공식 문서에 따르면 파드의 spec에는 restartPolicy 필드가 있고 값은 Always, OnFailure, Never이며 기본값은 Always입니다. 컨테이너가 종료되면 kubelet이 지수 백오프 지연(10초, 20초, 40초, ...)을 두고 다시 시작하며, 지연은 최대 300초(5분)로 제한됩니다. 컨테이너가 문제없이 10분 동안 실행되면 kubelet은 그 컨테이너의 재시작 백오프 타이머를 초기화합니다.
| 재시작 횟수 | 대기 시간(기본값) |
|---|---|
| 1번째 이후 | 10초 |
| 2번째 이후 | 20초 |
| 3번째 이후 | 40초 |
| 이후 계속 2배 | 최대 300초(5분)에서 고정 |
위 표는 공식 문서가 밝힌 규칙(10초에서 시작해 2배씩 증가, 최대 300초)을 정리한 것입니다. 클러스터 버전이나 설정에 따라 값이 다를 수 있습니다.
재시작 대기 시간을 바꿀 수 있나요?
공식 문서의 같은 페이지에는 버전별로 달라진 기능이 두 가지 적혀 있습니다. 문서에 표시된 상태는 이 글을 쓴 시점의 기준이므로, 사용 중인 클러스터 버전에서 지원되는지 반드시 확인하세요.
- 재시작 지연 단축: Kubernetes v1.33부터 알파이며 기본값은 비활성화입니다. 피처 게이트 ReduceDefaultCrashLoopBackOffDecay를 켜면 지연이 1초에서 시작해 2배씩 늘어나고 최대 60초까지로 줄어듭니다.
- 최대 지연 설정: Kubernetes v1.35부터 베타이며 기본 활성화입니다. 피처 게이트 KubeletCrashLoopBackOffMax를 쓰면 노드별 kubelet 설정으로 최대 지연을 기본 300초에서 바꿀 수 있습니다.
kubelet 설정의 crashLoopBackOff 항목에서 maxContainerRestartPeriod 필드를 "1s"에서 "300s" 사이로 지정합니다. 공식 문서에 실린 예시는 다음과 같습니다.
# 지연은 10초에서 시작해 2배씩 늘고, 최대 100초
kind: KubeletConfiguration
crashLoopBackOff:
maxContainerRestartPeriod: "100s"문서에 따르면 설정한 최대값이 기본 초기값 10초보다 작으면 초기 지연이 그 최대값으로 바뀝니다. 다만 이것은 재시작 간격을 조정할 뿐 크래시의 원인을 해결하지는 않습니다.
CrashLoopBackOff는 어떻게 진단하나요?
1단계: 파드 상태와 재시작 횟수 확인
kubectl get pods
kubectl describe pod ${POD_NAME}공식 디버깅 문서는 파드 디버깅의 첫 단계로 kubectl describe pods를 실행해 현재 상태와 최근 이벤트를 보라고 안내합니다. 컨테이너가 모두 Running인지, 최근 재시작이 있었는지를 확인하라고 합니다. describe 출력에는 컨테이너 상태(Waiting, Running, Terminated 중 하나)와 재시작 횟수(Restart Count)가 포함되며, 재시작 횟수는 restartPolicy가 Always인 컨테이너의 크래시 루프를 찾는 데 유용하다고 문서에 설명돼 있습니다. 아래쪽 Events 항목의 Reason과 Message도 함께 보세요.
2단계: 직전에 죽은 컨테이너의 로그 확인
공식 문서는 먼저 문제 컨테이너의 로그를 보고, 컨테이너가 이전에 크래시했다면 이전 컨테이너의 크래시 로그를 --previous 옵션으로 볼 수 있다고 안내합니다.
kubectl logs ${POD_NAME} -c ${CONTAINER_NAME}
kubectl logs ${POD_NAME} -c ${CONTAINER_NAME} --previousCrashLoopBackOff 상태에서는 현재 컨테이너가 막 재시작되어 로그가 비어 있는 경우가 많습니다. 이때 --previous로 직전 실행의 로그를 보는 것이 핵심입니다. 컨테이너가 하나뿐이면 -c 옵션은 생략할 수 있다고 공식 문서에 적혀 있습니다.
3단계: 흔한 원인 후보 점검
아래는 크래시 루프에서 일반적으로 많이 점검하는 항목입니다. 원인은 애플리케이션과 환경마다 다르며, 위 로그와 이벤트로 어느 항목에 해당하는지 확인해야 합니다.
- 애플리케이션이 시작 중 에러로 종료(설정값 누락, 필수 환경변수 없음, 연결 실패 등)
- 컨테이너 command나 args가 잘못되어 프로세스가 곧바로 종료
- 필요한 ConfigMap이나 Secret, 볼륨이 없거나 값이 틀림
- liveness probe 설정이 너무 엄격해 정상 컨테이너가 반복해서 재시작
- 메모리 한도 초과로 종료(describe 출력의 종료 이유와 이벤트로 확인)
주의할 점
- kubectl logs만 보면 재시작 직후의 빈 로그를 보고 원인을 놓치기 쉽습니다. 항상 --previous를 함께 확인하세요.
- 대기 시간이 최대 5분까지 늘어나므로, 원인을 고친 뒤에도 파드가 곧바로 다시 뜨지 않고 한동안 기다릴 수 있습니다. 급하면 파드를 삭제해 새로 만들 수 있습니다.
- 피처 게이트나 kubelet 설정으로 재시작 간격을 줄이면 크래시 루프가 더 자주 반복되어 노드에 부하를 줄 수 있습니다. 원인 해결이 먼저입니다.
- 이 글은 공식 문서를 근거로 정리한 것이며 특정 클러스터에서 직접 실행해 확인한 결과가 아닙니다.
정리표
| 확인할 것 | 명령 또는 설정 | 알 수 있는 것 |
|---|---|---|
| 파드 상태와 재시작 횟수 | kubectl describe pod | 컨테이너 상태, Restart Count, Events |
| 직전 크래시 로그 | kubectl logs --previous | 종료 직전 에러 메시지 |
| 재시작 간격(기본) | 10초부터 2배, 최대 300초 | 대기 시간의 상한 |
| 최대 간격 조정 | kubelet의 maxContainerRestartPeriod | 노드별 상한(1초~300초) |
자주 묻는 질문(FAQ)
CrashLoopBackOff는 에러인가요?
에러 자체가 아니라 컨테이너가 반복해서 실패하고 있어 재시작 대기 중이라는 상태입니다. 실제 원인은 컨테이너 로그와 파드 이벤트에서 찾아야 합니다.
CrashLoopBackOff일 때 로그가 비어 있는데 어떻게 하나요?
현재 컨테이너가 막 재시작된 상태일 수 있습니다. kubectl logs에 --previous 옵션을 붙여 직전에 크래시한 컨테이너의 로그를 확인하세요.
재시작 대기 시간은 최대 얼마까지 늘어나나요?
공식 문서 기준 기본값은 10초에서 시작해 2배씩 늘어 최대 300초(5분)입니다. 컨테이너가 10분 동안 문제없이 실행되면 타이머가 초기화됩니다. 최신 버전에서는 kubelet 설정으로 상한을 바꿀 수 있습니다.
restartPolicy를 바꾸면 해결되나요?
restartPolicy는 종료된 컨테이너를 다시 시작할지를 정하는 값이며 크래시의 원인을 고치지는 않습니다. 원인을 해결하지 않고 정책만 바꾸면 증상이 가려질 수 있습니다.
참고 문서: Kubernetes - Pod Lifecycle · Debug Running Pods · Debug Pods
최종 업데이트: 2026-10-26 · 작성: 내멋스레 사는 이야기
