// Module included in the following assemblies:
//
// * updating/updating_a_cluster/updating_disconnected_cluster/mirroring-image-repository.adoc

:_mod-docs-content-type: PROCEDURE
[id="update-mirroring-images-to-registry_{context}"]
= Mirroring images to a mirror registry

[role="_abstract"]
Before you can update a cluster in a disconnected environment, you must mirror the required {product-title} release images onto a local registry mirror.

[IMPORTANT]
====
To avoid excessive memory usage by the OpenShift Update Service application, you must mirror release images to a separate repository as described in the following procedure.
====

.Prerequisites

* You configured a mirror registry to use in your disconnected environment and can access the certificate and credentials that you configured.
ifndef::openshift-origin[]
* You downloaded the {cluster-manager-url-pull} and modified it to include authentication to your mirror repository.
endif::[]
ifdef::openshift-origin[]
* You have created a pull secret for your mirror repository.
endif::[]
* If you use self-signed certificates, you have specified a Subject Alternative Name in the certificates.

.Procedure

. Use the link:https://access.redhat.com/labs/ocpupgradegraph/update_channel[Red Hat {product-title} Update Graph visualizer and update planner] to plan an update from one version to another. The OpenShift Update Graph provides channel graphs and a way to confirm that there is an update path between your current and intended cluster versions.

. Set the required environment variables:
.. Export the release version:
+
[source,terminal]
----
$ export OCP_RELEASE=<release_version>
----
+
For `<release_version>`, specify the tag that corresponds to the version of {product-title} to which you want to update, such as `4.5.4`.

.. Export the local registry name and host port:
+
[source,terminal]
----
$ LOCAL_REGISTRY='<local_registry_host_name>:<local_registry_host_port>'
----
+
* For `<local_registry_host_name>`, specify the registry domain name for your mirror
repository.
+
* For `<local_registry_host_port>`, specify the port that it
serves content on.

.. Export the local repository name:
+
[source,terminal]
----
$ LOCAL_REPOSITORY='<local_repository_name>'
----
+
For `<local_repository_name>`, specify the name of the repository to create in your
registry, such as `ocp4/openshift4`.

.. If you are using the OpenShift Update Service, export an additional local repository name to contain the release images:
+
[source,terminal]
----
$ LOCAL_RELEASE_IMAGES_REPOSITORY='<local_release_images_repository_name>'
----
+
For `<local_release_images_repository_name>`, specify the name of the repository to
create in your registry, such as `ocp4/openshift4-release-images`.

.. Export the name of the repository to mirror:
+
[source,terminal]
----
$ PRODUCT_REPO='openshift-release-dev'
----
+
For a production release, you must specify `openshift-release-dev`.

.. Export the path to your registry pull secret:
+
[source,terminal]
----
$ LOCAL_SECRET_JSON='<path_to_pull_secret>'
----
+
For `<path_to_pull_secret>`, specify the absolute path to and file name of the pull secret for your mirror registry that you created.
+
[NOTE]
====
If your cluster uses an `ImageContentSourcePolicy` object to configure repository mirroring, you can use only global pull secrets for mirrored registries. You cannot add a pull secret to a project.
====

.. Export the release mirror:
+
[source,terminal]
----
$ RELEASE_NAME="ocp-release"
----
+
For a production release, you must specify `ocp-release`.

.. Export the type of architecture for your cluster:
+
[source,terminal]
----
$ ARCHITECTURE=<cluster_architecture>
----
+
For `<cluster_architecture>`, specify the architecture of the cluster, such as `x86_64`, `aarch64`, `s390x`, or `ppc64le`.

.. Export the path to the directory to host the mirrored images:
+
[source,terminal]
----
$ REMOVABLE_MEDIA_PATH=<path>
----
+
For `<path>`, specify the full path, including the initial forward slash (/) character.

. Review the images and configuration manifests to mirror:
+
[source,terminal]
----
$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} --dry-run
----
. Mirror the version images to the mirror registry.
** If your mirror host does not have internet access, take the following actions:
... Connect the removable media to a system that is connected to the internet.
... Mirror the images and configuration manifests to a directory on the removable media:
+
[source,terminal]
----
$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE}
----
+
[NOTE]
====
This command also generates and saves the mirrored release image signature config map onto the removable media.
====

... Take the media to the disconnected environment and upload the images to the local container registry.
+
[source,terminal]
----
$ oc image mirror  -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:${OCP_RELEASE}*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}
----
+
For `REMOVABLE_MEDIA_PATH`, you must use the same path that you specified when you mirrored the images.

... Use `oc` command-line interface (CLI) to log in to the cluster that you are updating.

... Apply the mirrored release image signature config map to the connected cluster:
+
[source,terminal]
----
$ oc apply -f ${REMOVABLE_MEDIA_PATH}/mirror/config/<image_signature_file>
----
+
For `<image_signature_file>`, specify the path and name of the file, for example, `signature-sha256-81154f5c03294534.yaml`.

... If you are using the OpenShift Update Service, mirror the release image to a separate repository:
+
[source,terminal]
----
$ oc image mirror -a ${LOCAL_SECRET_JSON} ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} ${LOCAL_REGISTRY}/${LOCAL_RELEASE_IMAGES_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}
----

** If the local container registry and the cluster are connected to the mirror host, take the following actions:

... Directly push the release images to the local registry and apply the config map  to the cluster by using following command:
+
[source,terminal]
----
$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
  --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} --apply-release-image-signature
----
+
[NOTE]
====
If you include the `--apply-release-image-signature` option, do not create the config map for image signature verification.
====

... If you are using the OpenShift Update Service, mirror the release image to a separate repository:
+
[source,terminal]
----
$ oc image mirror -a ${LOCAL_SECRET_JSON} ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} ${LOCAL_REGISTRY}/${LOCAL_RELEASE_IMAGES_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}
----