Why Kubernetes Switched to registry.k8s.io and How to Adapt

Authors: Adolfo García Veytia (Chainguard), Bob Killen (Google)

TL;DR

From Kubernetes 1.25 onward, images are published only to registry.k8s.io, not to k8s.gcr.io.

The new registry domain default will be back‑ported to all supported branches (1.22, 1.23, 1.24) in the upcoming December patch releases.

Clusters that enforce a strict allow‑list for k8s.gcr.io will see image pulls fail; the recommended workaround is to mirror images to a private registry.

Why the registry changed

The original k8s.gcr.io domain is hosted on a custom Google Container Registry (GCR) that has served the project since its inception. As other cloud providers and vendors expressed interest in hosting the images, a multi‑provider approach was adopted. Google contributed $3 million in infrastructure funding, and Amazon announced a matching donation at KubeCon NA 2022. The new registry.k8s.io distributes traffic across Google, Amazon, and future partners, providing faster downloads (closer servers) and reducing reliance on a single provider’s egress bandwidth and cost.

Why there is no stable domain/IP list

registry.k8s.io

functions as a secure blob redirector that sends client requests to the nearest cloud provider. Because the backend set can change dynamically as new providers join, a static list of IPs or domains would quickly become outdated. Restrictive controls such as hard‑coded IP allow‑lists or man‑in‑the‑middle proxies will break. Users needing strict control are encouraged to mirror the required images to a privately managed registry.

Typical error messages

When a cluster cannot reach the new registry, you may see pod‑creation failures similar to the following:

FailedCreatePodSandBox: Failed to create pod sandbox: rpc error: code = Unknown desc = Error response from daemon: Head "https://us-west1-docker.pkg.dev/v2/k8s-artifacts-prod/images/pause/manifests/3.8": x509: certificate signed by unknown authority

How to revert to the old registry

In kubeadm

You can override the image repository used by kubeadm in two ways:

Pass the --image-repository flag: kubeadm init --image-repository=k8s.gcr.io Or set imageRepository in the ClusterConfiguration section of the kubeadm config file:

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
imageRepository: "k8s.gcr.io"

In kubelet

Override the pause image used by the kubelet with the --pod-infra-container-image flag:

kubelet --pod-infra-container-image=k8s.gcr.io/pause:3.5

Acknowledgements

The change was made possible by contributions from many community members across SIG Infra, SIG Node, SIG Cluster Lifecycle, SIG Release, and SIG Contribex, as well as support from cloud‑provider partners Amazon and Google.

References

Secure blob redirector : https://github.com/kubernetes/registry.k8s.io/blob/main/cmd/archeio/docs/request-handling.md

registry.k8s.io stability documentation : https://github.com/kubernetes/registry.k8s.io#stability

kubeadm configuration API : https://kubernetes.io/docs/reference/config-api/kubeadm-config.v1beta3/