Creating a mirror registry with mirror registry for Red Hat OpenShift - Disconnected installation mirroring | Installing

Prerequisites
Mirror registry for Red Hat OpenShift introduction
Mirroring on a local host with mirror registry for Red Hat OpenShift
Updating mirror registry for Red Hat OpenShift from a local host
Mirroring on a remote host with mirror registry for Red Hat OpenShift
Updating mirror registry for Red Hat OpenShift from a remote host
Uninstalling the mirror registry for Red Hat OpenShift
Mirror registry for Red Hat OpenShift flags
Mirror registry for Red Hat OpenShift release notes

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 OpenShift Container Platform for disconnected installations.

If you already have a container image registry, such as Red Hat Quay, you can skip this section and go straight to Mirroring the OpenShift Container Platform image repository.

Prerequisites

An OpenShift Container Platform subscription.
Red Hat Enterprise Linux (RHEL) 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 OpenShift Container Platform 4.11 release images, or about 358 GB for OpenShift Container Platform 4.11 release images and OpenShift Container Platform 4.11 Red Hat Operator images. Up to 1 TB per stream or more is suggested.

These requirements are based on local testing results with only release images and Operator images. Storage requirements can vary based on your organization’s needs. You might require more space, for example, when you mirror multiple z-streams. You can use standard Red Hat Quay functionality to remove unnecessary images and free up space.

Mirror registry for Red Hat OpenShift introduction

For disconnected deployments of OpenShift Container Platform, 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 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 OpenShift Container Platform release content when running OpenShift Container Platform in restricted network environments.

The mirror registry for Red Hat OpenShift is limited to hosting images that are required to install a disconnected OpenShift Container Platform cluster, such as Release images or Red Hat Operator images. It uses local storage on your Red Hat Enterprise Linux (RHEL) machine, and storage supported by RHEL 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 OpenShift Container Platform 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.

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 OpenShift Container Platform images.

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 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".
```
$ 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:

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

You can also log in by accessing the UI at https://<host.example.com>:8443 after installation.

You can mirror OpenShift Container Platform images after logging in. Depending on your needs, see either the "Mirroring the OpenShift Container Platform image repository" or the "Mirroring Operator catalogs for use with disconnected clusters" sections of this document.

If there are issues with images stored by the mirror registry for Red Hat OpenShift due to storage layer problems, you can remirror the OpenShift Container Platform images, or reinstall mirror registry on more stable storage.

Updating mirror registry for Red Hat OpenShift from a local host

This procedure explains how to update the mirror registry for Red Hat OpenShift from a local host using the upgrade command. Updating to the latest version ensures bug fixes and security vulnerability fixes.

When updating, there is intermittent downtime of your mirror registry, as it is restarted during the update process.

Prerequisites

You have installed the mirror registry for Red Hat OpenShift on a local host.

Procedure

To upgrade the mirror registry for Red Hat OpenShift from localhost, enter the following command:

$ sudo ./mirror-registry upgrade -v

Users who upgrade the mirror registry for Red Hat OpenShift with the ./mirror-registry upgrade -v flag must include the same credentials used when creating their mirror registry. For example, if you installed the mirror registry for Red Hat OpenShift with --quayHostname <host_example_com> and --quayRoot <example_directory_name>, you must include that string to properly upgrade the mirror registry.

Mirroring on a remote host with mirror registry for Red Hat OpenShift

This procedure explains how to install the mirror registry for Red Hat OpenShift on a remote host using the mirror-registry tool. By doing so, users can create a registry to hold a mirror of OpenShift Container Platform images.

Procedure

Download the mirror-registry.tar.gz package for the latest version of the mirror registry for Red Hat OpenShift found on the 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".

$ sudo ./mirror-registry install -v \
  --targetHostname <host_example_com> \
  --targetUsername <example_user> \
  -k ~/.ssh/my_ssh_key \
  --quayHostname <host_example_com> \
  --quayRoot <example_directory_name>

Use the user name and password generated during installation to log into the mirror registry by running the following command:

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

You can also log in by accessing the UI at https://<host.example.com>:8443 after installation.

Updating mirror registry for Red Hat OpenShift from a remote host

This procedure explains how to update the mirror registry for Red Hat OpenShift from a remote host using the upgrade command. Updating to the latest version ensures bug fixes and security vulnerability fixes.

When updating, there is intermittent downtime of your mirror registry, as it is restarted during the update process.

Prerequisites

You have installed the mirror registry for Red Hat OpenShift on a remote host.

Procedure

To upgrade the mirror registry for Red Hat OpenShift from a remote host, enter the following command:

$ sudo ./mirror-registry upgrade -v --targetHostname <remote_host_url> --targetUsername <user_name> -k ~/.ssh/my_ssh_key

Uninstalling the mirror registry for Red Hat OpenShift

You can uninstall the mirror registry for Red Hat OpenShift from your local host by running the following command:

$ sudo ./mirror-registry uninstall -v \
  --quayRoot <example_directory_name>

Deleting the mirror registry for Red Hat OpenShift will prompt the user before deletion. You can use --autoApprove to skip this prompt.
Users who install the mirror registry for Red Hat OpenShift with the --quayRoot flag must include the --quayRoot flag when uninstalling. For example, if you installed the mirror registry for Red Hat OpenShift with --quayRoot example_directory_name, you must include that string to properly uninstall the mirror registry.

Mirror registry for Red Hat OpenShift flags

The following flags are available for the mirror registry for Red Hat OpenShift:

Flags Description

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.
`--initUser string`	Shows the username of the initial user. Defaults to `init` if left unspecified.
`--no-color`, `-c`	Allows users to disable color sequences and propagate that to Ansible when running install, uninstall, and upgrade commands.
`--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 OpenShift Container Platform 4.10 Release images, or about 358 GB for OpenShift Container Platform 4.10 Release images and OpenShift Container Platform 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.

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

--initUser string

Shows the username of the initial user. Defaults to init if left unspecified.

--no-color, -c

Allows users to disable color sequences and propagate that to Ansible when running install, uninstall, and upgrade commands.

--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 OpenShift Container Platform 4.10 Release images, or about 358 GB for OpenShift Container Platform 4.10 Release images and OpenShift Container Platform 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.

--quayHostname must be modified if the public DNS name of your system is different from the local hostname. Additionally, the --quayHostname flag does not support installation with an IP address. Installation with a hostname is required.
--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.

Mirror registry for Red Hat OpenShift release notes

These release notes track the development of the mirror registry for Red Hat OpenShift in OpenShift Container Platform.

For an overview of the mirror registry for Red Hat OpenShift, see Creating a mirror registry with mirror registry for Red Hat OpenShift.