beautifulsoups.dev
Published on

K8s CrashLoopBackOff 원인 10분 추적법

Authors

CrashLoopBackOff는 증상이 아니라 상태입니다. 쿠버네티스가 컨테이너를 재시작하려고 시도했는데, 짧은 시간 안에 계속 종료되어 백오프(backoff)로 재시작 간격을 늘리는 상황을 말합니다. 중요한 포인트는 두 가지입니다.

  • 무엇이 컨테이너를 종료시켰는가(Exit Code, Signal, OOMKill)
  • 왜 쿠버네티스가 “살아있지 않다”고 판단했는가(프로브, 준비 상태, 의존성)

이 글은 운영 중인 클러스터에서 10분 안에 원인을 좁히는 “추적 루틴”을 제공합니다. 원인 목록을 더 넓게 보고 싶다면 함께 읽을 만한 글로 K8s CrashLoopBackOff 원인 10가지·즉시 진단법도 참고하세요.

0분~1분: 대상 Pod와 컨테이너를 확정하기

먼저 “어떤 Pod의 어떤 컨테이너”가 죽는지 확정해야 합니다. 사이드카가 죽는 경우도 흔합니다.

# 네임스페이스 포함해서 빠르게 확인
kubectl get pod -n my-ns -o wide | grep -i crash

# 특정 파드 자세히
kubectl describe pod -n my-ns my-pod

describe에서 다음을 눈으로 먼저 잡습니다.

  • Containers: 아래 State: Waiting 과 Reason: CrashLoopBackOff
  • Last State: Terminated 의 Exit Code, Reason, Finished
  • Events: 에 반복되는 경고(프로브 실패, 이미지 풀 실패, OOM 등)

여기서 이미 절반은 끝납니다. Exit Code가 137이면 OOMKill 가능성이 크고, 1이면 앱이 자체적으로 실패 종료했을 확률이 큽니다.

1분~3분: “직전 로그”부터 본다 (현재 로그 말고)

CrashLoop 상황에서 가장 흔한 실수는 “현재 실행 중인 컨테이너 로그”만 보는 것입니다. 재시작 직후라 로그가 비어 있을 수 있습니다. 반드시 --previous를 먼저 봅니다.

# 직전 크래시 로그
kubectl logs -n my-ns my-pod -c my-container --previous

# 현재 실행 중 로그(살아있을 때)
kubectl logs -n my-ns my-pod -c my-container -f

로그에서 찾는 키워드 패턴은 다음과 같습니다.

  • 설정/환경: missing env, config not found, permission denied, no such file
  • 네트워크/의존성: connection refused, timeout, dns, x509, certificate
  • 마이그레이션/스키마: migration failed, relation does not exist
  • 런타임: panic, segmentation fault, SIGILL, SIGSEGV

로그가 전혀 없다면 “프로세스가 시작도 못 했거나, stdout으로 아무것도 못 찍고 죽었거나”입니다. 이때는 describe의 Last State와 이벤트, 그리고 command/args를 확인하는 쪽으로 이동합니다.

3분~5분: 종료 원인(Exit Code, Signal, OOMKill)로 분기

여기부터는 “분기”가 핵심입니다. kubectl describe pod의 Last State를 기준으로 아래처럼 갈라집니다.

케이스 A: Reason: OOMKilled 또는 Exit Code: 137

대부분 메모리 상한(resources.limits.memory)에 부딪혀 커널 OOM Killer가 프로세스를 죽인 것입니다.

# 리소스 설정 확인
kubectl get pod -n my-ns my-pod -o jsonpath='{.spec.containers[*].resources}'

# 메트릭 서버가 있다면 현재 사용량 확인
kubectl top pod -n my-ns my-pod
kubectl top pod -n my-ns --containers | grep my-pod

즉시 취할 액션:

  • limits.memory를 올리거나, 메모리 누수/캐시 설정을 점검
  • JVM/Node/Go 런타임이면 힙 상한을 명시적으로 조정
  • 대용량 초기 로딩(예: 모델, 사전, 캐시)을 지연 로딩으로 변경

주의: 메모리 requests만 높이고 limits가 낮으면, 스케줄은 되지만 실행 중 죽습니다. 반대로 limits만 높고 requests가 너무 낮으면 노드 압박으로 다른 프로세스와 경쟁하다가 불안정해질 수 있습니다.

케이스 B: Exit Code: 1 (일반 오류 종료)

앱이 “정상적으로 시작하지 못했다”고 선언하고 종료한 케이스입니다. 로그가 가장 중요합니다.

바로 확인할 것:

  • 잘못된 환경변수/시크릿
  • 마이그레이션 실패
  • 외부 의존성(DB, Kafka, Redis) 연결 실패
# 환경변수/시크릿 참조 확인(값 자체를 찍지 말고 참조가 유효한지)
kubectl get deploy -n my-ns my-deploy -o yaml | sed -n '1,200p'

# 시크릿/컨피그맵 존재 여부
kubectl get secret -n my-ns | grep my-secret
kubectl get configmap -n my-ns | grep my-config

시크릿 키 이름이 바뀌었거나, envFrom의 ConfigMap이 누락되면 “시작 즉시 종료”로 이어집니다.

케이스 C: Exit Code: 139 또는 시그널 관련(세그폴트)

네이티브 라이브러리, 아키텍처 불일치, 런타임 버그, 이미지/빌드 문제 가능성이 큽니다.

# 이미지와 실행 커맨드 확인
kubectl get pod -n my-ns my-pod -o jsonpath='{.spec.containers[0].image}{"\n"}{.spec.containers[0].command}{"\n"}{.spec.containers[0].args}{"\n"}'

특히 amd64 노드에 arm64 이미지를 올리거나(반대도 포함), distroless 이미지에서 필요한 라이브러리가 빠진 경우가 많습니다.

5분~7분: 프로브(liveness/readiness/startup)로 인한 “강제 재시작” 확인

애플리케이션이 사실은 살아 있는데, 프로브 설정이 공격적이어서 쿠버네티스가 죽인 뒤 재시작시키는 경우가 있습니다. Events에 아래가 반복되면 거의 확정입니다.

  • Liveness probe failed
  • Readiness probe failed
  • Back-off restarting failed container
# 프로브 설정만 빠르게 보기
kubectl get pod -n my-ns my-pod -o jsonpath='{.spec.containers[0].livenessProbe}{"\n"}{.spec.containers[0].readinessProbe}{"\n"}{.spec.containers[0].startupProbe}{"\n"}'

자주 발생하는 함정:

  • 초기 부팅이 느린데 startupProbe 없이 livenessProbe만 둔 경우
  • initialDelaySeconds가 너무 짧고, timeoutSeconds가 너무 짧은 경우
  • 앱은 0.0.0.0이 아니라 127.0.0.1에만 바인딩하는데, 프로브는 Pod IP로 접근하는 경우
  • HTTP 프로브 경로가 리다이렉트/인증으로 바뀐 경우(예: /health가 로그인 필요)

프로브 튜닝의 기본 방향:

  • “부팅 완료 전”은 startupProbe로 보호
  • “일시적 지연”은 failureThreshold와 periodSeconds로 흡수
  • “정말 죽었을 때만” livenessProbe가 재시작을 유도

7분~9분: 스케줄/볼륨/권한 문제로 시작 자체가 꼬이는지 확인

CrashLoop로 보이지만 실제로는 컨테이너가 정상 실행을 못 하고 준비 과정에서 실패하는 경우가 있습니다.

볼륨 마운트/권한

describe의 이벤트에 다음이 있으면 볼륨/권한 쪽입니다.

  • MountVolume.SetUp failed
  • permission denied
kubectl describe pod -n my-ns my-pod | sed -n '/Events:/,$p'

조치 포인트:

  • securityContext.runAsUser, fsGroup 미설정으로 파일 접근 실패
  • readOnlyRootFilesystem: true 인데 앱이 /tmp나 작업 디렉터리에 쓰려는 경우
  • PVC 바인딩/스토리지 클래스 문제

이미지 풀/레지스트리 인증

이건 보통 ImagePullBackOff지만, 재시작 과정에서 섞여 보일 때도 있습니다.

  • Failed to pull image
  • ErrImagePull

레지스트리 토큰 만료, imagePullSecrets 누락을 확인합니다.

9분~10분: 재현 가능한 “단발 실행”으로 원인 고정하기

원인을 거의 좁혔다면, 동일 이미지로 “프로브 없이” 단발 실행을 만들어 로그/행동을 고정시키는 게 빠릅니다. 운영 리소스를 직접 건드리기 어렵다면 임시 Pod로 재현합니다.

# 같은 이미지로 임시 디버그 파드 실행(명령은 상황에 맞게)
kubectl run -n my-ns crash-debug \
  --image=my-registry/my-image:tag \
  --restart=Never \
  --command -- sh -c 'env; ./app --version; ./app'

# 로그 확인
kubectl logs -n my-ns crash-debug

# 필요 시 파드 내부 진입(이미지에 sh가 있어야 함)
kubectl exec -n my-ns -it crash-debug -- sh

distroless처럼 셸이 없는 이미지라면, 별도 디버그 이미지(예: busybox, alpine)를 같은 네임스페이스에서 띄우고 네트워크/ DNS/ TLS만 확인하는 방식이 현실적입니다.

실전 체크리스트: 10분 루틴을 한 장으로 요약

아래 순서대로만 하면 “감”이 아니라 “증거”로 좁힙니다.

  1. kubectl describe pod로 Last State, Exit Code, Events 확보
  2. kubectl logs --previous로 직전 크래시 로그 확보
  3. Exit Code 137이면 메모리/OOM 분기, Exit Code 1이면 설정/의존성 분기
  4. Events에 프로브 실패가 반복되면 프로브 튜닝/경로 확인
  5. 볼륨/권한/시크릿 누락은 Events와 spec에서 바로 드러남
  6. 임시 Pod로 단발 실행해 재현하고 원인을 고정

자주 나오는 원인별 “증거”와 즉시 처방

DB 의존성(연결 실패)로 즉시 종료

  • 증거: 로그에 connection refused, timeout, password authentication failed
  • 처방: 네트워크 정책/서비스 DNS/시크릿/커넥션 스트링 확인, 앱 시작 시 재시도(backoff) 추가

마이그레이션을 앱 시작에 묶어둔 경우

  • 증거: migration failed 후 종료
  • 처방: 마이그레이션을 Job으로 분리하거나, 실패 시 롤백/재시도 전략 수립

DB 락/교착이 의심되면 애플리케이션 크래시로만 보지 말고 데이터베이스 관점에서 확인이 필요합니다. 이 경우 PostgreSQL 데드락(40P01) 원인·해결 9단계가 원인 좁히기에 도움이 됩니다.

설정 스크립트에서 set -e로 조기 종료

엔트리포인트 셸 스크립트가 작은 실패에도 즉시 종료하면서 CrashLoop가 나는 경우가 많습니다.

  • 증거: 로그가 짧고, 특정 커맨드 실패 직후 종료
  • 처방: 안전한 예외 처리, 명시적 에러 메시지, 필수/선택 단계 분리

관련해서 셸 스크립트의 실패 처리 패턴은 bash set -euo pipefail 함정과 안전한 예외처리를 참고하면 시행착오를 줄일 수 있습니다.

결론: CrashLoopBackOff는 “원인 수렴 속도”가 전부다

CrashLoopBackOff를 해결하는 가장 빠른 방법은 복잡한 추측이 아니라, describe의 Last State와 Events, 그리고 --previous 로그로 증거를 모아 분기하는 것입니다. 10분 루틴으로도 대부분의 케이스는 OOM, 프로브, 설정/시크릿, 의존성 연결, 권한/볼륨 중 하나로 수렴합니다.

다음 장애에서 시간을 더 줄이려면, 평소에 아래를 준비해 두면 좋습니다.

  • 애플리케이션 시작 로그에 “환경/의존성 체크 결과”를 명확히 남기기
  • 프로브를 서비스 특성에 맞게 튜닝하고, 초기 부팅은 startupProbe로 보호
  • 리소스 requests/limits를 근거 있는 값으로 관리하고 OOM 시그널을 관측 가능하게 만들기

이 정도만 갖춰도 CrashLoopBackOff는 ‘공포의 상태’가 아니라 ‘빠르게 추적 가능한 이벤트’가 됩니다.

Discuss on Twitter • View on GitHub