CrashLoopBackOff 원인 분석 및 해결 방법

개요

---

Kubernetes를 운영하면서 가장 자주 마주하는 이슈 중 하나가 CrashLoopBackOff입니다. 이 글에서는 CrashLoopBackOff가 발생하는 이유를 살펴보고, 그중 컨테이너 이미지 태그 오류로 인해 발생하는 사례를 재현하여 분석해 보겠습니다.

CrashLoopBackOff란?

---

CrashLoopBackOff는 Kubernetes에서 특정 Pod가 지속적으로 충돌(Crash)하여 재시작을 반복하는 상태를 의미합니다. 일반적으로 Pod가 실행되었다가 비정상적으로 종료되면, kubelet은 이를 다시 시작하려고 합니다. 하지만 계속해서 실패하면 일정 시간 동안 재시도 간격을 늘려가며 CrashLoopBackOff 상태를 반복하게 됩니다.

 

발생 가능한 원인

---

CrashLoopBackOff가 발생하는 주요 원인은 다음과 같습니다.

• 잘못된 컨테이너 이미지 태그: 이미지 레지스트리에서 해당 태그를 찾을 수 없음
• 애플리케이션 내부 오류: 코드 버그, 의존성 문제, 환경 변수 설정 오류
• 권한 문제: 애플리케이션이 실행되기 위한 권한 부족
• 네트워크 문제: 외부 서비스와의 통신 실패로 인해 앱이 종료됨
• OOMKilled(Out of Memory): 컨테이너가 메모리 초과로 종료됨
• Liveness Probe 실패: Kubernetes가 컨테이너가 비정상적으로 동작한다고 판단하여 재시작함

이번 글에서는 "잘못된 컨테이너 이미지 태그"로 인해 CrashLoopBackOff가 발생하는 시나리오를 다뤄보겠습니다.

잘못된 컨테이너 이미지 태그로 인해 CrashLoopBackOff 발생

---

잘못된 이미지 태그를 가진 Deployment 생성

아래의 Deployment 파일을 보면 image: nginx:invalid-tag라는 존재하지 않는 태그를 사용하고 있습니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:invalid-tag  # 존재하지 않는 태그
        ports:
        - containerPort: 80

 

 

이제 이 Deployment를 생성합니다.

kubectl apply -f nginx-deployment.yaml

 

Pod 상태 확인

Deployment를 생성한 후 Pod 상태를 확인하면 다음과 같이 ImagePullBackOff 또는 ErrImagePull 상태가 나타납니다.

kubectl get pods

 

출력 예시:

NAME                                 READY   STATUS             RESTARTS   AGE
nginx-deployment-5d4b5b4b7f-abcde    0/1     ImagePullBackOff   0          1m

 

이후 Kubernetes가 지속적으로 재시도를 하다가 일정 시간이 지나면 CrashLoopBackOff 상태로 전환됩니다.

kubectl describe pod nginx-deployment-5d4b5b4b7f-abcde

 

출력 예시:

Events:
  Type     Reason             Age                From               Message
  ----     ------             ----               ----               -------
  Normal   Scheduled          2m                 default-scheduler  Successfully assigned default/nginx-deployment-5d4b5b4b7f-abcde to node01
  Normal   Pulling            2m                 kubelet            Pulling image "nginx:invalid-tag"
  Warning  Failed             2m                 kubelet            Failed to pull image "nginx:invalid-tag": rpc error: code = NotFound desc = failed to pull and unpack image "nginx:invalid-tag"
  Warning  Failed             2m                 kubelet            Error: ErrImagePull
  Normal   BackOff            1m (x3 over 2m)    kubelet            Back-off pulling image "nginx:invalid-tag"
  Warning  Failed             1m                 kubelet            Error: ImagePullBackOff

 

해결 방법

---

1. 컨테이너 이미지 태그 확인

• 올바른 태그를 사용하고 있는지 체크합니다.
• 사용 가능한 태그 목록은 공개된 컨테이너 이미지 레지스트리 또는 프라이빗 컨테이너 이미지 레지스트리에서 확인할 수 있습니다.

docker pull nginx:latest

사용가능한 이미지와 태그를 Docker Hub를 통해 받아옵니다.

 

2. Deployment 수정 nginx:latest 또는 기존에 존재하는 태그로 변경하고, 다시 배포합니다.

containers:
- name: nginx
  image: nginx:latest  # 존재하는 태그로 변경

kubectl apply -f nginx-deployment.yaml

 

3. Pod 삭제 및 재시작 기존 Pod를 삭제하고 새로운 Pod를 배포합니다.

kubectl delete pod nginx-deployment-5d4b5b4b7f-abcde

 

Kubernetes가 새롭게 생성하는 Pod에서 정상적으로 이미지가 받아지면 문제가 해결됩니다.

 

4. 프라이빗 레지스트리 사용 시 인증 확인 만약 내부 레지스트리를 사용한다면, 인증 문제가 원인일 수도 있습니다. 해당 경우, imagePullSecrets을 추가하여 해결할 수 있습니다.

spec:
  imagePullSecrets:
  - name: my-registry-secret

 

정리

---

CrashLoopBackOff는 Kubernetes에서 흔히 발생하는 문제 중 하나이며, 여러 가지 원인으로 인해 발생할 수 있습니다. 이번 글에서는 컨테이너 이미지 태그 오류로 인해 발생하는 CrashLoopBackOff 문제를 분석하고 해결하는 방법을 살펴보았습니다.

Kubernetes 환경에서 CrashLoopBackOff가 발생하면 다음을 확인해보셔야 합니다.

• kubectl describe pod <POD_NAME> 명령어로 이벤트 로그 분석
• kubectl logs <POD_NAME> 명령어로 컨테이너 로그 확인
• kubectl get events 명령어로 클러스터 이벤트 체크

운영 환경에서 발생하는 CrashLoopBackOff는 다양한 원인으로 발생할 수 있으므로, 본 글에서 다룬 내용들이 빠르게 대응하는데 도움이 되셨으면 좋겠습니다.