How to Fix K8s ImagePullBackOff: Registry Authentication
Quick Fix Summary
TL;DRCreate and apply a Kubernetes Secret with your registry credentials to the affected namespace.
ImagePullBackOff occurs when a Kubernetes node cannot pull a container image from a registry. Authentication failures are a primary cause, blocking pod startup and halting production services.
Diagnosis & Causes
Recovery Steps
Step 1: Diagnose the Authentication Failure
First, confirm the error is authentication-related by checking the pod events and describe output.
kubectl describe pod <pod-name> -n <namespace>
kubectl get events -n <namespace> --field-selector involvedObject.name=<pod-name>Step 2: Create a Docker Registry Secret
Create a Kubernetes Secret of type `docker-registry` using your credentials. Replace placeholders with your actual registry URL, username, and password/token.
kubectl create secret docker-registry regcred \
--docker-server=<your-registry-server> \
--docker-username=<your-name> \
--docker-password=<your-pword> \
--docker-email=<your-email> \
-n <target-namespace>Step 3: Patch the Pod's ServiceAccount
For a cluster-wide or namespace-wide fix, attach the secret to the default ServiceAccount. This automatically injects it into all new pods.
kubectl patch serviceaccount default -n <namespace> -p '{"imagePullSecrets": [{"name": "regcred"}]}'Step 4: Apply the Secret to a Specific Pod (Alternative)
If you prefer not to modify the ServiceAccount, explicitly add the `imagePullSecrets` field to your Pod or Deployment YAML.
spec:
containers:
- name: myapp
image: my-registry.io/my-app:latest
imagePullSecrets:
- name: regcredStep 5: Validate and Restart
Verify the secret is correctly configured and restart the deployment to trigger a new image pull.
kubectl get secret regcred -n <namespace> -o yaml
kubectl rollout restart deployment/<deployment-name> -n <namespace>Step 6: Verify Fix and Monitor
Confirm the pod starts successfully and the ImagePullBackOff error is resolved.
kubectl get pods -n <namespace> -w
kubectl logs <new-pod-name> -n <namespace>Architect's Pro Tip
"For AWS ECR, use `kubectl create secret docker-registry` with an IAM role's temporary credentials, or better, configure the ECR Credential Helper on your nodes for automatic, secure token renewal."
Frequently Asked Questions
Can I use the same secret across multiple namespaces?
No, Secrets are namespace-scoped. You must create the secret in each namespace where it's needed, or use a tool like kubed for syncing.
My secret exists, but pods still fail. What's next?
Check: 1) Secret name matches the Pod spec, 2) Credentials are valid via `docker login`, 3) Network policies allow egress to the registry, 4) The node has disk space.