openshift-docs/disconnected/installing-mirroring-installation-images.adoc

:_mod-docs-content-type: ASSEMBLY
[id="installing-mirroring-installation-images"]
= Mirroring images for a disconnected installation by using the oc adm command
include::_attributes/common-attributes.adoc[]
:context: installing-mirroring-installation-images

toc::[]

You can ensure your clusters only use container images that satisfy your organizational controls on external content. Before you install a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. By using the `oc adm` command, you can mirror release and catalog images in OpenShift. To mirror container images, you must have a registry for mirroring.

[NOTE]
====
The `oc adm release mirror` command is planned for deprecation in a future release. Additionally, when using this command, release image signatures are not automatically mirrored to the disconnected registry. Missing release signatures prevent cluster upgrades, as `ClusterImagePolicy` requires all release images to be verified. To ensure image signatures are correctly mirrored, it is recommended to use the oc-mirror v2 plugin.
====

// TODO: Is this procedure going to be marked deprecated for 4.10 so that it could be removed in the future?
// TODO: Add a link to the TP procedure?
// TODO: Consider updating the title of this one to indicate the difference? Or wait to make any changes like that til GA, til we know if it'll stick around or be completely replaced by the oc-mirror one?

[IMPORTANT]
====
You must have access to the internet to obtain the necessary container images.
In this procedure, you place your mirror registry on a mirror host
that has access to both your network and the internet. If you do not have access
to a mirror host, use the xref:../disconnected/installing-mirroring-installation-images.adoc#olm-mirror-catalog_installing-mirroring-installation-images[Mirroring Operator catalogs for use with disconnected clusters] procedure to copy images to a device you can move across network boundaries with.
====

[id="prerequisites_installing-mirroring-installation-images"]
== Prerequisites

* You must have a container image registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker v2-2] in the location that will host the {product-title} cluster, such as one of the following registries:
+
--
** link:https://www.redhat.com/en/technologies/cloud-computing/quay[{quay}]
** link:https://jfrog.com/artifactory/[JFrog Artifactory]
** link:https://www.sonatype.com/products/repository-oss?topnav=true[Sonatype Nexus Repository]
** link:https://goharbor.io/[Harbor]
--
+
If you have an entitlement to {quay}, see the documentation on deploying {quay} link:https://docs.redhat.com/en/documentation/red_hat_quay/3.9/html/deploy_red_hat_quay_for_proof-of-concept_non-production_purposes/index[for proof-of-concept purposes] or link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index[by using the {quay} Operator]. If you need additional assistance selecting and installing a registry, contact your sales representative or Red Hat Support.

* If you do not already have an existing solution for a container image registry, subscribers of {product-title} are provided a xref:../disconnected/installing-mirroring-creating-registry.adoc#installing-mirroring-creating-registry[mirror registry for Red Hat OpenShift]. The _mirror registry for Red{nbsp}Hat OpenShift_ is included with your subscription and is a small-scale container registry that can be used to mirror the required container images of {product-title} in disconnected installations.

include::modules/installation-about-mirror-registry.adoc[leveloffset=+1]

.Additional information

For information about viewing the CRI-O logs to view the image source, see xref:../installing/validation_and_troubleshooting/validating-an-installation.adoc#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source].

[id="installing-preparing-mirror"]
== Preparing your mirror host

Before you perform the mirror procedure, you must prepare the host to retrieve content
and push it to the remote location.

// Installing the OpenShift CLI on Linux
include::modules/cli-installing-cli-linux.adoc[leveloffset=+2]

// Installing the OpenShift CLI on Windows
include::modules/cli-installing-cli-windows.adoc[leveloffset=+2]

// Installing the OpenShift CLI on macOS
include::modules/cli-installing-cli-macos.adoc[leveloffset=+2]

include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1]

//This command seems out of place. Where should it really go?
////
[id="installing-performing-connected-mirror"]
== Performing a mirror while connected to the internet

$ oc adm release mirror OPENSHIFT_VERSION --to MIRROR_REPOSITORY
////

////
[id="installing-restricted-networks-preparations-mirroring"]
== Mirroring the content

In production environments, add the required images to a registry in your restricted network. For non-production environments, you can use the images without a separate registry.

 modules/installation-performing-disconnected-mirror.adoc[leveloffset=+2]

 modules/installation-performing-disconnected-mirror-without-registry.adoc[leveloffset=+2]
////

include::modules/installation-mirror-repository.adoc[leveloffset=+1]

[id="installing-preparing-samples-operator"]
== The Cluster Samples Operator in a disconnected environment

In a disconnected environment, you must take additional steps after you install a cluster to configure the Cluster Samples Operator. Review the following information in preparation.

include::modules/installation-images-samples-disconnected-mirroring-assist.adoc[leveloffset=+2]

include::modules/olm-mirroring-catalog.adoc[leveloffset=+1]

[role="_additional-resources"]
.Additional resources

* xref:../disconnected/using-olm.adoc#olm-restricted-networks[Using Operator Lifecycle Manager in disconnected environments]

[id="olm-mirror-catalog-prerequisites_installing-mirroring-installation-images"]
=== Prerequisites

Mirroring Operator catalogs for use with disconnected clusters has the following prerequisites:

* Workstation with unrestricted network access.
* `podman` version 1.9.3 or later.
* If you want to filter, or _prune_, an existing catalog and selectively mirror only a subset of Operators, see the following sections:
** xref:../cli_reference/opm/cli-opm-install.adoc#cli-opm-install[Installing the opm CLI]
** xref:../operators/admin/olm-managing-custom-catalogs.adoc#olm-filtering-fbc_olm-managing-custom-catalogs[Updating or filtering a file-based catalog image]
ifndef::openshift-origin[]
* If you want to mirror a Red Hat-provided catalog, run the following command on your workstation with unrestricted network access to authenticate with `registry.redhat.io`:
+
[source,terminal]
----
$ podman login registry.redhat.io
----
endif::[]
* Access to a mirror registry that supports
link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2].
* On your mirror registry, decide which repository, or namespace, to use for storing mirrored Operator content. For example, you might create an `olm-mirror` repository.
* If your mirror registry does not have internet access, connect removable media to your workstation with unrestricted network access.
* If you are working with private registries, including `registry.redhat.io`, set the `REG_CREDS` environment variable to the file path of your registry credentials for use in later steps. For example, for the `podman` CLI:
+
[source,terminal]
----
$ REG_CREDS=${XDG_RUNTIME_DIR}/containers/auth.json
----

include::modules/olm-mirroring-catalog-extracting.adoc[leveloffset=+2]

include::modules/olm-mirroring-catalog-colocated.adoc[leveloffset=+3]

include::modules/olm-mirroring-catalog-airgapped.adoc[leveloffset=+3]

include::modules/olm-mirroring-catalog-manifests.adoc[leveloffset=+2]

include::modules/olm-mirroring-catalog-post.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources

* xref:../post_installation_configuration/preparing-for-users.adoc#post-install-mirrored-catalogs[Populating the software catalog from mirrored Operator catalogs]
* xref:../operators/admin/olm-managing-custom-catalogs.adoc#olm-filtering-fbc_olm-managing-custom-catalogs[Updating or filtering a file-based catalog image]

[id="next-steps_installing-mirroring-installation-images"]
== Next steps

//* TODO need to add the registry secret to the machines, which is different

* Install a cluster on infrastructure that you provision in your restricted network, such as on
xref:../installing/installing_vsphere/upi/installing-restricted-networks-vsphere.adoc#installing-restricted-networks-vsphere[VMware vSphere],
xref:../installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc#installing-restricted-networks-bare-metal[bare metal], or xref:../installing/installing_aws/upi/installing-restricted-networks-aws.adoc#installing-restricted-networks-aws[Amazon Web Services].

[role="_additional-resources"]
[id="restricted-networks-additional-resources"]
== Additional resources

* See xref:../support/gathering-cluster-data.adoc#gathering-data-specific-features_gathering-cluster-data[Gathering data about specific features] for more information about using must-gather.