Disconnected Overview

Let’s start with an overview of OpenShift’s disconnected installation process. You can refer to the OpenShift documentation for more details.

The disconnected installation steps are:

1. Prepare a system (jump) that can download the mirroring tools and the OpenShift installation images

Use oc-mirror to download the installation images

2. Move the mirroring tools and installation images from the jump system to the highside system

We’ll use rsync in this workshop
Many people use DVDs or USBs to walk content between systems and over air gaps
- This is known as 👟 sneaker net 👟

3. Setup a system (highside) that can serve the installation images in the disconnected network

Install the mirror-registry
Use oc-mirror to populate the mirror-registry

4. Tell the OpenShift Installer (openshift-install) where to find the installation images

Add three additional sections to the install-config.yaml file
- Add the mirror-registry as an approved mirror / installation source
- Add credentials (pull secret) for the mirror-registry
- Trust the TLS certificate of the mirror-registry

5. After OpenShift has been installed…

Tell OpenShift where to look for apps / Operators
Tell OpenShift where to look for updates

Now that we know the procedure, let’s start with Step 1 - Preparing the jump system

Preparing the jump system

The jump system lives in the lowside network which allows it to download the mirroring tools and installation images. The network is called lowside because it has a low security profile, and shouldn’t be used to store sensitive information.

Download Mirroring Tools

OpenShift provides two primary tools that are used to create disconnected clusters:

1. oc-mirror - A tool to help you download:

The OpenShift installation images (a specific set of container images)
Additional container images such as docker.io/wordpress
Individual Operators like the Web Terminal, the DISA STIG Compliance Operator, etc…
Helm charts like csi-driver-nfs

2. mirror-registry - An image registry that serves container images to the OpenShift nodes

This is a smaller & streamlined version of the Red Hat Quay Image Registry

We will also download two additional tools that will be used later on the highside system.

3. openshift-install: The OpenShift Installer

4. oc: The OpenShift command line interface

OpenShift 4.10 introduced oc-mirror as a new tool to download OpenShift content. The previous tool, oc adm release mirror …, is still available but not recommended.

oc-mirror allows you to download additional images, Helm charts, and individual Operators.
oc-mirror also intelligently downloads only the changes when updates are downloaded.

Disconnected OpenShift installations can use any image registry that supports the Docker v2 API, provide TLS encryption, and require authenticated image pulls, such as:

Harbor
JFrog Artifactory
Sonatype Nexus Repository
Red Hat Quay Registry (enterprise)

Click the Copy button to quickly grab all of the commands in the code blocks.

Press Ctrl + Shift + V to paste.
Using Ctrl + Insert (copy) and Shift + Insert (paste) also works.

The pasted commands won’t run immediately. You must to hit Enter/Return yourself.

Please begin by changing your directory to /mnt/low-side-data/
Then use the following commands to download and extract the required tools.

oc-mirror: A plugin to the oc command for mirorring OpenShift releases, apps / Operators, additional images, and Helm charts

cd /mnt/low-side-data/
curl -L -o oc-mirror.tar.gz https://mirror.openshift.com/pub/openshift-v4/clients/ocp/4.14.19/oc-mirror.tar.gz
tar -xzf oc-mirror.tar.gz
rm -f oc-mirror.tar.gz
chmod +x oc-mirror
sudo cp -v oc-mirror /bin

mirror-registry: a small-scale Red Hat Quay registry designed for mirroring

curl -L -o mirror-registry.tar.gz https://mirror.openshift.com/pub/cgw/mirror-registry/latest/mirror-registry-amd64.tar.gz

openshift-install: The OpenShift Installer

curl -L -o openshift-install.tar.gz https://mirror.openshift.com/pub/openshift-v4/clients/ocp/4.14.19/openshift-install-linux.tar.gz
tar -xzf openshift-install.tar.gz openshift-install
rm -f openshift-install.tar.gz

oc: The OpenShift command line interface

curl -L -o oc.tar.gz https://mirror.openshift.com/pub/openshift-v4/clients/ocp/4.14.19/openshift-client-linux.tar.gz
tar -xzf oc.tar.gz oc
rm -f oc.tar.gz
sudo cp -v oc /bin

Checkpoint

The commands above asked you to download and extract OpenShift’s mirroring and installation tools. You can verify your work by looking at the files in your low side transfer directory (/mnt/low-side-data). You should see four files in that directory

ls -1 /mnt/low-side-data/

mirror-registry.tar.gz
oc
oc-mirror
openshift-install

Mirroring the OpenShift installation images

Now that the mirroring and installation tools have been downloaded and extracted, it’s time to put oc-mirror to work! Let’s start with a brief overview of using oc-mirror:

1. Provide access credentials (a pull secret)

Credentials are required to download OpenShift installation images

2. Create an ImageSetConfiguration YAML file that describes:

What to download (OpenShift itself, an Operator, and an image)
What versions (e.g. everything between 4.14.19 and 4.14.20)
Where to store the downloaded content

3. Run oc-mirror with the YAML file

This process downloads ~25 GB of data and takes about 15 minutes in this workshop environment
We will run the download in a separate (tmux) terminal so that you can keep working.

A pull secret is JSON-formated data that combines authentication information for one or more Image Registries into a single file. You can find your own pull secret in the Red Hat Hybrid Cloud Console.

This workshop provides a generic pull secret in order to avoid delays logging in to the Hybrid Cloud Console and avoid frustrations using vi, nano or emacs.

More information about pull secrets can be found in the Appendix.

Please begin by copying the provided pull secret into the default location.

mkdir -v $HOME/.docker
cp -v $HOME/pull-secret-example.json $HOME/.docker/config.json

mkdir: created directory '/home/lab-user/.docker'
'/home/lab-user/pull-secret-example.json' -> '/home/lab-user/.docker/config.json'

Then create an ImageSetConfiguration YAML file that tells oc-mirror what to downloaded. A template of this file is provided for you. To save time and storage, the template downloads:

Two specific versions of OpenShift
One optional app / Operator, the Web Terminal Operator
One additional image, registry.redhat.io/rhel8/support-tools
No Helm charts will be download

You can find a more detailed example of an ImageSetConfig in this GitHub Gist. Please don’t make any changes to the provided ImageSetConfig because it will increase the amount of time required to download and transfer the content.

Create a file called imageset-config.yaml with the following contents:

cat << EOF > /mnt/low-side-data/imageset-config.yaml
---
kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v1alpha2
storageConfig:
  local:
    path: ./
mirror:
  platform:
    channels:
    - name: stable-4.14
      type: ocp
      minVersion: 4.14.19
      maxVersion: 4.14.20

  operators:
  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.14
    packages:
    - name: web-terminal
      channels:
      - name: fast

  additionalImages:
  - name: registry.redhat.io/rhel8/support-tools

  helm: {}
EOF

It takes ~15 minutes to download the installation images in this workshop environment.

Please run the next oc-mirror command in a tmux session. This will allow you to move on to the next section while oc-mirror downloads ~25 GB of data.

Your workshop environment has configured tmux to be as user-friendly as possible.

Let’s create a tmux session and begin the oc-mirror download. Run the tmux command and see how your terminal is automatically split into two "panes", top and bottom. You can use your mouse to click and change between the top pane and the bottom pane. You can drag the line that divides the panes to resize them.

If you use your scroll wheel, please press q to return to the bottom and continue typing.

tmux

[lab-user@jump ~]$   ### This is the top pane ###



───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
[lab-user@jump ~]$   ### This is the bottom pane ###



[0] 0:bash*                                                                     "ip-10-0-6-23.us-west-" 07:21 01-May-24
        Welcome to tmux - press [Ctrl + b then d] to Disconnect or press [Ctrl + b then h] for additional Help
  Mouse mode has been turned on. Click to select your window/pane. Resize works too. Hold shift when selecting text.

If you get disconnected from tmux, you can re-attach by typing: tmux attach

For more information on tmux, check out the Appendix

Now that tmux is running, choose one of the panes to run the oc-mirror command. oc-mirror is run with an argument to specify the ImageSetConfig file and the output URL.

cd /mnt/low-side-data
oc-mirror --config imageset-config.yaml file:///mnt/low-side-data

Logging to .oc-mirror.log
Creating directory: /mnt/low-side-data/oc-mirror-workspace/src/publish
Creating directory: /mnt/low-side-data/oc-mirror-workspace/src/v2
Creating directory: /mnt/low-side-data/oc-mirror-workspace/src/charts
Creating directory: /mnt/low-side-data/oc-mirror-workspace/src/release-signatures
No metadata detected, creating new workspace

...  a long, uncomfortable pause ...

info: Mirroring completed
Creating archive /mnt/low-side-data/mirror_seq1_000000.tar

Summary

This lab’s instructions helped you downloaded OpenShift’s mirroring and installation tools. You provided credentials (a pull secret) and download instructions (imageset-config.yaml) to oc-mirror.

Because oc-mirror takes a long time to complete, you ran the download command in a tmux pane. You can now proceed to the next section and use the other tmux pane to keep working without waiting for the download to complete.