ImagePullBackOff 진단 런북

ImagePullBackOff / ErrImagePull은 Pod가 컨테이너 이미지를 가져오지 못해 기동에 실패한 상태입니다. CrashLoopBackOff와 달리 컨테이너 프로세스가 한 번도 뜨지 않은 경우가 많습니다.

30초 체크리스트

1. kubectl get pod <name> -o wide — STATUS가 ImagePullBackOff / ErrImagePull인지 확인
2. kubectl describe pod <name> — Events 맨 아래 Failed / BackOff 메시지 복사
3. 이미지 문자열 확인: registry/repo:tag 오타, digest, latest 의존
4. 프라이빗 레지스트리면 imagePullSecrets / 노드 IAM / 네트워크(방화벽·DNS) 점검
5. 워커 노드에서 동일 이미지 crictl pull 또는 ctr images pull로 재현

Events에서 원인 분류

kubectl describe pod <pod> -n <ns> | sed -n '/Events:/,$p'
kubectl get events -n <ns> --field-selector involvedObject.name=<pod> --sort-by=.lastTimestamp

진단 명령

# 이미지 참조 확인
kubectl get pod <pod> -n <ns> -o jsonpath='{range .spec.containers[*]}{.name}{"\t"}{.image}{"\n"}{end}'

# imagePullSecrets
kubectl get pod <pod> -n <ns> -o jsonpath='{.spec.imagePullSecrets[*].name}{"\n"}'
kubectl get sa default -n <ns> -o yaml | sed -n '/imagePullSecrets/,/^[^ ]/p'

# 노드에서 직접 pull (containerd 예시)
IMAGE=$(kubectl get pod <pod> -n <ns> -o jsonpath='{.spec.containers[0].image}')
NODE=$(kubectl get pod <pod> -n <ns> -o jsonpath='{.spec.nodeName}')
kubectl debug node/$NODE -it --image=busybox -- chroot /host crictl pull "$IMAGE"

원인별 수정

1) 잘못된 태그·레지스트리

# before
image: ghcr.io/acme/api:v1.2.3
# after — 실제 존재하는 태그/digest
image: ghcr.io/acme/api@sha256:…

2) 프라이빗 레지스트리 인증

kubectl create secret docker-registry regcred \
  --docker-server=ghcr.io \
  --docker-username=<user> \
  --docker-password=<token> \
  -n <ns>

# Pod 또는 ServiceAccount에 연결

spec:
  imagePullSecrets:
    - name: regcred

EKS라면 노드 역할 / IRSA가 ECR GetAuthorizationToken·BatchGetImage를 갖는지 확인하세요.

3) 네트워크·DNS

• 노드에서 getent hosts registry.example.com
• HTTP 프록시 환경이면 containerd의 proxy 설정
• 사설 HTTPS면 노드 신뢰 저장소에 CA 추가

4) 레이트 리밋

Docker Hub 익명 pull 한도에 걸리면 인증 pull, 미러, 또는 사내 pull-through cache로 이동하세요.

재발 방지

• 배포 이미지에 mutable latest 금지, digest 고정
• CI에서 crane digest / skopeo inspect로 존재 확인 후 롤아웃
• imagePullPolicy: IfNotPresent는 태그 재사용 시 위험 — digest면 안전
• 클러스터에 레지스트리 미러/캐시

빠른 판정표

ImagePullBackOff는 앱 버그가 아니라 이미지 공급 경로 문제입니다. Events 한 줄만 제대로 읽어도 대부분 5분 안에 갈래가 갈립니다.