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.
Fixes rpc error: code = 2 desc = repository does not exist or no pull access
kubectl create secret docker-registry regcred \
--docker-server=myregistry.azurecr.io \
--docker-username=<username> \
--docker-password=<password> \
-n <pod-namespace>kubectl create secret docker-registry regcred \--docker-server=myregistry.azurecr.io \--docker-username=<username> \--docker-password=<password> \-n <pod-namespace>rpc error: code = 2 desc = repository does not exist or no pull access
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.