Kubernetes ImagePullBackOff 해결: 이미지 태그·imagePullSecrets·네트워크 점검

AI로 제작한 개념 일러스트입니다. 다운로드 실패는 이미지 참조·인증·노드 연결 경로를 나누어 확인합니다.

Kubernetes Pod가 ImagePullBackOff에 머물면 애플리케이션 로그부터 찾기보다 Pod의 이벤트를 먼저 확인하세요. 이미지를 내려받지 못해 컨테이너가 시작되지 않은 상태일 수 있습니다. 이미지 주소·태그, 인증정보와 네임스페이스, 노드의 네트워크·TLS·지원 아키텍처를 순서대로 좁히면 불필요한 재배포를 줄일 수 있습니다.

1. ImagePullBackOff와 실행 뒤 장애 구분하기

Kubernetes 이미지 공식 문서는 ImagePullBackOff를 이미지 다운로드 실패 후 간격을 늘려 재시도하는 상태로 설명합니다. 상태 이름 자체가 근본 원인은 아닙니다. 이벤트에 적힌 상세 오류를 읽어야 합니다. 다운로드가 끝난 뒤 프로세스가 반복 종료되는 CrashLoopBackOff와도 구분하세요.

2. Pod 이벤트와 실제 이미지 주소 읽기

다음은 가상 네임스페이스 demo와 Pod api-demo의 조회 예시입니다. 이름은 실제 값으로 바꾸세요. Secret의 인증값을 출력하지 않고 상태와 연결 관계부터 확인하는 순서입니다.

kubectl get pod api-demo -n demo -o wide
kubectl describe pod api-demo -n demo
kubectl get pod api-demo -n demo -o jsonpath='{.spec.containers[*].image}'
kubectl get pod api-demo -n demo -o jsonpath='{.spec.imagePullSecrets[*].name}'
kubectl get secret regcred -n demo
kubectl get nodes -L kubernetes.io/arch

describe 출력의 Events에서 실패 시각과 상세 메시지를 확인합니다. init container가 실패한 경우에는 일반 containers 이미지 목록만으로 부족하므로 해당 init container 이미지도 함께 읽습니다. 오류 원문을 공유할 때 내부 저장소 주소와 개인 정보는 필요한 범위로 가리고, 인증정보가 담긴 Secret 데이터는 첨부하지 마세요.

3. 메시지별 점검표

이벤트의 단서	우선 확인	조치 방향
not found·manifest unknown	주소·태그가 실제로 존재하는지	릴리스 이미지 참조를 대조
unauthorized·denied	주체의 다운로드 권한·인증 갱신	공개 전환보다 인증 경로 점검
FailedToRetrieveImagePullSecret	Secret 이름과 Pod 네임스페이스	같은 네임스페이스의 참조 확인
x509·timeout	노드에서 레지스트리까지의 경로	TLS 신뢰·DNS·방화벽·프록시 확인
no matching manifest	노드 OS·CPU와 이미지 지원 목록	지원되는 플랫폼으로 빌드·참조

오류 문자열은 런타임과 레지스트리에 따라 다릅니다. 표는 후보를 좁히기 위한 안내이며 한 단어만 보고 설정을 변경하는 규칙은 아닙니다. 예를 들어 timeout이면 노드가 레지스트리에 접근하는 경로를 먼저 보고, denied이면 실제 다운로드 주체와 해당 저장소 권한을 대조합니다.

4. imagePullSecrets는 같은 네임스페이스에 있어야 합니다

비공개 레지스트리 이미지 다운로드 공식 안내는 imagePullSecrets로 참조한 Secret이 Pod와 같은 네임스페이스에 있어야 한다고 설명합니다. 아래는 이미 존재하고 적절히 구성된 regcred를 참조하는 설명용 Pod입니다. 가상 이미지 주소이므로 그대로 배포해도 실행되는 예제가 아닙니다.

apiVersion: v1
kind: Pod
metadata:
  name: api-demo
  namespace: demo
spec:
  imagePullSecrets:
    - name: regcred
  containers:
    - name: api
      image: registry.example.com/team/api:2026.09.28
      imagePullPolicy: IfNotPresent

가상 상황에서 default 네임스페이스에는 regcred가 있는데 demo에서 실행한 Pod가 이를 찾지 못한다면, 비밀번호 변경보다 이름과 네임스페이스를 먼저 확인합니다. Deployment에서는 실제 Pod 템플릿의 spec.imagePullSecrets도 확인하세요. 로컬 Docker 로그인 성공은 클러스터 노드의 인증 성공을 증명하지 않습니다. 관리형 환경의 자격증명 제공자 등 별도 인증 방식도 사용 중인지 파악합니다.

5. 태그·캐시·아키텍처와 자주 묻는 질문

태그는 다른 이미지로 이동할 수 있으므로 릴리스 기록에 다이제스트를 함께 남기면 추적에 도움이 됩니다. imagePullPolicy는 처음 생성될 때 설정된 값을 확인하세요. 나중에 태그만 latest로 바꾸었다고 정책도 자동으로 바뀐다고 가정하면 안 됩니다. 멀티 아키텍처 이미지는 해당 노드 플랫폼을 포함하는지 확인합니다.

Pod를 지우면 해결되나요? 재시도는 일어나도 잘못된 이미지 주소·권한은 그대로입니다. 이벤트를 보존하고 원인을 수정하는 것이 먼저입니다.

Always로 바꾸면 모든 이미지 오류가 해결되나요? 다운로드 정책이 존재하지 않는 태그나 부족한 권한을 고치지는 않습니다. 캐시 사용과 다운로드 여부를 결정하는 정책으로 이해하세요.

이미지는 받아졌는데 계속 재시작해요. 다운로드 단계 이후의 종료 코드·프로브·프로그램 오류를 조사할 차례입니다. 다른 단계의 장애를 같은 처방으로 처리하지 마세요.

6. 복구 완료 기준을 정하기

정상 복구는 해당 Pod의 이미지 다운로드 성공, 필요한 컨테이너 시작, 준비 상태와 실제 서비스 응답까지 확인하는 것입니다. 실행 뒤 반복 종료 문제가 남으면 기존 CrashLoopBackOff 해결 순서 글로 이어서 점검하세요. 실패 이벤트와 수정한 참조·인증 경로를 남기면 다음 릴리스에서도 같은 순서로 검증할 수 있습니다.

자료 확인: 2026년 9월 28일. 제품 기능·요금·지원 범위는 변경될 수 있으므로 도입 직전 공식 문서와 해당 계정의 설정을 확인하세요.