Configuring clients to use a container registry mirror

Stian Frøystein
Jun 04, 2025

Table of Contents

This is part two in a series of blog posts about container registry mirrors. The previous post focused on setting up a mirror in Kubernetes, now we will look at how to configure various clients to use it.

Note

If you do not have your own mirror you can use https://mirror.gcr.io, which is what will be used in this guide for simplicity.

Docker #

If you are using Docker on Linux you can simply edit /etc/docker/daemon.json and add the registry-mirrors field:

1
2
3
{
  "registry-mirrors": ["https://mirror.gcr.io"]
}

Docker Desktop #

If you are using Docker Desktop you can configure the same via the Docker Engine page in the settings:

docker desktop settings

CRI-O #

CRI-O is a lightweight alternative to Docker primarily for use with Kubernetes but is also the default runtime when using Podman.

Mirrors can be configured by editing /etc/containers/registries.conf or in a dedicated file under /etc/containers/registries.conf.d:

1
2
3
4
5
6
7
# /etc/containers/registries.conf.d/001-mirrors.conf
[[registry]]
  location = "docker.io"

  [[registry.mirror]]
    location = "mirror.gcr.io:443"
    pull-from-mirror = "all"

OpenShift #

OpenShift has built-in CRDs that can be used to configure nodes in a cluster to use mirrors.

From the OpenShift documentation:

ImageDigestMirrorSet (IDMS). This object allows you to pull images from a mirrored registry by using digest specifications. The IDMS CR enables you to set a fall back policy that allows or stops continued attempts to pull from the source registry if the image pull fails.
ImageTagMirrorSet (ITMS). This object allows you to pull images from a mirrored registry by using image tags. The ITMS CR enables you to set a fall back policy that allows or stops continued attempts to pull from the source registry if the image pull fails.

In other words an IDMS will only use the mirror when using digests to pull an image (docker.io/alpine@sha256:af11...) and an ITMS will only use the mirror when using tags to pull an image (docker.io/alpine:3.22.0)

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
apiVersion: config.openshift.io/v1
kind: ImageDigestMirrorSet
metadata:
  name: example
spec:
  imageDigestMirrors:
    - mirrors:
        - mirror.gcr.io
      source: docker.io
      mirrorSourcePolicy: AllowContactingSource

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
apiVersion: config.openshift.io/v1
kind: ImageTagMirrorSet
metadata:
  name: example
spec:
  imageTagMirrors:
    - mirrors:
        - mirror.gcr.io
      source: docker.io
      mirrorSourcePolicy: AllowContactingSource

The possible values for mirrorSourcePolicy (fallback policy if the image pull fails) are:

AllowContactingSource: Allows continued attempts to pull the image from the source repository. This is the default.
NeverContactSource: Prevents continued attempts to pull the image from the source repository.

That’s it for now, in the next part I will describe how to use MachineConfigs in OpenShift to configure mirrors when using Hosted Control Planes.

Tags: