Kubernetes Rancher에서 Init:ImagePullBackOff 발생 원인과 확인 방법

Kubernetes Rancher에서 Init:ImagePullBackOff 발생 원인과 확인 방법

Rancher에서 Kubernetes 클러스터의 Worker Node 또는 Pod 상태를 확인하다 보면 Init:ImagePullBackOff 상태와 함께 다음과 같은 메시지가 표시될 수 있습니다.

Init:ImagePullBackOff
containers with incomplete status: [init-kubeconfig-volume]

이 상태는 일반적으로 Pod의 메인 컨테이너가 문제가 아니라, 먼저 실행되어야 하는 Init Container의 이미지를 가져오지 못하고 있다는 의미입니다. Kubernetes에서 Init Container는 애플리케이션 컨테이너보다 먼저 실행되며, 모든 Init Container가 성공적으로 완료되어야 메인 컨테이너가 시작됩니다.

Init:ImagePullBackOff는 어떤 상태인가?

해당 메시지를 실행 순서로 보면 다음과 같습니다.

Pod 생성
  ↓
Init Container 시작 준비
  ↓
init-kubeconfig-volume 이미지 Pull 시도
  ↓
이미지 Pull 실패
  ↓
Init:ImagePullBackOff
  ↓
메인 Container 시작 대기

따라서 init-kubeconfig-volume이라는 이름만 보고 kubeconfig 파일이나 Volume 자체의 문제라고 판단하면 안 됩니다. 현재 ImagePullBackOff가 명시되어 있다면 우선 확인해야 할 대상은 해당 Init Container가 사용하는 이미지와 Registry 접근 과정입니다.

Kubernetes의 ImagePullBackOff는 kubelet이 컨테이너 이미지를 가져오지 못해 컨테이너를 시작할 수 없고, 재시도 간격을 늘리면서 이미지 Pull을 계속 시도하고 있음을 의미합니다.

Rancher에서 가장 먼저 확인할 항목

Rancher에서는 문제가 발생한 Worker Node만 확인하기보다 실제 Init:ImagePullBackOff 상태인 Pod의 상세 화면으로 들어가는 것이 중요합니다.

1. Rancher에서 대상 Cluster로 이동합니다.
2. Workloads 또는 Pods에서 문제가 발생한 Pod를 찾습니다.
3. Pod 상세 화면을 엽니다.
4. Events를 확인합니다.
5. Init Containers에서 init-kubeconfig-volume의 Image 값을 확인합니다.

Events에는 실제 이미지 Pull 실패 원인이 비교적 구체적으로 기록됩니다. 예를 들어 다음과 같은 메시지를 확인할 수 있습니다.

Failed to pull image "harbor.example.com/project/image:v1.2.3"

ErrImagePull

Back-off pulling image "harbor.example.com/project/image:v1.2.3"

Events 메시지별 주요 원인

ImagePullBackOff 주요 오류와 확인 대상

Events 메시지	주요 원인	우선 확인 대상
unauthorized	Registry 인증 실패	계정, 비밀번호, Token, imagePullSecret
pull access denied	이미지 접근 권한 문제	Registry 프로젝트 권한, imagePullSecret
manifest unknown	지정한 이미지 또는 Tag를 찾을 수 없음	Repository와 Tag 존재 여부
not found	이미지 경로 또는 Tag 오류	Image 주소 확인
i/o timeout	Registry 통신 실패 가능성	Worker Node의 DNS, Routing, Firewall
connection refused	Registry 서비스 또는 포트 연결 실패	Registry 상태, Port, Load Balancer
x509: certificate signed by unknown authority	Registry 인증서를 신뢰하지 못함	Worker Node 및 Container Runtime의 CA 설정
FailedToRetrieveImagePullSecret	지정한 Image Pull Secret을 찾지 못함	Secret 이름과 Namespace

1. init-kubeconfig-volume이 사용하는 Image 확인

가장 먼저 init-kubeconfig-volume이 어떤 이미지를 사용하도록 설정되어 있는지 확인합니다.

kubectl get pod <POD_NAME> -n <NAMESPACE> \
  -o jsonpath='{.spec.initContainers[*].name}{"\n"}{.spec.initContainers[*].image}{"\n"}'

예를 들어 다음처럼 Private Registry의 이미지가 지정되어 있을 수 있습니다.

harbor.example.com/project/kubeconfig-init:v1.2.3

이 경우 Repository 경로, 이미지 이름, Tag가 실제 Registry에 존재하는지 확인해야 합니다. 특히 배포 YAML이나 Helm values에서 Tag만 변경되었거나 Registry에서 기존 이미지를 삭제한 경우 manifest unknown 또는 not found가 발생할 수 있습니다.

2. Pod Events 확인

CLI 접근이 가능하다면 다음 명령으로 Rancher 화면보다 자세한 Events를 확인할 수 있습니다.

kubectl describe pod <POD_NAME> -n <NAMESPACE>

출력 하단의 Events를 확인합니다.

Events:
  Type     Reason     Message
  ----     ------     -------
  Normal   Pulling    Pulling image "harbor.example.com/project/image:v1.2.3"
  Warning  Failed     Failed to pull image "harbor.example.com/project/image:v1.2.3"
  Warning  Failed     Error: ErrImagePull
  Normal   BackOff    Back-off pulling image
  Warning  Failed     Error: ImagePullBackOff

여기서 중요한 것은 단순히 마지막의 ImagePullBackOff만 보는 것이 아니라 그 직전에 기록된 Failed 메시지의 상세 원인을 확인하는 것입니다.

3. Harbor 또는 Private Registry 인증 문제 확인

이미지가 Harbor 같은 Private Registry에 있다면 imagePullSecrets 설정을 확인해야 합니다. Kubernetes의 imagePullSecret은 Pod와 동일한 Namespace에 존재해야 합니다.

kubectl get pod <POD_NAME> -n <NAMESPACE> \
  -o jsonpath='{.spec.imagePullSecrets}{"\n"}'

kubectl get secret -n <NAMESPACE>

Pod가 특정 ServiceAccount를 사용한다면 ServiceAccount에 imagePullSecret이 연결되어 있는지도 함께 확인합니다.

kubectl get pod <POD_NAME> -n <NAMESPACE> \
  -o jsonpath='{.spec.serviceAccountName}{"\n"}'

kubectl get serviceaccount <SERVICE_ACCOUNT> \
  -n <NAMESPACE> -o yaml

Events에 unauthorized, pull access denied, FailedToRetrieveImagePullSecret 등이 있다면 이 영역을 우선 점검하는 것이 좋습니다.

4. 특정 Worker Node에서만 발생하는지 확인

같은 Deployment의 다른 Pod들은 정상인데 특정 Worker Node에 배치된 Pod만 ImagePullBackOff가 발생한다면 Registry 이미지 자체보다 해당 Worker Node의 환경을 의심할 필요가 있습니다.

kubectl get pod <POD_NAME> -n <NAMESPACE> -o wide

이 경우 다음과 같은 Worker Node별 차이를 확인합니다.

• Worker Node → Registry 네트워크 연결
• DNS 이름 해석
• Firewall 또는 ACL
• Proxy 설정
• Private Registry CA 인증서
• Container Runtime의 Registry 설정

반대로 여러 Worker Node에서 동일한 이미지가 모두 실패한다면 이미지 경로, Registry 장애, 인증 정보 또는 배포 설정 문제일 가능성을 먼저 확인하는 것이 효율적입니다.

5. ImagePullBackOff와 Volume 문제를 구분해야 하는 이유

init-kubeconfig-volume이라는 이름 때문에 처음에는 kubeconfig Volume Mount 문제처럼 보일 수 있습니다. 하지만 컨테이너 이름은 애플리케이션이나 배포 솔루션이 임의로 정의할 수 있으므로 이름 자체가 실패 원인을 의미하지는 않습니다.

현재 상태가 다음과 같다면:

Init:ImagePullBackOff
containers with incomplete status: [init-kubeconfig-volume]

우선적인 장애 지점은 다음과 같이 해석하는 것이 적절합니다.

init-kubeconfig-volume
        │
        ├─ Image Pull 성공
        │     ↓
        │   Init Container 실행
        │     ↓
        │   kubeconfig/volume 초기화 작업
        │
        └─ Image Pull 실패  ← 현재 우선 확인 지점
              ↓
        Init Container 실행 자체가 안 됨
              ↓
        메인 Container도 시작되지 않음

즉 현재 단계에서는 Init Container 내부 스크립트나 kubeconfig 생성 로직까지 실행되지 않았을 가능성이 높습니다. 먼저 이미지 Pull 문제를 해결한 뒤, Init Container가 실행된 이후 별도의 오류가 발생하는지를 확인해야 합니다.

빠르게 원인을 좁히는 점검 순서

1. kubectl describe pod 또는 Rancher Pod Events에서 Failed to pull image의 상세 메시지를 확인합니다.
2. init-kubeconfig-volume의 정확한 Image 주소와 Tag를 확인합니다.
3. Registry에 해당 Repository와 Tag가 실제 존재하는지 확인합니다.
4. Private Registry라면 imagePullSecret과 ServiceAccount를 확인합니다.
5. i/o timeout이나 connection refused라면 Worker Node → Registry 네트워크를 확인합니다.
6. x509 오류라면 Registry 인증서와 Worker Node/Container Runtime의 CA 신뢰 설정을 확인합니다.
7. 특정 Node에서만 발생하는지 다른 Pod와 비교합니다.

정리

Rancher에서 Init:ImagePullBackOff와 containers with incomplete status: [init-kubeconfig-volume]이 함께 표시된다면, init-kubeconfig-volume Init Container가 완료되지 않아 Pod 초기화가 중단된 상태입니다. 특히 ImagePullBackOff는 해당 컨테이너 이미지를 가져오지 못했다는 것이 핵심입니다.

따라서 Pod 삭제나 재시작부터 반복하기보다 Pod Events → Failed to pull image 상세 메시지 → Init Container Image → Registry/Secret/Network/Certificate 순서로 확인하는 것이 원인을 빠르게 좁히는 방법입니다. Kubernetes는 이미지 Pull 실패 시 백오프 간격을 두고 다시 시도하므로 근본 원인이 해결되지 않으면 Pod를 다시 만들어도 동일한 문제가 반복될 수 있습니다.

FAQ

Pod를 삭제하고 다시 생성하면 해결될 수 있나요?

일시적인 Registry 또는 네트워크 장애였다면 정상화될 수 있지만, 이미지 Tag 오류, 인증 실패, imagePullSecret 누락 또는 인증서 문제라면 Pod를 다시 생성해도 같은 오류가 발생할 가능성이 높습니다.

init-kubeconfig-volume 로그부터 확인하면 되나요?

ImagePullBackOff 상태에서는 컨테이너 이미지 자체를 가져오지 못해 Init Container가 실행되지 않았을 수 있습니다. 따라서 로그보다 Events의 이미지 Pull 실패 메시지를 먼저 확인하는 것이 중요합니다.

같은 이미지가 다른 Worker Node에서는 정상이라면 무엇을 확인해야 하나요?

문제가 발생한 Worker Node의 DNS, Registry 연결 경로, Firewall, Proxy, 인증서 신뢰 및 Container Runtime 설정 차이를 우선 비교하는 것이 좋습니다.

imagePullSecret은 다른 Namespace의 Secret을 사용할 수 있나요?

Pod의 imagePullSecrets가 참조하는 Secret은 해당 Pod와 같은 Namespace에 있어야 합니다. Secret 이름뿐 아니라 Namespace도 함께 확인해야 합니다.