A pod fails to pull a container image from a private registry because the registry credentials are missing, incorrect, or the repository doesn't exist. This occurs with private registries (Azure ACR, AWS ECR, etc.) that require authentication. Fix by creating proper imagePullSecrets with correct credentials.
When pulling from a private registry, kubelet must authenticate using credentials stored in a Kubernetes secret (imagePullSecrets). If credentials are missing, incorrect, or don't have access to the repository, the pull fails with "repository not found" or "no pull access." This is distinct from a public registry image not existing—the issue is authentication, not availability.
Create docker-registry secret:
kubectl create secret docker-registry regcred \
--docker-server=myregistry.azurecr.io \
--docker-username=<username> \
--docker-password=<password> \
-n <pod-namespace>Add imagePullSecrets:
apiVersion: v1
kind: Pod
metadata:
name: my-pod
spec:
imagePullSecrets:
- name: regcred
containers:
- name: app
image: myregistry.azurecr.io/myapp:v1.0List secrets:
kubectl get secrets -n <pod-namespace> | grep regcred
kubectl describe secret regcred -n <pod-namespace>Secret must be in same namespace as pod.
Verify credentials work:
docker login -u <username> -p <password> myregistry.azurecr.io
docker pull myregistry.azurecr.io/myapp:v1.0Get correct credentials:
az acr credential show --name myregistry --query passwords[0].valueUse the output as --docker-password.
Automatically apply credentials to all pods:
kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "regcred"}']}This eliminates need to specify imagePullSecrets per pod.
Kubernetes does NOT use ~/.docker/config.json from local machine; secrets must be explicitly created. Secrets are namespace-scoped. For credential rotation, create new secret and update pods (force rolling restart). For self-signed registries, distribute CA certificates to all nodes. Avoid storing secrets in version control; use a secrets management system. Different cloud registries use different auth: ACR uses username/password, ECR uses temporary tokens, GCR uses service account JSON.
Failed to connect to server: connection refused (HTTP/2)
How to fix "HTTP/2 connection refused" error in Kubernetes
missing request for cpu in container
How to fix "missing request for cpu in container" in Kubernetes HPA
error: invalid configuration
How to fix "error: invalid configuration" in Kubernetes
etcdserver: cluster ID mismatch
How to fix "etcdserver: cluster ID mismatch" in Kubernetes
running with swap on is not supported
How to fix "running with swap on is not supported" in kubeadm