openshift · stevsmit · Jan 26, 2022 · Dec 6, 2021
diff --git a/installing/installing-mirroring-installation-images.adoc b/installing/installing-mirroring-installation-images.adoc
@@ -5,36 +5,37 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-Before you install a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. You can also use this procedure in unrestricted networks to ensure your clusters only use container images that have satisfied your organizational controls on external content.
+You can use the procedures in this section to 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. To mirror container images, you must have a registry for mirroring.
 
 [IMPORTANT]
 ====
 You must have access to the internet to obtain the necessary container images.
-In this procedure, you place the mirror registry on a mirror host
+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 disconnected procedure to copy images to a device you
-can move across network boundaries with.
+to a mirror host, use the xref:../installing/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:
+* 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[Red Hat 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 Red Hat Quay, see the documentation on deploying Red Hat Quay link:https://access.redhat.com/documentation/en-us/red_hat_quay/3.5/html/deploy_red_hat_quay_for_proof-of-concept_non-production_purposes/[for proof-of-concept purposes] or link:https://access.redhat.com/documentation/en-us/red_hat_quay/3.5/html/deploy_red_hat_quay_on_openshift_with_the_quay_operator/[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:../installing/installing-mirroring-installation-images.adoc#mirror-registry[mirror registry for Red Hat OpenShift]. The _mirror registry for Red 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 on viewing the CRI-O logs to view the image source, see xref:../installing/validating-an-installation.html#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source].
+For information on viewing the CRI-O logs to view the image source, see xref:../installing/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
@@ -65,6 +66,46 @@ In production environments, add the required images to a registry in your restri
  modules/installation-performing-disconnected-mirror-without-registry.adoc[leveloffset=+2]
 ////
 
+[id="mirror-registry"]
+== Mirror registry for Red Hat OpenShift
+
+The _mirror registry for Red Hat OpenShift_ is a small and streamlined container registry that you can use as a target for mirroring the required container images of {product-title} for disconnected installations.
+
+If you already have a container image registry, such as Red Hat Quay, you can skip these steps and go straight to xref:../installing/installing-mirroring-installation-images.adoc#installation-mirror-repository_installing-mirroring-installation-images[Mirroring the OpenShift Container Platform image repository].
+
+.Prerequisites
+
+* An {product-title} subscription.
+* {op-system-base-full} 8 with Podman 3.3 installed.
+* Fully qualified domain name for the Red Hat Quay service, which must resolve through a DNS server.
+* Passwordless `sudo` access on the target host.
+* Key-based SSH connectivity on the target host. SSH keys are automatically generated for local installs. For remote hosts, you must generate your own SSH keys.
+* 2 or more vCPUs.
+* 8 GB of RAM.
+* About 12 GB for {product-title} 4.10 Release images, or about 358 GB for {product-title} 4.10 Release images and {product-title} 4.10 Red Hat Operator images. Up to 1 TB per stream or more is suggested.
++
+[IMPORTANT]
+====
+These requirements are based on local testing results with only Release images and Operator images tested. Storage requirements can vary based on your organization's needs. Some users might require more space, for example, when they mirror multiple z-streams. You can use standard Red Hat Quay functionality to remove unnecessary images and free up space.
+====
+
+include::modules/mirror-registry-introduction.adoc[leveloffset=+1]
+include::modules/mirror-registry-localhost.adoc[leveloffset=+2]
+include::modules/mirror-registry-remote.adoc[leveloffset=+2]
+include::modules/mirror-registry-uninstall.adoc[leveloffset=+2]
+include::modules/mirror-registry-flags.adoc[leveloffset=+2]
+
+.Additional resources
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/manage_red_hat_quay/using-ssl-to-protect-quay[Using SSL to protect connections to Red Hat Quay]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/manage_red_hat_quay/using-ssl-to-protect-quay#configuring_the_system_to_trust_the_certificate_authority[Configuring the system to trust the certificate authority]
+
+* xref:../installing/installing-mirroring-installation-images.adoc#installation-mirror-repository_installing-mirroring-installation-images[Mirroring the OpenShift Container Platform image repository]
+
+* xref:../installing/installing-mirroring-installation-images.adoc#olm-mirror-catalog_installing-mirroring-installation-images[Mirroring Operator catalogs for use with disconnected clusters]
+
+
 include::modules/installation-mirror-repository.adoc[leveloffset=+1]
 
 [id="installing-preparing-samples-operator"]

diff --git a/modules/installation-about-mirror-registry.adoc b/modules/installation-about-mirror-registry.adoc
@@ -7,18 +7,22 @@
 [id="installation-about-mirror-registry_{context}"]
 = About the mirror registry
 
-You can mirror the images that are required for {product-title} installation and subsequent product updates to a mirror registry. These actions use the same process. The release image, which contains the description of the content, and the images it references are all mirrored. In addition, the Operator catalog source image and the images that it references must be mirrored for each Operator that you use. After you mirror the content, you configure each cluster to retrieve this content from your mirror registry.
+You can mirror the images that are required for {product-title} installation and subsequent product updates to a container mirror registry such as Red Hat Quay, JFrog Artifactory, Sonatype Nexus Repository, or Harbor. If you do not have access to a large-scale container registry, you can use the _mirror registry for Red Hat OpenShift_, a small-scale container registry included with {product-title} subscriptions.
 
-The mirror registry can be any container registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2]. All major cloud provider registries, as well as Red Hat Quay, Artifactory, and others, have the necessary support. Using one of these registries ensures that {product-title} can verify the integrity of each image in disconnected environments.
+You can use any container registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker v2-2], such as Red Hat Quay, the _mirror registry for Red Hat OpenShift_, Artifactory, Sonatype Nexus Repository, or Harbor. Regardless of your chosen registry, the procedure to mirror content from Red Hat hosted sites on the internet to an isolated image registry is the same. After you mirror the content, you configure each cluster to retrieve this content from your mirror registry.
 
 [IMPORTANT]
 ====
 The internal registry of the {product-title} cluster cannot be used as the target registry because it does not support pushing without a tag, which is required during the mirroring process.
 ====
 
+If choosing a container registry that is not the _mirror registry for Red Hat OpenShift_, it must be reachable by every machine in the clusters that you provision. If the registry is unreachable, installation, updating, or normal operations such as workload relocation might fail. For that reason, you must run mirror registries in a highly available way, and the mirror registries must at least match the production availability of your {product-title} clusters.
 
-The mirror registry must be reachable by every machine in the clusters that you provision. If the registry is unreachable installation, updating, or normal operations such as workload relocation might fail. For that reason, you must run mirror registries in a highly available way, and the mirror registries must at least match the production availability of your {product-title} clusters.
+When you populate your mirror registry with {product-title} images, you can follow two scenarios. If you have a host that can access both the internet and your mirror registry, but not your cluster nodes, you can directly mirror the content from that machine. This process is referred to as _connected mirroring_. If you have no such host, you must mirror the images to a file system and then bring that host or removable media into your restricted environment. This process is referred to as _disconnected mirroring_.
 
-When you populate a mirror registry with {product-title} images, you can follow two scenarios. If you have a host that can access both the internet and your mirror registry, but not your cluster nodes, you can directly mirror the content from that machine. This process is referred to as _connected mirroring_. If you have no such host, you must mirror the images to a file system and then bring that host or removable media into your restricted environment. This process is referred to as _disconnected mirroring_.
+[NOTE]
+====
+
+====
 
 For mirrored registries, to view the source of pulled images, you must review the `Trying to access` log entry in the CRI-O logs. Other methods to view the image pull source, such as using the `crictl images` command on a node, show the non-mirrored image name, even though the image is pulled from the mirrored location.
diff --git a/modules/mirror-registry-flags.adoc b/modules/mirror-registry-flags.adoc
@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * installing/installing-mirroring-installation-images.adoc
+
+[id="mirror-registry-flags_{context}"]
+= Mirror registry for Red Hat OpenShift flags
+
+The following flags are available for the _mirror registry for Red Hat OpenShift_:
+
+[options="header",cols="1,3"]
+|===
+| Flags | Description
+| `--autoApprove` | A boolean value that disables interactive prompts. If set to `true`, the `quayRoot` directory is automatically deleted when uninstalling the mirror registry. Defaults to `false` if left unspecified.
+| `--initPassword` | The password of the init user created during Quay installation. Must be at least eight characters and contain no whitespace.
+| `--quayHostname` | The fully-qualified domain name of the mirror registry that clients will use to contact the registry. Equivalent to `SERVER_HOSTNAME` in the Quay `config.yaml`. Must resolve by DNS. Defaults to `<targetHostname>:8443` if left unspecified. ^[1]^
+| `--quayRoot`, `-r` | The directory where container image layer and configuration data is saved, including `rootCA.key`, `rootCA.pem`, and `rootCA.srl` certificates. Requires about 12 GB for {product-title} 4.10 Release images, or about 358 GB for {product-title} 4.10 Release images and {product-title} 4.10 Red Hat Operator images. Defaults to `/etc/quay-install` if left unspecified.
+| `--ssh-key`, `-k` | The path of your SSH identity key. Defaults to `~/.ssh/quay_installer` if left unspecified.
+| `--sslCert` | The path to the SSL/TLS public key / certificate. Defaults to `{quayRoot}/quay-config` and is auto-generated if left unspecified.
+| `--sslCheckSkip` | Skips the check for the certificate hostname against the `SERVER_HOSTNAME` in the `config.yaml` file. ^[2]^
+| `--sslKey` | The path to the SSL/TLS private key used for HTTPS communication. Defaults to `{quayRoot}/quay-config` and is auto-generated if left unspecified.
+| `--targetHostname`, `-H` | The hostname of the target you want to install Quay to. Defaults to `$HOST`, for example, a local host, if left unspecified.
+| `--targetUsername`, `-u` | The user on the target host which will be used for SSH. Defaults to `$USER`, for example, the current user if left unspecified.
+| `--verbose`, `-v` | Shows debug logs and Ansible playbook outputs.
+|===
+[.small]
+1. `--quayHostname` must be modified if the public DNS name of your system is different from the local hostname.
+2. `--sslCheckSkip` is used in cases when the mirror registry is set behind a proxy and the exposed hostname is different from the internal Quay hostname. It can also be used when users do not want the certificates to be validated against the provided Quay hostname during installation.
diff --git a/modules/mirror-registry-introduction.adoc b/modules/mirror-registry-introduction.adoc
@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * installing/installing-mirroring-installation-images.adoc
+
+[id="mirror-registry-introduction_{context}"]
+== Mirror registry for Red Hat OpenShift introduction
+
+For disconnected deployments of {product-title}, a container registry is required to carry out the installation of the clusters. To run a production-grade registry service on such a cluster, you must create a separate registry deployment to install the first cluster. The _mirror registry for Red Hat OpenShift_ addresses this need and is included in every OpenShift subscription. It is available for download on the link:https://console.redhat.com/openshift/downloads#tool-mirror-registry[OpenShift console *Downloads*] page.
+
+The _mirror registry for Red Hat OpenShift_ allows users to install a small-scale version of Red Hat Quay and its required components using the `mirror-registry` command line interface (CLI) tool. The _mirror registry for Red Hat OpenShift_ is deployed automatically with pre-configured local storage and a local database. It also includes auto-generated user credentials and access permissions with a single set of inputs and no additional configuration choices to get started.
+
+The _mirror registry for Red Hat OpenShift_ provides a pre-determined network configuration and reports deployed component credentials and access URLs upon success. A limited set of optional configuration inputs like fully qualified domain name (FQDN) services, superuser name and password, and custom TLS certificates are also provided. This provides users with a container registry so that they can easily create an offline mirror of all {product-title} release content when running {product-title} in restricted network environments.
+
+The _mirror registry for Red Hat OpenShift_ is limited to hosting images that are required to install a disconnected {product-title} cluster, such as Release images or Red Hat Operator images. It uses local storage on your {op-system-base-full} machine, and storage supported by {op-system-base} is supported by the _mirror registry for Red Hat OpenShift_. Content built by customers should not be hosted by the _mirror registry for Red Hat OpenShift_.
+
+Unlike Red Hat Quay, the _mirror registry for Red Hat OpenShift_ is not a highly-available registry and only local file system storage is supported. Using the _mirror registry for Red Hat OpenShift_ with more than one cluster is discouraged, because multiple clusters can create a single point of failure when updating your cluster fleet. It is advised to leverage the _mirror registry for Red Hat OpenShift_ to install a cluster that can host a production-grade, highly-available registry such as Red Hat Quay, which can serve {product-title} content to other clusters.
+
+Use of the _mirror registry for Red Hat OpenShift_ is optional if another container registry is already available in the install environment.
diff --git a/modules/mirror-registry-localhost.adoc b/modules/mirror-registry-localhost.adoc
@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * installing/installing-mirroring-installation-images.adoc
+
+[id="mirror-registry-localhost_{context}"]
+= Mirroring on a local host with mirror registry for Red Hat OpenShift
+
+This procedure explains how to install the _mirror registry for Red Hat OpenShift_ on a local host using the `mirror-registry` installer tool. By doing so, users can create a local host registry running on port 443 for the purpose of storing a mirror of {product-title} images.
+
+[NOTE]
+====
+Installing the _mirror registry for Red Hat OpenShift_ using the `mirror-registry` CLI tool makes several changes to your machine. After installation, a `/etc/quay-install` directory is created, which has installation files, local storage, and the configuration bundle. Trusted SSH keys are generated in case the deployment target is the local host, and systemd files on the host machine are set up to ensure that container runtimes are persistent. Additionally, an initial user named `init` is created with an automatically generated password. All access credentials are printed at the end of the install routine.
+====
+
+.Procedure
+
+. Download the `mirror-registry.tar.gz` package for the latest version of the _mirror registry for Red Hat OpenShift_ found on the link:https://console.redhat.com/openshift/downloads#tool-mirror-registry[OpenShift console *Downloads*] page.
+
+. Install the _mirror registry for Red Hat OpenShift_ on your local host with your current user account by using the `mirror-registry` tool. For a full list of available flags, see "mirror registry for Red Hat OpenShift flags".
++
+[source,terminal]
+----
+$ sudo ./mirror-registry install \
+  --quayHostname <host_example_com> \
+  --quayRoot <example_directory_name>
+----
+
+. Use the user name and password generated during installation to log into the registry by running the following command:
++
+[source,terminal]
+----
+$ podman login --authfile pull-secret.txt \
+  -u init \
+  -p <password> \
+  <host_example_com>:8443> \
+  --tls-verify=false <1>
+----
+<1> You can avoid running `--tls-verify=false` by configuring your system to trust the generated rootCA certificates. See "Using SSL to protect connections to Red Hat Quay" and "Configuring the system to trust the certificate authority" for more information.
++
+[NOTE]
+====
+You can also log in by accessing the UI at `\https://<host.example.com>:8443` after installation.
+====
+
+. You can mirror {product-title} images after logging in. Depending on your needs, see either the "Mirroring the {product-title} image repository" or the "Mirroring Operator catalogs for use with disconnected clusters" sections of this document.
++
+[NOTE]
+====
+If there are issues with images stored by the _mirror registry for Red Hat OpenShift_ due to storage layer problems, you can remirror the {product-title} images, or reinstall mirror registry on more stable storage.
+====