Mar 24, 2026

마지막 업데이트 Mar 30, 2026

Kubernetes ImagePullBackOff: 먼저 볼 것들

Pod 가 ImagePullBackOff 에 걸렸다면 Kubernetes 는 애플리케이션 자체보다 이미지 pull 이 제대로 되지 않는다고 알려 주는 것입니다. 해결 경로도 대개 애플리케이션 내부가 아닙니다. image reference 실수, registry 인증, secret 누락, 혹은 cluster 가 registry 에 접근하지 못하는 문제인 경우가 많습니다.

짧게 말하면 핵심은 이것입니다. 정확한 image reference 와 pod event 부터 봐야 합니다. 가장 빠르게 해결되는 경우는 의외로 가장 단순합니다. 잘못된 image name, 잘못된 tag, 잘못된 registry path, 존재하지 않는 tag 같은 경우죠.

정확한 image reference 부터 본다

secret 이나 네트워크를 보기 전에, Kubernetes 가 정확히 어떤 이미지를 가져오려는지부터 확인해야 합니다.

즉 아래를 봐야 합니다.

full image name
registry hostname
repository path
image tag 또는 digest
pull 관련 pod event

실제 문제는 단순한 image reference 오류인데, 바로 복잡한 인증 문제처럼 파고들다가 시간이 길어지는 경우가 많습니다.

`ImagePullBackOff` 는 보통 무엇을 뜻하나

실전에선 보통 아래 중 하나입니다.

잘못된 image name 또는 tag
registry 인증 실패
빠졌거나 잘못 연결된 imagePullSecrets
기대한 secret 를 참조하지 않는 service account
registry 또는 네트워크 reachability 실패

핵심은 “이미지가 없다” 와 “이미지는 있지만 cluster 가 못 가져온다” 를 구분하는 것입니다.

흔한 원인

1. image name 또는 tag 가 틀렸다

tag 가 존재하지 않거나, registry path 가 틀리거나, repo name 이 조금만 어긋나도 pull 은 바로 실패합니다.

특히 이런 뒤에 자주 보입니다.

수동 tag 변경
manifest 복붙
registry 이동

2. registry 인증이 없다

private registry 는 보통 아래가 필요합니다.

imagePullSecrets
service account 연결
node-level credential

즉 이미지 자체는 멀쩡해도 cluster 에서 접근 권한이 없을 수 있습니다.

3. network 또는 registry availability 가 깨졌다

cluster 에서 registry endpoint 로 못 나가거나, registry 자체가 간헐적으로 실패하는 경우입니다.

이쯤 오면 manifest bug 라기보다 infrastructure connectivity incident 에 가깝습니다.

4. secret 는 있는데 잘못 연결됐다

imagePullSecrets 가 아래일 수 있습니다.

다른 namespace 에 있다
잘못된 service account 에 붙어 있다
pod 에서 전혀 참조하지 않는다

이 경우 secret 는 존재하는데 pod 는 여전히 못 쓰기 때문에 특히 헷갈립니다.

5. image pull policy 또는 rollout 가정이 틀렸다

문제가 auth 나 naming 이 아니라, 어떤 이미지가 이미 있어야 하는지, Kubernetes 가 얼마나 자주 가져오려 하는지에 대한 가정일 수도 있습니다.

rollout 이 잦거나 private registry rate limit 이 있는 환경에서 더 중요합니다.

실전 점검 순서

1. `kubectl describe pod` event 에서 pull error 를 본다

event 문구는 보통 실패 유형을 꽤 직접 말해 줍니다.

not found
unauthorized
forbidden
connection failure
timeout

가장 빠른 첫 단서입니다.

2. full image name 과 tag 를 검증한다

기억에 의존하지 말고, manifest 와 실제 registry 경로를 직접 비교해야 합니다.

3. registry 가 private 인지, credential 이 필요한지 확인한다

필요하다면 pod 가 그 credential 에 도달할 수 있는 실제 경로가 있는지 봐야 합니다.

4. `imagePullSecrets`, service account, namespace 연결을 점검한다

“secret 는 있는데요?” 문제가 가장 많이 풀리는 단계입니다.

5. cluster 가 registry 에 실제 접근 가능한지 확인한다

naming 과 auth 가 맞다면, 그다음은 connectivity 쪽일 가능성이 큽니다.

이 시점부터는 image reference 자체보다 infra path 문제에 가깝습니다.

빠른 명령

kubectl describe pod <pod> -n <ns>
kubectl get secret -n <ns>
kubectl get sa <service-account> -n <ns> -o yaml

정확한 image pull error 와, pod 또는 service account 가 기대한 registry secret 를 실제로 참조하는지 확인하는 데 좋습니다.

ErrImagePull 상세 내용, 잘못되었거나 빠진 imagePullSecrets, 존재하지 않는 tag 또는 registry path 를 먼저 보세요.

failure mode 를 찾은 뒤 무엇을 바꾸면 좋나

tag 또는 name 이 틀렸다면

이미지 reference 를 먼저 고쳐야 합니다. 존재하지 않는 이미지는 인증을 아무리 맞춰도 안 됩니다.

auth 가 빠졌다면

올바른 namespace 의 secret 를, 올바른 pod 또는 service account 경로에 연결해야 합니다.

connectivity 가 깨졌다면

deployment typo 보다 네트워크 또는 registry availability incident 로 다뤄야 합니다.

secret 가 있는데 사용되지 않는다면

service account 또는 pod 참조 경로를 고쳐야 합니다.

rollout 가정이 틀렸다면

pull policy, tag 운영 방식, image publish discipline 을 다시 봐야 합니다.

장애 중에 던져볼 질문

이 질문이 꽤 유용합니다.

Kubernetes 가 실패하는 이유가 image reference 자체가 틀려서인가, credential 이 틀려서인가, 아니면 cluster 가 유효한 registry 에 접근하지 못해서인가?

이 구분만 해도 fix path 가 빠르게 갈립니다.

FAQ

Q. `ImagePullBackOff` 면 무조건 secret 문제인가

아닙니다. 잘못된 tag, repo path, registry connectivity 문제도 흔합니다.

Q. 가장 빠른 첫 단계는 무엇인가

pod event 와 실제 image reference 를 같이 보는 것입니다.

Q. secret 가 있으면 항상 pull 돼야 하나

아닙니다. 올바른 namespace 에 있어야 하고, 올바르게 연결돼 있어야 합니다.

Q. 이건 앱 버그인가

보통은 아닙니다. image, registry, cluster access 쪽 문제인 경우가 많습니다.

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.