Kubernetes 파드가 CrashLoopBackOff에 멈춤

안녕하세요, BlueByte입니다. CrashLoopBackOff는 무섭게 보이지만, 컨테이너가 시작 직후 계속 종료된다고 Kubernetes가 알려주는 것뿐입니다. 원인이 아니라 증상이죠. 오늘은 원인을 실제로 짚어주는 두 가지 — 이전 컨테이너의 로그와 종료 코드 — 를 읽고, 추측 대신 진짜 문제를 고치는 순서로 가보겠습니다.

CrashLoopBackOff가 (아닌) 것

파드가 Running에 못 이릅니다:

NAME        READY   STATUS             RESTARTS   AGE
api-7d9f    0/1     CrashLoopBackOff   5          3m

컨테이너가 시작하고, 종료되고, kubelet이 재시작합니다 — 매번 더 길게 물러서면서(10s, 20s, 40s, 최대 5분). 상태는 그 반복이지 이유가 아닙니다. 이유는 컨테이너를 종료시키는 무언가이고, 그건 로그와 종료 코드에 있습니다.

몇 안 되는 원인, 각각의 지문

주 프로세스가 시작 직후 종료되는 것입니다. 흔한 이유는 각각 알아볼 수 있습니다:

• 시작 시 애플리케이션 오류 — 누락된 환경변수, 닿지 않는 의존성(아직 안 뜬 DB), 잘못된 설정. 종료 코드는 대개 1이나 2, 로그에 스택 트레이스.
• 메모리 초과 — 메모리 한도를 넘어 kill됨. 종료 코드 137(SIGKILL), 이유 OOMKilled.
• 앱이 느리게 떠서 liveness 프로브가 실패.
• 잘못된 command나 entrypoint — 프로세스가 즉시 종료되거나 바이너리를 못 찾음, 로그가 비어 있는 경우가 많음.
• 볼륨·시크릿 누락 — 앱이 설정을 못 읽고 죽음.

이전 컨테이너의 로그와 종료 코드 읽기

이게 일의 전부입니다. 지금 뜨는 인스턴스가 아니라 이미 죽은 인스턴스를 읽으세요:

kubectl logs api-7d9f --previous

그다음 종료 코드와 이유:

kubectl describe pod api-7d9f

Last State: Terminated를 보세요. 137 + OOMKilled는 메모리, 1/2는 로그가 설명하는 앱 오류, Liveness probe failed 이벤트는 프로브, Events 목록은 누락된 ConfigMap·Secret·마운트를 짚어 줍니다.

구체적 원인을 고치기

• 앱 오류: 누락된 환경변수를 넣거나, 설정을 고치거나, 의존성이 닿게 한 뒤 파드가 재시작되게 둡니다.
• OOMKilled (137): 메모리 한도를 올리거나 사용량을 줄입니다:

resources:
  limits:
    memory: "512Mi"

• liveness 프로브가 너무 빡셈: 앱이 뜰 시간을 줍니다:

livenessProbe:
  httpGet: { path: /healthz, port: 8080 }
  initialDelaySeconds: 30

실제 사례: 누락된 환경변수

kubectl get pods가 api-7d9f를 재시작 6회의 CrashLoopBackOff로 보여줍니다. kubectl logs api-7d9f --previous는 Error: DATABASE_URL is not set만 찍고 끝이며, kubectl describe pod는 Exit Code: 1을 확인해 줍니다. 원인이 분명합니다 — 메모리도 프로브도 아닙니다. 배포의 env(또는 참조된 Secret)에 DATABASE_URL을 추가해 적용하면, 다음 재시작이 Running에 이르고 카운트가 멈춥니다. 이전 로그를 먼저 읽은 덕에, 원인도 아닌 메모리 한도를 올리는 헛수고를 피했습니다.

안정됐는지 확인

파드를 지켜보세요:

kubectl get pod api-7d9f -w

READY 1/1의 Running으로 옮겨가고 RESTARTS가 더 오르지 않아야 합니다. 재시작이 계속 오르면, 로그가 아직 해결 안 된 원인을 짚고 있는 것입니다.

ImagePullBackOff·Pending과의 구분

ImagePullBackOff는 kubectl get pods에서 비슷해 보이지만 이미지가 아예 시작되지 못한 것입니다 — 이름이나 레지스트리 자격 증명이 틀린 것이죠. Pending은 파드가 스케줄되지 못한 것(자리 있는 노드가 없음)입니다. CrashLoopBackOff는 컨테이너가 실제로 돌다가 종료된 것이라, 로그와 종료 코드가 지도가 되는 유일한 경우입니다. 메모리 한도를 신중히 잡고, 프로브를 넉넉히 두고, 의존성은 init 컨테이너로 기다리게 해서 파드가 반복하지 않고 대기하게 하세요.