Kubernetes cannot pull images from the old k8s.gcr.io registry
Failed to pull image "k8s.gcr.io/..."Short answer
The project registry k8s.gcr.io was frozen on 3 April 2023 and replaced by registry.k8s.io. Anything that still names the old host, such as manifests, Helm values or a kubeadm config, can fail to pull, and new images are not published there. Find every k8s.gcr.io reference and change the host to registry.k8s.io.
Fix it fast
1Find out which cause you have
List every image in the cluster that still uses the old host.
kubectl get pods -A -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.metadata.name}{"\t"}{range .spec.containers[*]}{.image}{" "}{end}{"\n"}{end}' | grep k8s.gcr.io2Match what you see, then jump to its fix
What does the error look like?
Failed to pull image "k8s.gcr.io/..."ErrImagePull / ImagePullBackOff on a k8s.gcr.io image
Cause 1 of 2
Manifests or Helm values still point at k8s.gcr.io
1Check
The Kubernetes announcement says the old registry was frozen on 3 April 2023 and that registry.k8s.io replaced it. Search your own manifests and chart values for the old host.
grep -rn "k8s.gcr.io" manifests/ charts/2Fix
Replace the host and keep the path and tag. If the image is from a third-party chart, upgrade the chart to a release that uses the new host.
# before
image: k8s.gcr.io/pause:3.9
# after
image: registry.k8s.io/pause:3.93Verify
Apply the change and watch the pod reach Running.
kubectl rollout status deployment/my-appConfirmed by kubernetes.io
Cause 2 of 2
kubeadm is set to pull control-plane images from the old registry
1Check
kubeadm can list the images it needs. If your ClusterConfiguration sets imageRepository to the old host, it overrides the default.
kubeadm config images list
grep -n imageRepository kubeadm-config.yaml2Fix
Remove imageRepository, or set it to registry.k8s.io; the documented default when the field is empty is registry.k8s.io. Then pull again.
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
imageRepository: registry.k8s.io3Verify
Pull the control-plane images with the corrected config.
kubeadm config images pull --config kubeadm-config.yamlConfirmed by kubernetes.io
How do I stop it coming back?
- Search manifests, Helm values and CI files for the old host whenever a project announces a registry move.
- Pin images by tag or digest in registry.k8s.io, never by a mirror you do not control.
- Run kubeadm config images list before an upgrade to see where images come from.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Kubernetes pod stuck in ErrImagePull or ImagePullBackOff
ImagePullBackOff
The kubelet could not pull the container image.
3 causes, each with a fixServers
Argo CD behind an nginx Ingress loops with too many redirects
307 Temporary Redirect on every request to the Argo CD host
The browser and Argo CD disagree about who handles TLS.
3 causes, each with a fixServers
A cert-manager Certificate stays at READY False with Let's Encrypt
Issuing certificate as Secret does not exist
A Certificate that stays not ready is waiting on a chain: Issuer, CertificateRequest, Order, Challenge.
3 causes, each with a fixServers
Kubernetes in Docker Desktop will not start or stays on starting
kubectl shows no contexts, or errors against the docker-desktop context
When the Docker Desktop cluster hangs on starting, the usual causes are too few resources, a broken cluster state, or the kubeadm provisioner failing.
4 causes, each with a fixServers
EKS managed node group ends in Create failed because nodes never joined
NodeCreationFailure
Nodes that do not register within 15 minutes cause NodeCreationFailure and a Create failed status.
4 causes, each with a fixServers
An Elasticsearch pod keeps restarting with Back-off restarting failed container
CrashLoopBackOff
Back-off restarting failed container only says the container keeps dying.
3 causes, each with a fix