DaoCloud public-image-mirror: Accelerating Container Image Pulls from Blocked Registries

The Problem: Blocked Container Registries

Developers and operations teams in some network environments cannot pull images directly from docker.io, gcr.io, ghcr.io, registry.k8s.io, quay.io, or other major registries. The result is failed kubeadm deployments, broken CI pipelines, and Kubernetes pods that cannot start because their images are unavailable.

public-image-mirror addresses this with a public registry proxy. The repository is not a piece of software to install locally. It is the public information hub for a service operated by DaoCloud, providing documentation, the allowed image list, and links to the backend infrastructure.

Two Ways to Use the Mirror: Prefix and Hostname Replacement

The README describes two methods. The recommended method is prefix addition: prepend m.daocloud.io/ to the full original image path.

For example:

docker.io/library/busybox
   |
   V
m.daocloud.io/docker.io/library/busybox

The alternative, listed as not recommended, is hostname replacement. This replaces the source registry hostname with a DaoCloud subdomain. For docker.io, the replacement is docker.m.daocloud.io:

docker.io/library/busybox
  |
  V
docker.m.daocloud.io/library/busybox

The README warns explicitly not to configure docker.io replacements for non-docker.io registries. Each source registry has distinct content; mixing them up breaks image resolution. The hostname replacement approach also requires manually configured registry-mirrors or registries.conf entries, while the prefix approach works with any docker run or kubectl command without daemon configuration.

Supported Registries and Their Mirror Subdomains

The README documents the following hostname substitutions for the prefix-replacement approach:

- docker.io maps to docker.m.daocloud.io - gcr.io maps to gcr.m.daocloud.io - ghcr.io maps to ghcr.m.daocloud.io - registry.k8s.io maps to k8s.m.daocloud.io - k8s.gcr.io maps to k8s-gcr.m.daocloud.io (k8s.gcr.io has been migrated to registry.k8s.io) - quay.io maps to quay.m.daocloud.io - mcr.microsoft.com maps to mcr.m.daocloud.io - nvcr.io maps to nvcr.m.daocloud.io - registry.ollama.ai maps to ollama.m.daocloud.io (listed as experimental)

For running a quick Nginx container from the mirror using the prefix method:

docker run -d -P m.daocloud.io/docker.io/library/nginx

The last push to the repository was on 2026-09-23, indicating the allowed image list and documentation are being actively updated.

Kubernetes and Containerd Integration

For kubeadm-based Kubernetes clusters, the README provides a ClusterConfiguration snippet that redirects the image repository:

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
dns:
  imageRepository: k8s.m.daocloud.io/coredns
imageRepository: k8s.m.daocloud.io

For kind clusters, the mirror can be specified per-image in the node image flag:

kind create cluster --name kind --image m.daocloud.io/docker.io/kindest/node:v1.22.1

For Containerd, the mirror is configured through the hosts.toml mechanism documented in the Containerd project's hosts.md. For Podman, which unlike Docker supports mirrors for registries other than docker.io, the configuration goes in /etc/containers/registries.conf:

[[registry]]
location = "gcr.io"

[[registry.mirror]]
location = "gcr.m.daocloud.io"

For Docker specifically, only the docker.io mirror can be set in registry-mirrors inside /etc/docker/daemon.json:

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

The README notes that configuring a non-docker.io registry mirror as a Docker daemon mirror is incorrect and will not work as expected.

Cache Behavior and Limitations

The README documents specific caching constraints that affect how reliable the mirror is for production use. All hashes (sha256 digests) match the upstream source, which is enforced through a lazy-loading mechanism. Cached images are kept for 30 days; after that period, they are deleted and must be re-synchronized from upstream on the next pull request.

Manifest entries are cached in memory for 1 hour. If an image tag is updated upstream, the new manifest will only be visible after that 1-hour window expires. Blob entries are cached in memory for 1 minute. If a blob reaches its 30-day expiry during that 1-minute window, a pull may return a 404 error.

The recommended usage pattern the README gives is to specify images by sha256 digest rather than by tag where possible, with versioned tags as the next preference and the latest mutable tag as the last resort. This reduces the risk of pulling a different image than expected after a tag update.

Peak usage times are documented as Chinese business hours on weekdays: 09:00 to 11:00 and 14:00 to 17:00 Beijing time. The README advises scheduling pulls during off-peak hours (01:00 to 07:00 Beijing time) to avoid congestion.

Deploying a Local Cache for Internal Networks

For teams that want to reduce external pull requests and make the mirror work in fully air-gapped environments, the README points to a local cache deployment option documented in docs/local-cache. This allows setting up an internal registry that acts as a secondary cache, pulling from the DaoCloud mirror rather than from the blocked upstream.

For automatically rewriting all Pod image references in a Kubernetes cluster without touching individual YAML or Helm files, the README references a separate project called repimage. It works through a mutating webhook:

kubectl create -f https://files.m.daocloud.io/github.com/wzshiming/repimage/releases/download/latest/repimage.yaml
kubectl rollout status deployment/repimage -n kube-system

This approach is an alternative to configuring every tool individually and is documented as a Kubernetes best practice in the README, though it is a third-party project rather than part of public-image-mirror itself.

What This Repository Is Not

public-image-mirror is not software to install or operate. The README states that the backend code lives in a separate repository: github.com/OpenCIDN/ocimirror. This repository holds the documentation, the whitelist, and the allowed image index.

Because this is a hosted public service with a whitelist and rate limiting, teams cannot add arbitrary new images without going through an issue request process (referenced in issue #2328 in the README). Images not already in the allowed list may not be available.

A self-hosted Docker registry mirror (such as a Harbor instance) or a pull-through cache configured against the upstream registries directly is the alternative for teams that need full control over what is cached, guaranteed cache retention beyond 30 days, or images not in the DaoCloud whitelist. The DaoCloud mirror trades control for zero operational overhead.

Editorial conclusion

public-image-mirror is useful in one specific situation: pulling container images from registries that are slow or unreachable from a network, without modifying Kubernetes YAML, Helm charts, or Dockerfiles. The prefix method (prepend m.daocloud.io/ to the full image path) works across all supported registries and requires no global daemon configuration. The 30-day cache expiry and the 1-hour manifest cache mean that images are not permanently mirrored; a pull after expiry re-synchronizes from the upstream. Teams running production infrastructure should treat this as a network convenience, not as a guaranteed artifact store, and should verify cache state before building images that depend on pinning by digest.

Frequently asked questions

Official sources

1. Official README
2. Project repository