Kubernetes: Pod이 ImagePullBackOff에서 멈춤

안녕하세요, BlueByte입니다. ImagePullBackOff에서 벗어나지 못하는 Pod는 크래시가 난 게 아닙니다 — 스케줄링은 정상이었지만 kubelet이 컨테이너 이미지를 가져오지 못해 계속 재시도하며 back-off하는 상태입니다. 증상은 Pod가 0/1에 멈춘 채 STATUS: ImagePullBackOff(조금 전에는 ErrImagePull)로 표시되는 것입니다. 오늘은 이 두 상태가 뜻하는 것, Events를 읽어 진짜 원인을 찾는 법, 원인별 해결, 그리고 예방까지 하나씩 짚어보겠습니다.

ImagePullBackOff와 ErrImagePull이 알려주는 것

kubectl get pods에 관련된 두 상태가 나타납니다:

NAME                    READY   STATUS             RESTARTS   AGE
web-6d4b8f9c7c-2xk9p    0/1     ImagePullBackOff   0          3m

ErrImagePull은 즉각적인 실패입니다: kubelet이 컨테이너 런타임에 이미지 pull을 요청했고 그 pull이 실패했습니다. ImagePullBackOff는 그 뒤에 이어지는 상태로, 실패가 반복되면 kubelet이 다시 시도하기 전에 대기하며 매번 지연을 늘려 최대 5분까지 갑니다. 둘 다 애플리케이션이 깨졌다는 뜻은 아닙니다. 이미지가 도착하지 못해 컨테이너가 아예 시작되지 않은 것뿐입니다.

kubelet이 이미지를 가져오지 못하는 이유

pull은 몇 가지 구체적인 이유 중 하나로 실패합니다:

• 이미지 이름이나 레지스트리가 틀림 — 오타이거나, 레지스트리 접두사가 빠져 Docker Hub로 기본 처리됨.
• 태그가 존재하지 않음 — 이미지는 실제로 있지만 :1.2.3을 푸시한 적이 없거나, :1.2.3을 의도했는데 :1.23으로 입력함.
• 이미지가 프라이빗인데 Pod에 자격 증명이 없음 — 레지스트리가 authorization 오류로 응답함.
• 레지스트리 레이트 리밋에 걸림(Docker Hub는 익명 pull을 제한) — 지금은 pull이 거부됨.
• imagePullPolicy: Never가 설정됐지만 이미지가 노드에 이미 존재하지 않음.

Events를 읽어 진짜 원인 확인하기

추측하지 마세요 — kubectl describe 아래쪽 Events가 정확한 실패를 알려줍니다:

kubectl describe pod web-6d4b8f9c7c-2xk9p

Events:
  Type     Reason   Age               From     Message
  ----     ------   ----              ----     -------
  Warning  Failed   30s (x4 over 2m)  kubelet  Failed to pull image "myrepo/app:1.2.3":
                                               manifest unknown: manifest unknown
  Warning  Failed   30s (x4 over 2m)  kubelet  Error: ErrImagePull
  Normal   BackOff  5s  (x6 over 2m)  kubelet  Back-off pulling image "myrepo/app:1.2.3"

Message가 전부입니다. manifest unknown은 태그가 없다는 뜻, pull access denied나 unauthorized는 프라이빗인데 인증이 안 됐다는 뜻, no such host는 레지스트리 이름이 틀렸다는 뜻입니다. 노드나 로컬에서 같은 이미지를 직접 pull해 확인해 보세요:

docker pull myrepo/app:1.2.3

같은 방식으로 실패하면 문제는 Kubernetes가 아니라 이미지나 자격 증명입니다.

원인별로 고치기: 이름·태그·프라이빗 레지스트리

1. 이름이나 태그가 틀림 — 레지스트리에 태그가 있는지 먼저 확인하고, 참조를 고쳐 다시 적용합니다:

kubectl set image deployment/web app=myrepo/app:1.4.0

2. 프라이빗 레지스트리 — pull secret을 만들어 Pod 템플릿에 연결합니다:

kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=<user> \
  --docker-password=<token>

spec:
  imagePullSecrets:
    - name: regcred

3. Docker Hub 레이트 리밋 — 같은 secret 방식으로 인증하거나, 이미지를 자체 레지스트리로 미러링합니다.

실제 사례: pull secret 없는 프라이빗 이미지

registry.example.com/team/api:2.1.0을 배포했는데 Pod가 ImagePullBackOff에 멈춥니다. kubectl describe pod는 Failed to pull image ...: pull access denied, repository does not exist or may require authorization을 보여줍니다. 이미지는 실제로 있고 푸시됐으니 authorization 문제입니다. kubectl create secret docker-registry regcred ...로 pull secret을 만들고, Deployment의 Pod 템플릿에 imagePullSecrets: [{ name: regcred }]을 추가한 뒤 kubectl rollout restart deployment/api를 실행합니다. 몇 초 안에 새 Pod가 이미지를 pull하고 1/1 Running에 도달합니다. 레지스트리는 처음부터 닿아 있었고, kubelet에 제시할 자격 증명이 없었을 뿐입니다.

Pod가 정말 Running인지 확인하기

고친 뒤 Pod가 올라오는지 지켜봅니다:

kubectl get pod -l app=api -w

NAME                   READY   STATUS    RESTARTS   AGE
api-7c9d5f8b6d-abcde   1/1     Running   0          12s

1/1과 Running에 restart가 없으면 이미지가 pull됐고 컨테이너가 시작된 것입니다. 이제 kubectl describe pod는 Failed 대신 Pulled 이벤트를 보여줍니다.

다시 생기지 않게 예방하기

이미지를 :latest가 아니라 실제 불변 태그나 digest로 고정하세요. 그러면 재태깅되거나 삭제된 태그에 Pod가 걸리지 않습니다 — :latest면 기본 imagePullPolicy가 Always라 재시작마다 다시 pull합니다. 레지스트리 자격 증명은 프라이빗 레지스트리가 필요한 모든 워크로드가 참조하는 Secret으로 두고, Docker Hub를 대규모로 쓴다면 인증된 미러를 통해 pull해 레이트 리밋 아래로 유지하세요. 롤아웃 전에 kubectl apply --dry-run=server -f pod.yaml로 스펙을 검증해 잘못된 이미지 참조를 미리 잡으세요.

CrashLoopBackOff와 무엇이 다른가

ImagePullBackOff는 컨테이너가 실행되기 전에 생깁니다 — 이미지가 아예 도착하지 못했습니다. CrashLoopBackOff는 그 이후입니다: 이미지는 잘 pull됐고, 컨테이너가 시작됐다가 반복해서 종료됩니다. kubectl describe에 Pulled 이벤트가 보이는데도 Pod가 계속 재시작한다면 그것은 CrashLoopBackOff이며, 이미지 참조가 아니라 컨테이너 로그를 읽어야 합니다. 둘 다 같은 지수 back-off를 쓰지만, 원인은 "이미지가 로드됐는가"의 반대편에 있습니다.