$ ./mirror-registry install \
--quayHostname <host_example_com> \
--quayRoot <example_directory_name>
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 OKD 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.
An OKD subscription.
Fedora 8 and 9 with Podman 3.4.2 or later and OpenSSL installed.
Fully qualified domain name for the Red Hat Quay service, which must resolve through a DNS server.
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 OKD 4.13 release images, or about 358 GB for OKD 4.13 release images and OKD 4.13 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 or the proper API callout to remove unnecessary images and free up space. |
For disconnected deployments of OKD, 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 preconfigured 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 OKD release content when running OKD in restricted network environments.
Use of the mirror registry for Red Hat OpenShift is optional if another container registry is already available in the install environment.
The following limitations apply to the mirror registry for Red Hat OpenShift:
The mirror registry for Red Hat OpenShift is not a highly-available registry and only local file system storage is supported. It is not intended to replace Red Hat Quay or the internal image registry for OKD.
The mirror registry for Red Hat OpenShift is not intended to be a substitute for a production deployment of Red Hat Quay.
The mirror registry for Red Hat OpenShift is only supported for hosting images that are required to install a disconnected OKD cluster, such as Release images or Red Hat Operator images. It uses local storage on your Fedora machine, and storage supported by Fedora is supported by the mirror registry for Red Hat OpenShift.
Because the mirror registry for Red Hat OpenShift uses local storage, you should remain aware of the storage usage consumed when mirroring images and use Red Hat Quay’s garbage collection feature to mitigate potential issues. For more information about this feature, see "Red Hat Quay garbage collection". |
Support for Red Hat product images that are pushed to the mirror registry for Red Hat OpenShift for bootstrapping purposes are covered by valid subscriptions for each respective product. A list of exceptions to further enable the bootstrap experience can be found on the Self-managed Red Hat OpenShift sizing and subscription guide.
Content built by customers should not be hosted by the mirror registry for Red Hat OpenShift.
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 OKD content to other clusters.
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 OKD images.
Installing the mirror registry for Red Hat OpenShift using the |
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".
$ ./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 -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 |
You can mirror OKD images after logging in. Depending on your needs, see either the "Mirroring the OKD 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 OKD images, or reinstall mirror registry on more stable storage. |
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 new features, bug fixes, and security vulnerability fixes.
When upgrading from version 1 to version 2, be aware of the following constraints:
|
You have installed the mirror registry for Red Hat OpenShift on a local host.
If you are upgrading the mirror registry for Red Hat OpenShift from 1.3 → 2.y, and your installation directory is the default at /etc/quay-install
, you can enter the following command:
$ sudo ./mirror-registry upgrade -v
|
If you are upgrading the mirror registry for Red Hat OpenShift from 1.3 → 2.y and you used a custom quay configuration and storage directory in your 1.y deployment, you must pass in the --quayRoot
and --quayStorage
flags. For example:
$ sudo ./mirror-registry upgrade --quayHostname <host_example_com> --quayRoot <example_directory_name> --quayStorage <example_directory_name>/quay-storage -v
If you are upgrading the mirror registry for Red Hat OpenShift from 1.3 → 2.y and want to specify a custom SQLite storage path, you must pass in the --sqliteStorage
flag, for example:
$ sudo ./mirror-registry upgrade --sqliteStorage <example_directory_name>/sqlite-storage -v
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 OKD images.
Installing the mirror registry for Red Hat OpenShift using the |
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".
$ ./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 -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 |
You can mirror OKD 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 OKD images, or reinstall mirror registry on more stable storage. |
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 upgrading from version 1 to version 2, be aware of the following constraints:
|
You have installed the mirror registry for Red Hat OpenShift on a remote host.
To upgrade the mirror registry for Red Hat OpenShift from a remote host, enter the following command:
$ ./mirror-registry upgrade -v --targetHostname <remote_host_url> --targetUsername <user_name> -k ~/.ssh/my_ssh_key
Users who upgrade the mirror registry for Red Hat OpenShift with the |
If you are upgrading the mirror registry for Red Hat OpenShift from 1.3 → 2.y and want to specify a custom SQLite storage path, you must pass in the --sqliteStorage
flag, for example:
$ ./mirror-registry upgrade -v --targetHostname <remote_host_url> --targetUsername <user_name> -k ~/.ssh/my_ssh_key --sqliteStorage <example_directory_name>/quay-storage
In some cases, you might want to update your SSL/TLS certificates for the mirror registry for Red Hat OpenShift. This is useful in the following scenarios:
If you are replacing the current mirror registry for Red Hat OpenShift certificate.
If you are using the same certificate as the previous mirror registry for Red Hat OpenShift installation.
If you are periodically updating the mirror registry for Red Hat OpenShift certificate.
Use the following procedure to replace mirror registry for Red Hat OpenShift SSL/TLS certificates.
You have downloaded the ./mirror-registry
binary from the OpenShift console Downloads page.
Enter the following command to install the mirror registry for Red Hat OpenShift:
$ ./mirror-registry install \
--quayHostname <host_example_com> \
--quayRoot <example_directory_name>
This installs the mirror registry for Red Hat OpenShift to the $HOME/quay-install
directory.
Prepare a new certificate authority (CA) bundle and generate new ssl.key
and ssl.crt
key files. For more information, see Using SSL/TLS to protect connections to Red Hat Quay.
Assign /$HOME/quay-install
an environment variable, for example, QUAY
, by entering the following command:
$ export QUAY=/$HOME/quay-install
Copy the new ssl.crt
file to the /$HOME/quay-install
directory by entering the following command:
$ cp ~/ssl.crt $QUAY/quay-config
Copy the new ssl.key
file to the /$HOME/quay-install
directory by entering the following command:
$ cp ~/ssl.key $QUAY/quay-config
Restart the quay-app
application pod by entering the following command:
$ systemctl restart quay-app
You can uninstall the mirror registry for Red Hat OpenShift from your local host by running the following command:
$ ./mirror-registry uninstall -v \
--quayRoot <example_directory_name>
|
The following flags are available for the mirror registry for Red Hat OpenShift:
Flags | Description |
---|---|
|
A boolean value that disables interactive prompts. If set to |
|
The password of the init user created during Quay installation. Must be at least eight characters and contain no whitespace. |
|
Shows the username of the initial user. Defaults to |
|
Allows users to disable color sequences and propagate that to Ansible when running install, uninstall, and upgrade commands. |
|
The fully-qualified domain name of the mirror registry that clients will use to contact the registry. Equivalent to |
|
The folder where Quay persistent storage data is saved. Defaults to the |
|
The directory where container image layer and configuration data is saved, including |
|
The folder where SQLite database data is saved. Defaults to |
|
The path of your SSH identity key. Defaults to |
|
The path to the SSL/TLS public key / certificate. Defaults to |
|
Skips the check for the certificate hostname against the |
|
The path to the SSL/TLS private key used for HTTPS communication. Defaults to |
|
The hostname of the target you want to install Quay to. Defaults to |
|
The user on the target host which will be used for SSH. Defaults to |
|
Shows debug logs and Ansible playbook outputs. |
|
Shows the version for the mirror registry for Red Hat OpenShift. |
--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.
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 OKD for disconnected installations.
These release notes track the development of the mirror registry for Red Hat OpenShift in OKD.
The following sections provide details for each 2.0 release of the mirror registry for Red Hat OpenShift
Issued: 26 September 2024
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.12.1.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 03 September 2024
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.12.0.
The following advisory is available for the mirror registry for Red Hat OpenShift:
With the release of mirror registry for Red Hat OpenShift, the internal database has been upgraded from PostgreSQL to SQLite. As a result, data is now stored on the sqlite-storage
Podman volume by default, and the overall tarball size is reduced by 300 MB.
New installations use SQLite by default. Before upgrading to version 2.0, see "Updating mirror registry for Red Hat OpenShift from a local host" or "Updating mirror registry for Red Hat OpenShift from a remote host" depending on your environment.
A new feature flag, --sqliteStorage
has been added. With this flag, you can manually set the location where SQLite database data is saved.
The following sections provide details for each 1.3.z release of the mirror registry for Red Hat OpenShift
Issued: 2024-04-23
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.15.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-12-07
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.14.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-09-19
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.12.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-08-16
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.11.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-07-19
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.10.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-05-30
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.8.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-05-18
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.7.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-04-25
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.6.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-04-05
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.5.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-03-21
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.4.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-03-7
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.3.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Issued: 2023-02-20
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.8.1.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Mirror registry for Red Hat OpenShift is now supported on Fedora 9 installations.
IPv6 support is now available on mirror registry for Red Hat OpenShift local host installations.
IPv6 is currently unsupported on mirror registry for Red Hat OpenShift remote host installations.
A new feature flag, --quayStorage
, has been added. By specifying this flag, you can manually set the location for the Quay persistent storage.
A new feature flag, --pgStorage
, has been added. By specifying this flag, you can manually set the location for the Postgres persistent storage.
Previously, users were required to have root privileges (sudo
) to install mirror registry for Red Hat OpenShift. With this update, sudo
is no longer required to install mirror registry for Red Hat OpenShift.
When mirror registry for Red Hat OpenShift was installed with sudo
, an /etc/quay-install
directory that contained installation files, local storage, and the configuration bundle was created. With the removal of the sudo
requirement, installation files and the configuration bundle are now installed to $HOME/quay-install
. Local storage, for example Postgres and Quay, are now stored in named volumes automatically created by Podman.
To override the default directories that these files are stored in, you can use the command line arguments for mirror registry for Red Hat OpenShift. For more information about mirror registry for Red Hat OpenShift command line arguments, see "Mirror registry for Red Hat OpenShift flags".
Previously, the following error could be returned when attempting to uninstall mirror registry for Red Hat OpenShift: ["Error: no container with name or ID \"quay-postgres\" found: no such container"], "stdout": "", "stdout_lines": []*
. With this update, the order that mirror registry for Red Hat OpenShift services are stopped and uninstalled have been changed so that the error no longer occurs when uninstalling mirror registry for Red Hat OpenShift. For more information, see PROJQUAY-4629.
The following sections provide details for each 1.2.z release of the mirror registry for Red Hat OpenShift
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.7.10.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.7.9.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.7.8.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Previously, getFQDN()
relied on the fully-qualified domain name (FQDN) library to determine its FQDN, and the FQDN library tried to read the /etc/hosts
folder directly. Consequently, on some Fedora CoreOS (FCOS) installations with uncommon DNS configurations, the FQDN library would fail to install and abort the installation. With this update, mirror registry for Red Hat OpenShift uses hostname
to determine the FQDN. As a result, the FQDN library does not fail to install. (PROJQUAY-4139)
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.7.7.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.7.6.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.7.5.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.7.4.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.7.3.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.7.2.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Mirror registry for Red Hat OpenShift is now available with Red Hat Quay 3.7.1.
The following advisory is available for the mirror registry for Red Hat OpenShift:
Previously, all components and workers running inside of the Quay pod Operator had log levels set to DEBUG
. As a result, large traffic logs were created that consumed unnecessary space. With this update, log levels are set to WARN
by default, which reduces traffic information while emphasizing problem scenarios. (PROJQUAY-3504)
The following section provides details 1.1.0 release of the mirror registry for Red Hat OpenShift
The following advisory is available for the mirror registry for Red Hat OpenShift:
A new command, mirror-registry upgrade
has been added. This command upgrades all container images without interfering with configurations or data.
If |
Previously, the absence of quayHostname
or targetHostname
did not default to the local hostname. With this update, quayHostname
and targetHostname
now default to the local hostname if they are missing. (PROJQUAY-3079)
Previously, the command ./mirror-registry --version
returned an unknown flag
error. Now, running ./mirror-registry --version
returns the current version of the mirror registry for Red Hat OpenShift. (PROJQUAY-3086)
Previously, users could not set a password during installation, for example, when running ./mirror-registry install --initUser <user_name> --initPassword <password> --verbose
. With this update, users can set a password during installation. (PROJQUAY-3149)
Previously, the mirror registry for Red Hat OpenShift did not recreate pods if they were destroyed. Now, pods are recreated if they are destroyed. (PROJQUAY-3261)
To assist in troubleshooting mirror registry for Red Hat OpenShift, you can gather logs of systemd services installed by the mirror registry. The following services are installed:
quay-app.service
quay-postgres.service
quay-redis.service
quay-pod.service
You have installed mirror registry for Red Hat OpenShift.
If you installed mirror registry for Red Hat OpenShift with root privileges, you can get the status information of its systemd services by entering the following command:
$ sudo systemctl status <service>
If you installed mirror registry for Red Hat OpenShift as a standard user, you can get the status information of its systemd services by entering the following command:
$ systemctl --user status <service>