K8s ImagePullBackOff

A pod status indicating Kubernetes cannot pull the specified container image from a registry. The pod will remain in a pending or waiting state, preventing the workload from starting.

Common Causes

Invalid image name, tag, or repository path in the pod/deployment manifest.
Missing image pull secrets for a private container registry (e.g., Docker Hub, ECR, GCR).
Network issues preventing the node from reaching the container registry.
The specified image tag does not exist in the registry.
Authentication or authorization failure with the registry (e.g., expired token, insufficient permissions).

How to Fix

1 Check Pod Events and Status

Use kubectl describe to get detailed error messages from the pod's events, which often specify the exact cause (e.g., 'not found', 'unauthorized').

BASH

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

2 Verify Image Name and Tag

Manually check that the image reference in your manifest is correct and exists in the target registry. Test pulling it locally with docker pull.

BASH

$ docker pull <your-image:tag>

3 Configure Image Pull Secrets

If using a private registry, ensure the pod's service account has the necessary imagePullSecrets. Create the secret and reference it in the pod spec or service account.

BASH

 $ kubectl create secret docker-registry my-registry-secret \
  --docker-server=<registry-url> \
  --docker-username=<user> \
  --docker-password=<pass> \
  --docker-email=<email>
# Then add `imagePullSecrets:
# - name: my-registry-secret` to your pod spec.

4 Check Node Network and Registry Access

SSH into the node where the pod is scheduled and attempt to pull the image directly using the node's container runtime (e.g., crictl) to diagnose network or DNS issues.

BASH

 $ ssh <node-ip>
sudo crictl pull <your-image:tag>