Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Kubernetes cannot pull images from the old k8s.gcr.io registry

ErrorFailed 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.

  • Applies to Kubernetes 1.31+, kubeadm 1.31+, containerd 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.io
  2. 2Match what you see, then jump to its fix

    1. 1The failing pod's image starts with k8s.gcr.io/Manifests or Helm values still point at k8s.gcr.ioFix
    2. 2kubeadm init or kubeadm config images pull fails on k8s.gcr.iokubeadm is set to pull control-plane images from the old registryFix

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.9

3Verify

Apply the change and watch the pod reach Running.

kubectl rollout status deployment/my-app

Confirmed by kubernetes.io

Did this fix it?

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.yaml

2Fix

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.io

3Verify

Pull the control-plane images with the corrected config.

kubeadm config images pull --config kubeadm-config.yaml

Confirmed by kubernetes.io

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.