OpenShift Disconnected Install: Step 0 – Mirror Registry

Posted in openshift

It’s super interesting that I came back to this blog after literally 5 years of absence. Since I moved from the Portworx team at Everpure (née Pure Storage) into a role a little more focused on sales here at Red Hat, I haven’t felt the need to continue to write technical tidbits. But I’ve had a number of customers struggle with installing OpenShift in a fully disconnected environment and as I was getting ready to write the same email 8 different times, I thought perhaps it might be better to point them at a blog post that describes the process in some detail.

A disconnected environment is sometimes referred to as an air-gapped deployment. It’s an environment where the systems targeted for deployment have no connections with other networks. This means the deployment must be self contained, all of the dependent services must be contained in the environment when in operation but it also means during install there is no connection to any other environment to retrieve the content required for the installation.

A tiny little note here before I get started – this post is free from AI. I’m not sure if that makes me a luddite or not, but I still enjoy the old fashioned process of organizing my own thoughts and letting them flow from my brain through my fingers into written word.

Options for Mirroring Required OpenShift Install Media

Step 0 for the disconnected install process is creating a “mirror” of OpenShift installation content. You’ll need to decide where this content will eventually reside. The OpenShift install process requires an image registry to pull data from for the install, and the registry must have all of the content your configured install needs. This is where Red Hat’s documentation gets a little unintuitive. The process here is:

  1. Choose the image registry that you will host the content in. This registry should be docker v2-2 api compliant.
  2. (Optional) Install a Red Hat provided Quay-based registry to host the content as a temporary solution
  3. Decide how you will need to transfer the data to the image registry. Your options are:
  4. (Optional) Mirror content to disk
  5. (Optional) Mirror content from disk to target registry
  6. Mirror content directly from Red Hat to the target registry

Generally, customers choose to deploy the temporary registry we provide and mirror directly to it. This might present a few challenges to you. It means the system you are hosting the registry on needs internet access, either in the beginning of the install process or throughout. This could be a laptop that starts on a network with internet access, is unplugged and introduced to the disconnected environment, or a bastion host that can have access in the start of the install process.

I’m going to cover the process to install a registry to a local Linux host and mirror content directly from Red Hat to the target registry. This process is documented in official Red Hat documentation, but after several customers have asked me for clarification, I thought I should take a run at making it a little clearer.

The documentation is available here: https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/disconnected_environments/installing-mirroring-creating-registry#mirror-registry-introduction_installing-mirroring-creating-registry

Required Tools

There are several tools required for the install. These tools (except the Linux Host) are downloaded as gzip tarballs. You’re going to download the tarball to the host you’re installing into, uncompressed the binaries and then copy to somewhere in your path.

Linux Host(s)

In many scenarios you’re going to use just one host which will host the image registry and to be the machine you run the tools required to pull the installation content. In this scenario you have a utility system that is ephemeral – you’re going to remove it from the environment once the installations are complete. You may choose for other reasons to have a utility server persist in the environment outside of OpenShift to act as a bastion for access, to host the image registry and provide generic services like DNS, Identity Management or services specific to your workloads.

mirror-registry tool

The “mirror-registry” tool is an application that will create a light version of the Quay image registry service if you do not have an image registry present in the environment where the installation will take place. It will run in a container on the host. Red Hat Enterprise Linux systems from version 8 and on include Podman, which will allow you to run the container on the host.

You can download the mirror-registry tool from your Red Hat Console. Navigate to console.redhat.com and click on the “OpenShift” tile. Once in the OpenShift section, find “Resources” on the left hand side of the UI. Click “Resources” and then select “Downloads”. Scroll down near the bottom of the window to find the section labelled “OpenShift disconnected installation tools”. You’ll see the button to download “mirror registry for Red Hat OpenShift” there. You can also right click the button, copy the download link provided by the button and use it in a curl or wget command on your host.

Official Red Hat documentation on the tool is available here: https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/disconnected_environments/installing-mirroring-installation-images#installation-about-mirror-registry_installing-mirroring-installation-images

openshift client (oc) tool

The oc tool is something you will want to leverage for managing OpenShift in general, but specifically for this process, it’s going to be used to replicate content from the Red Hat image registries to your selected end point, either the image registry that’s already been deployed, or the registry you have deployed with mirror-registry. Inside of console.redhat.com in the OpenShift section, in the same Resources > Downloads section, at the very top under “Command-line interface (CLI) tools”. You can press the button to download directly and copy to the host you will run from, or right click and copy the link to paste into a curl or wget command.

Official Red Hat documentation is here: https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/cli_tools/openshift-cli-oc#cli-about-cli_cli-developer-commands

oc mirror plugin

Lastly the oc mirror plugin is found in the same location as the mirror-registry tool – near the bottom of the Downloads page you’ll see “OpenShift disconnected installation tools” and the “OpenShift Client (oc) mirror plugin”. Make sure you choose the correct version of linux, and the correct architecture version and either download directly or copy the link and paste into a command on your host.

The official Red Hat docs for oc mirror are here: https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/disconnected_environments/about-installing-oc-mirror-v2

There is also a GitHub page for the plugin, with some documentation as well: https://github.com/openshift/oc-mirror

Building the Mirror

Download & Install Tools

curl -LO https://mirror.openshift.com/pub/cgw/mirror-registry/latest/mirror-registry-amd64.tar.gz
curl -LO https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/stable/openshift-client-linux.tar.gz
curl -LO https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/latest/oc-mirror.rhel9.tar.gz
mkdir mirror-registry
tar zxvf mirror-registry-amd64.tar.gz -C mirror-registry
tar zxvf openshift-client-linux.tar.gz
tar zxvf oc-mirror.rhel9.tar.gz

Once you’ve downloaded the files and unzipped it all, you’ll have a bunch of binaries. mirror-registry, oc, oc-mirror. 

chmod +x oc-mirror
sudo mv oc /usr/local/bin
sudo mv kubectl /usr/local/bin
sudo mv oc-mirror /usr/local/bin

(Optional) Install Image Registry with mirror-registry

You will need openssl and podman on the system before running. You can run the mirror-registry command with –help flag to get details on the possible parameters. The install will run by default fine – you may want to set the password with the –initPassword flag. 

./mirror-registry install --initPassword password

Once the install process has completed, you’ll see a “Waiting up to 3 minutes for Quay to become alive at https://localhost8443/health/instance”. Eventually that should complete as the service comes up and is alive. The last status message should look like this: 

INFO[2026-03-09 00:20:24] Quay installed successfully, config data is stored in ~/quay-install 
INFO[2026-03-09 00:20:24] Quay is available at https://[hostname]:8443 with credentials (init, password)

Type ‘podman ps’ and you’ll see the three pods created to support the service. If you can route 8443 traffic to the host, you could log into the Quay web interface with the credentials.

We need to trust the rootCA certificates generated during the install process so we don’t have to use the skip tls flags. 

cd ~/quay-install
cd quay-rootCA
sudo cp rootCA.pem /etc/pki/ca-trust/source/anchors
update-ca-trust extract 
cd
podman login -u init -p password <host>:8443

Replicate Red Hat Registry to Local Registry

Once your registry is up and running, your auth is all set up (you can talk to your version of Quay running), you’re ready to replicate the Red Hat OpenShift release images and Red Hat Operator images. Current guidance in Red Hat documentation is that you’ll need 12GB for OpenShift Container Platform, and about 358GB for OpenShift and Red Hat Operator images.

Download your Pull Secret from console.redhat.com. You will find it in a few places, but if you make your way back to the OpenShift section of the console, click Resources > Downloads you’ll find your Pull Secret at the very bottom in the “Tokens” section. You can copy and paste the token to your ssh session or download and transfer it there.

This is where it starts to get interesting. Long time Linux admins will recognize these shenanigans but if you’re new to Linux this might seem odd. The overall goal is for the oc mirror plugin to have an auth file with credentials it can use to talk to a specific endpoint, like the one you’re trying to push to. The Pull Secret actually already has a bunch of details for accessing Red Hat resources, you’re going to add your credentials for the image registry you’ve configure.

To start, we need to translate the Pull Secret into JSON. We’re going to convert it, and then create a new file in a specific location in the filesystem that processes resulting from the oc mirror plugin can use. Then we’re going to encode the local image registry credentials with base64, and add them to the authorization file.

You’ll see the commands I used below. My Pull Secret is in a file called pull-secret and I converted it to pull-secret.json and copied it to the new location with the proper filename. The echo command is how I produced an encoded version of the credentials that I added to the auth.json file. 

cat ./pull-secret | jq . > pull-secret.json
cp pull-secret.json $XDG_RUNTIME_DIR/containers/auth.json
echo -n 'init:password' | base64 -w0

I need to now use the base64 encoded credentials to populate a new section in the auth.json file I just created in the crazy XDG_RUNTIME_DIR. As an example, since I was re-validating the approach I created the following section in the auth file:

"auths": {
  "ip-172-31-21-233.us-east-2.compute.internal:8443":{
    "auth": "aW5pdDpwYXNzd29yZA==",
    "email": "chrisb@redhat.com"
  },

Use your favourite text editor and follow the formatting of the file. This might seem a little odd when you’re reading it through for the first time, but with a terminal in front of you it should make sense.

At this point, we should be ready to mirror the registry. Like most other oc commands, we need to feed the command a YAML file with all the settings. If it was your first time to my blog and you wondered “why does it say it’s a ‘blog about YAML’?”, welcome.

Here’s the example file from Red Hat documentation: 

kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v2alpha1
mirror:
  platform:
    channels:
    - name: stable-4.20 
      minVersion: 4.20.2
      maxVersion: 4.20.2
    graph: true 
  operators:
    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.20 
      packages: 
       - name: aws-load-balancer-operator
       - name: 3scale-operator
       - name: node-observability-operator
  additionalImages: 
   - name: registry.redhat.io/ubi8/ubi:latest
   - name: registry.redhat.io/ubi9/ubi@sha256:20f695d2a91352d4eaa25107535126727b5945bff38ed36a3e59590f495046f0

I saved this file to the working directory as ImageSetConfiguration.yaml

The full documentation of the ImageSetConfiguration is here: https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/disconnected_installation_mirroring/installing-mirroring-disconnected#oc-mirror-imageset-config-params_installing-mirroring-disconnected

There are more examples of ImageSetConfiguration files here: https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/disconnected_installation_mirroring/installing-mirroring-disconnected#oc-mirror-image-set-examples_installing-mirroring-disconnected

And now we are ready to go! I set the workspace as local directory. 

oc mirror -c imagesetconfiguration.yaml --workspace file://./ docker://[hostname]:8443 --v2

You should see oc-mirror start working – it collects all the release image information, the operator images, creating a catalogue an then starting to pull images from Red Hat and push to the registry you provided. You’ll see a progress bar at the bottom, and a crawl of images being downloaded and pushed to the registry you configured as the target. Once complete you should see the progress bar get all the way to 100% and it should finally say:

[INFO]   : 👋 Goodbye, thank you for using oc-mirror

That’s it! The set of images defined in your ImageSetConfiguration have been pushed to your local registry. If you’re able, you could point a web browser at this Quay instance and browse the catalogues created by this process.

Now that this is done, you’re ready to move on to installing OpenShift in your disconnected environment!

Work In Progress Sections

(Optional) Replicate Registry to Disk

In many disconnected environments, customers will choose to replicate Red Hat’s registry to disk, “sneaker net” the disk – either a USB key or hard drive – to the environment and then pull the images into the registry from the hard drive when in the disconnected environment. The process is similar to the one I’ve documented here, but the initial oc mirror command is TO disk, and we run another command FROM disk once connected to the air-gapped environment. More to follow here.

(Optional) Replicate Disk-based Image Registry to Local Registry

Unknown's avatar

Published by Chris Saunders

Infrastructure nerd learning to code and be a better human

Leave a comment