OC-Mirror surprised us again with new abilities

Utilizing ‘oc-mirror’ to mirror RedHat OpenShift version & building the update graph image.

Photo by Lopez Robin on Unsplash

Introduction

In the past few months, RedHat has started to push out to the public a “revamped” CLI tool called “oc-mirror”. This is a very powerful and resourceful tool that can and will allow you to perform tasks that were complicated in the past more simply and efficiently nowadays.

Two months ago I released an article on medium outlining this tool and how to use it to mirror Openshift operators from the different catalogs to a disconnected cluster installation.

Mirroring specific versions of K8S Operators

At the time oc-mirror could even mirror specific versions of operators which beforehand was a painful process due to the way image layering works and how the operator catalog’s index image is used to tag these image layers.

The subject at hand — mirroring ocp version

As said before oc-mirror is a very powerful cli, and I’m here to update you about two features that a colleague of mine showcased in a mutual project of ours.

Shon Paz and I worked on a disconnected environment at a customer’s of ours (we as RedHat employees) which the client has decided on implementing RedHats’ Advanced Cluster Management (aka ACM) with multiple abilities to manage their fleet of clusters. One of the desired abilities was to empower the ACM deployment with RedHat’s OpenShift Update Service (aka OSUS), which comes from the following open-source project:

GitHub - openshift/cincinnati-operator: An operator to manage Cincinnati, the update graph service

ACM based on the Stolostron open-source project connected with a deployment of the OSUS operator works together to supply together the ability to upgrade clusters and manage the process — more on this soon, stay updated on my medium account.

Now let us get straight to work

Prerequisites

• Openshift Container Platform v4.9.xx and above
• A Bastion server based on a RHEL8 operating system (in both environments).
• OC CLI — download link

Using oc-mirror to mirror Openshift versions & creating a graph data for OSUS:

For us to understand the following process we’ll go over an ImageSet example and take it apart into pieces — at the end, the full ImageSet will be added.

1. ImageSet — A config / digest file that oc-mirror uses to fulfill the required task. In this file, you will input what you would like oc-mirror to do (mirror ocp version, mirror operators, and possibly create an update graph).

apiVersion: mirror.openshift.io/v1alpha2
kind: ImageSetConfiguration

2. Apiversion & kind — both are part of how oc-mirror understands this file, its type, and to whom the file is supposed to “talk to”.

3. ArchiveSize — oc-mirror’s output is a .tar archive file. The file contains all of the mirrored content. Sometimes we would like to split the .tar file into smaller-sized files. The archiveSize variable sets the max size for the .tar that’s outputed by the oc-mirror process. — If for any reason you would like to split a large file into smaller (divided) files you would set the variable in the imageSet to the maximum size you would like. e.g — You have mirrored two ocp versions and the total size of your file would normally be approximately 24Gb, but your import process allows for files up to 10Gb size for each file — in this case, you would set the variable for archiveSize to 10.

4. Mirrored Content — If we have a look at our imageSet example, you would see that under the archive size we have a few more pieces of information telling us and oc-mirror what to mirror.
The “tree” goes this way: ‘mirror:’ tells us the action, and ‘platform:’ tells us that we are mirroring the os for openshift (ocp versions), from now on it’s pretty straightforward.

5. Channels & Version — Under the ‘channels:’ line we can see that we have picked the stable-4.10 channel — more on how to choose your update channel & understanding the different channels available.
P.S — Note the chosen channel is for the end release — i.e if you where to upgrade from ocp 4.10.XX in the “stable-4.10” channel to ocp 4.11.XX in the “stable-4.11” channel you will have to enter the channel as follows:

channels:
     - name: stable-4.11

6. Versions — This is a very important step in the process. I advise you to plan your upgrade path before starting the process, We at RedHat supply a simple GUI where you can import all of your clusters’ parameters. Version channel, your initial version, and your target version. After entering all of the parameters in the GUI you will be presented with something similar to this:

This showcases the upgrade path that I’ve planned ahead of time — this lets me control exactly which version/s I would like to use in the case that there are multiple options to conduct the upgrade process.

The other option is to let oc-mirror choose the upgrade path that’s recommended by RedHat with the ImageSet file, you do so just by entering your minVersion (your current version) and your maxVersion (your target version) accordingly.

Let’s get back to the ImageSet — you have two variables, minVersion & maxVersion, If you wish to mirror multiple versions as I’ve shown above do so, on the other hand, if you wish to mirror one specific version set both variables to be the same version number — and now you will successfully mirror a single OCP version.

7. Graph — Mark this as true in the case you would like oc-mirror to create the update-graph image and data for you, if you would not wish for oc-mirror to do so mark this as false.

The following ImageSet configuration tells oc-mirror to mirror the following components:

Ocp version 4.10.18, Ocp version 4.10.37 and create an update graph for the following update path (channel: stable-4.10).

$ cat >./oc-mirror-config.yaml<<EOF
apiVersion: mirror.openshift.io/v1alpha2
kind: ImageSetConfiguration
archiveSize: 50
mirror:
 platform:
   channels:
     - name: stable-4.10
       minVersion: 4.10.18
       maxVersion: 4.10.37
       shortestPath: true
   graph: true
storageConfig:
 local:
   path: ./metadata
EOF

Now let’s start mirroring the needed images to our directory:
* Keep in mind that all of the file names in the oc-mirror command showcased are just an example and can be substituted for any other file name.

$ oc-mirror --config=oc-mirror-config-osus.yaml file://upgrade-from-4.9.33-to-4.10.18
# Output starts here..
Adding graph data
wrote mirroring manifests to upgrade-from-4.9.33-to-4.10.18/oc-mirror-workspace/operators.1667653366/manifests-redhat-operator-indexTo upload local images to a registry, run:	oc adm catalog mirror file://redhat/redhat-operator-index:v4.9 REGISTRY/REPOSITORY

Verification

In order to verify you have successfully created the .tar file containing all of the required images follow these steps:

1. Navigate to the directory you ran the oc-mirror command from
2. Verify that an image set .tar file was created:
3. Use the ls -a or ll commands to “explore your” dir
4. The output should be as follows —
5. In the case your archiveSize is greater than the size of what your mirroring you’ll have only 1 mirror_seq1_000000.tar file.
6. In the case your archiveSize is smaller than the size of what your mirroring you’ll have multiple mirror_seq1_xxxxxx.tar files, each file will be approximately the size you configured for the archiveSize parameter in the config.yaml .

— — — — — — — — — — — — — — — — — — — — — —

Disconnected / Air Gapped Network

— — — — — — — — — — — — — — — — — — — — — —

Import & install in the same way as prior on the “connected bastion” server the oc-mirror cli.
**Bastion server must be rhel v8 and up **

Copy the pull secret for you local registry.

Locate your disconnected registry’s pull secret.
For example: when logging in to the local registry (localhost:5000) a default file will be created in most cases under the following path “/run/user/0/containers/auth.json”
If the file is not located in this path feel free to use the following command.

$ updatedb 
$ locate auth.json

The following pull secret is a token in json format, the password is “encoded” in base64.

Copy the file contents to to following file — IF the dir does not exist please create it.
Make sure that the login credentials are to the registry’s fqdn.

# DIR CREATION = mkdir -p ~/.docker
$ vim ~/.docker/config.json

Now run the command — verify that you have edited it to your openshift version tar file.

$ oc-mirror --from <mirror_tar_sequence>.tar docker://<registry_fqdn>:<port>/openshift/ocp4 --dest-skip-tls

** Whilst mirroring into a docker registry in the case you have multiple mirror_seq1_xxxxxx.tar files than the --from flag should point to the directory containing all of the mirror_seq1_xxxxxx.tar files.

Final words

I hope that this article was useful and has given a new tool in your toolbox for managing ocp clusters. If it’s the case, feel free to give a few claps and to share it with your network. You can also send me some feedback, especially if you find any errors or think of any enhancements.