Kubernetes Image Pull Back-Off

The 'ImagePullBackOff' status indicates that the Kubernetes Kubelet was unable to pull the specified container image from the configured container registry. This prevents the pod from starting successfully.

Common Causes

Incorrect image name or tag specified in the Pod definition.
The specified image does not exist in the container registry.
Authentication failure when trying to pull from a private container registry (missing or incorrect imagePullSecrets).
Network connectivity issues between the Kubernetes node and the container registry (firewall, DNS, proxy).
Container registry rate limits or temporary unavailability.

How to Fix

1 Verify Image Name and Tag

Double-check the image name and tag in your Pod, Deployment, or StatefulSet YAML definition. Ensure there are no typos and that the image with the specified tag actually exists in your container registry.

BASH

$ kubectl describe pod <pod-name> -n <namespace>

2 Check Container Registry Authentication

If you are pulling from a private registry, ensure that `imagePullSecrets` are correctly configured and linked to the Pod's Service Account or directly in the Pod spec. The secret must contain valid credentials for the registry.

BASH

 $ kubectl create secret docker-registry my-registry-secret \
  --docker-server=your.registry.com \
  --docker-username=your-username \
  --docker-password=your-password \
  --docker-email=your-email@example.com -n <namespace>

# Then add to your Pod spec:
# imagePullSecrets:
# - name: my-registry-secret

3 Validate Network Connectivity to Registry

Confirm that the Kubernetes node where the pod is scheduled has network access to the container registry. This might involve checking firewall rules, proxy settings, or DNS resolution on the node.

BASH

 $ kubectl debug node/<node-name> -it --image=busybox -- sh -c "ping -c 3 your.registry.com || curl -v https://your.registry.com/v2/"

4 Inspect Kubelet Events and Logs

Examine Kubernetes events and Kubelet logs on the affected node for more detailed error messages. These often provide specific reasons for the image pull failure, such as 'unauthorized' or 'manifest unknown'.

BASH

 $ kubectl get events -n <namespace> --field-selector involvedObject.name=<pod-name>
kubectl describe pod <pod-name> -n <namespace>
# If you have SSH access to the node:
# journalctl -u kubelet | grep <image-name>