Understand image registry repository mirroring

You must mirror images to update clusters in disconnected environments.

By setting up container registry repository mirroring, you can perform the following tasks:

  • Configure your OpenShift Container Platform cluster to redirect requests to pull images from a repository on a source image registry and have it resolved by a repository on a mirrored image registry.

  • Identify multiple mirrored repositories for each target repository, to make sure that if one mirror is down, another can be used.

Repository mirroring in OpenShift Container Platform includes the following attributes:

  • Image pulls are resilient to registry downtimes.

  • Clusters in disconnected environments can pull images from critical locations, such as quay.io, and have registries behind a company firewall provide the requested images.

  • A particular order of registries is tried when an image pull request is made, with the permanent registry typically being the last one tried.

  • The mirror information you enter is added to the /etc/containers/registries.conf file on every node in the OpenShift Container Platform cluster.

  • When a node makes a request for an image from the source repository, it tries each mirrored repository in turn until it finds the requested content. If all mirrors fail, the cluster tries the source repository. If successful, the image is pulled to the node.

You can set up repository mirroring in the following ways:

  • At OpenShift Container Platform installation:

    By pulling container images needed by OpenShift Container Platform and then bringing those images behind your company’s firewall, you can install OpenShift Container Platform into a data center that is in a disconnected environment.

  • After OpenShift Container Platform installation:

    If you did not configure mirroring during OpenShift Container Platform installation, you can do so postinstallation by using any of the following custom resource (CR) objects:

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

    • ImageContentSourcePolicy (ICSP). This object allows you to pull images from a mirrored registry by using digest specifications. The ICSP CR always falls back to the source registry if the mirrors do not work.

      Important

      Using an ImageContentSourcePolicy (ICSP) object to configure repository mirroring is a deprecated feature. Deprecated functionality is still included in OpenShift Container Platform and continues to be supported. It will be removed in a future release and is not recommended for new deployments.

      If you have existing YAML files that you used to create ImageContentSourcePolicy objects, you can use the oc adm migrate icsp command to convert those files to a ImageDigestMirrorSet YAML files. For more information, see "Converting ImageContentSourcePolicy (ICSP) files for image registry repository mirroring".

Each of these custom resource objects identify the following information:

  • The source of the container image repository you want to mirror.

  • A separate entry for each mirror repository you want to offer the content

Note the following actions and how they affect node drain behavior:

  • If you create an IDMS or ICSP CR object, the MCO does not drain or reboot the node.

  • If you create an ITMS CR object, the MCO drains and reboots the node.

  • If you delete an ITMS, IDMS, or ICSP CR object, the MCO drains and reboots the node.

  • If you modify an ITMS, IDMS, or ICSP CR object, the MCO drains and reboots the node.

    Important

    • When the MCO detects any of the following changes, it applies the update without draining or rebooting the node:

      • Changes to the SSH key in the spec.config.passwd.users.sshAuthorizedKeys parameter of a machine config.

      • Changes to the global pull secret or pull secret in the openshift-config namespace.

      • Automatic rotation of the /etc/kubernetes/kubelet-ca.crt certificate authority (CA) by the Kubernetes API Server Operator.

    • When the MCO detects changes to the /etc/containers/registries.conf file, such as editing an ImageDigestMirrorSet, ImageTagMirrorSet, or ImageContentSourcePolicy object, it drains the corresponding nodes, applies the changes, and uncordons the nodes. The node drain does not happen for the following changes:

      • The addition of a registry with the pull-from-mirror = "digest-only" parameter set for each mirror.

      • The addition of a mirror with the pull-from-mirror = "digest-only" parameter set in a registry.

      • The addition of items to the unqualified-search-registries list.

For new clusters, you can use IDMS, ITMS, and ICSP CRs objects as needed. However, using IDMS and ITMS is recommended.

If you upgraded a cluster, any existing ICSP objects remain stable, and both IDMS and ICSP objects are supported. Workloads that use ICSP objects continue to function as expected. However, if you want to take advantage of the fallback policies introduced in the IDMS CRs, you can migrate current workloads to IDMS objects by using the oc adm migrate icsp command as shown in the Converting ImageContentSourcePolicy (ICSP) files for image registry repository mirroring section that follows. Migrating to IDMS objects does not require a cluster reboot.

Note

By default, if your cluster uses an ImageDigestMirrorSet, ImageTagMirrorSet, or ImageContentSourcePolicy object to configure repository mirroring, you must use a global pull secret for mirrored registries. You cannot add an image pull secret to a project.

However, you can configure a cluster-wide CRIOCredentialProviderConfig object to enable project-scoped image pull secrets that you can use with mirrored repositories. For more information, see "Configuring project-scoped image pull secrets for mirrored registries".

← Previous: Use Cluster Samples Operator image streams with alternate or mirrored registries | ↑ Up: Administer | ⌂ Home: OpenShift Container Platform | Next: Configure image registry settings →