Pull images from a mirrored registry (preview)

You can configure image digest mirrors to redirect container image pull requests from a source registry to one or more mirror registries. When a node pulls an image, it first attempts the mirrors in the order specified, before falling back to the original source registry.

Image digest mirrors are useful if you need to do any of the following:

  • Mirror third-party container images to a private registry for security or compliance reasons.
  • Pull images from a registry that is geographically closer to reduce latency.
  • Operate in restricted network environments where direct access to public registries is not available.

Note

Image digest mirrors only apply to images referenced by digest (registry.example.com/image@sha256:...). Images referenced by tag are not affected.

Considerations for adding, updating, or removing image digest mirrors

Adding, updating, or removing image digest mirrors in a running cluster triggers a rolling replacement of all nodes across all node pools. During this rolling replacement, nodes are drained and recreated one at a time, which temporarily reduces cluster capacity and can cause disruption to running workloads.

Before adding, updating, or removing image digest mirrors in a running cluster, do the following:

  • Plan for a maintenance window so that the rolling replacement can be applied on all node pools at the same time.
  • Batch all image digest mirror changes into a single update to avoid multiple, successive rolling replacements.
  • Run the oc get pdb -A command to verify that all Pod Disruption Budgets (PDBs) allow at least one node to drain at a time.

If any PDBs show 0 allowed disruptions, the PDB is at its limit and the rolling replacement can stall indefinitely.

Add image digest mirrors to a cluster

You can add image digest mirrors when you create a cluster, or update an existing cluster to add them.

Prerequisites

  • Azure CLI version 2.67.0 or higher. Use az --version to find your installed version. If you need to install or upgrade, see Install Azure CLI.

Procedure

  1. Set the following environment variables in your shell if you didn't already set them. Replace the placeholder values with your own.

    CUSTOMER_RG_NAME="<resource-group-name>"
CLUSTER_NAME="<cluster-name>"

  2. Add the image digest mirrors.

    Each entry in the --image-digest-mirrors array maps a source registry to one or more mirror registries. When a node pulls an image from the source, it tries each mirror in order before falling back to the source.

    The following example updates an existing cluster to configure two image digest mirrors:

    az aro hcp cluster update \
  --resource-group "${CUSTOMER_RG_NAME}" \
  --name "${CLUSTER_NAME}" \
  --image-digest-mirrors "[{source:docker.io/library,mirrors:[myprivateregistry.azurecr.io/docker-hub/library]},{source:quay.io/my-org,mirrors:[myprivateregistry.azurecr.io/quay-mirror/my-org,mybackupregistry.azurecr.io/quay-mirror/my-org]}]"

  3. Verify the image digest mirror configuration.

    az aro hcp cluster show \
  --resource-group "${CUSTOMER_RG_NAME}" \
  --name "${CLUSTER_NAME}" \
  --query "properties.imageDigestMirrors"

    The following example output shows the two image digest mirrors applied to the cluster:

    [
  {
    "mirrors": [
      "myprivateregistry.azurecr.io/docker-hub/library"
    ],
    "source": "docker.io/library"
  },
  {
    "mirrors": [
      "myprivateregistry.azurecr.io/quay-mirror/my-org",
      "mybackupregistry.azurecr.io/quay-mirror/my-org"
    ],
    "source": "quay.io/my-org"
  }
]

Update image digest mirrors

You can modify image digest mirrors on an existing cluster by running az aro hcp cluster update with the --image-digest-mirrors argument.

Before updating image digest mirrors, review the Considerations for adding, updating, or removing image digest mirrors.

Important

When you update image digest mirrors, include the complete list of image digest mirror entries. The --image-digest-mirrors argument replaces the entire array, so the cluster removes any entries that you omit from the updated list.

The following example updates the cluster to use a single image digest mirror:

az aro hcp cluster update \
  --resource-group "${CUSTOMER_RG_NAME}" \
  --name "${CLUSTER_NAME}" \
  --image-digest-mirrors "[{source:docker.io/library,mirrors:[myprivateregistry.azurecr.io/docker-hub/library]}]"

Remove all image digest mirrors

To remove all image digest mirrors from a cluster, run az aro hcp cluster update and set the --image-digest-mirrors argument to an empty array ([]).

Before removing image digest mirrors, review the Considerations for adding, updating, or removing image digest mirrors.

az aro hcp cluster update \
  --resource-group "${CUSTOMER_RG_NAME}" \
  --name "${CLUSTER_NAME}" \
  --image-digest-mirrors "[]"
  • Last updated on