Lab: Prepare a Test Environment for MicroShift

Estimated reading time: 9 minutes.

Objective

Prepare a test environment for air-gaped deployment of MicroShift in both package-based RHEL and RHEL for Edge.

Before you Begin

You need a few machines to perform the hands-on activities in this course.

  • A development machine with RHEL and unrestricted sudo, where you will install Image Builder and RPM-OSTree tools, create test VMs using Libvirt, and also run the OpenShift client to access your MicroShift instances in other machines.

  • A test machine with RHEL and unrestricted sudo, where you will install MicroShift on package-based RHEL.

  • A package server machine already configured to serve DNF repositories for RHEL, Fast Datapath for RHEL, and Red Hat OpenShift Container Platform.

  • A web server machine with RHEL and unrestricted sudo, to host OSTree repositories

  • A mirror registry machine with RHEL and unrestricted sudo, to host a mirror registry for Red Hat OpenShift.

These instructions were tested on RHEL 9.5 but should work with minimal or no change on newer and older RHEL 9.x releases.

If you are using the course environment, you will log in to the workstation VM as the user student with password student. The workstation VM is your development machine. You will start SSH sessions from the workstation VM to the servera VM, which is your web server machine and also your mirror registry machine, using the same user.

Be sure you execute each step on the correct machine. If a step is not explicit about the machine it should be performed, it is using the same machine as its previous step.

In the course environment, the classroom VM, with the materials alias, is your package server machine but you are not expected to start SSH sessions nor perform any activity on it.

It should be possible to perform all activities in this course using a free Red Hat Developers free subscrition, which gives you access to installation media, RPM packages, and container images for RHEL and Red Hat OpenShift. If you ignore the requirements for air-gaped installation of MicroShift, you could use a single RHEL VM and adapt the steps to your own environment.

Instructions

  1. Configure your web server machine with a mirror registry for Red Hat OpenShift.

    These steps are required for all kinds of MicroShift deployment, be they on package-based or image-based, if you are performing air-gaped deployments.

    1. The mirror registry for OpenShift runs as a local container, so install Podman and the Linux container tools.

      $ sudo dnf install container-tools
...
Complete!

    2. Allow remote access to the mirror registry on the system firewall.

      $ sudo firewall-cmd --add-port=8443/tcp --permanent
success
$ sudo firewall-cmd --reload
success

    3. Download the installer for mirror registry for Red Hat OpenShift.

      In a connected environment, you would get it from the downloads page of the Red Hat Hybrid Cloud Console, but there is already a copy of the installer in the course environment at http://content.example.com/rhde/rhocp/. 
      $ wget -q http://content.example.com/rhde/rhocp/mirror-registry-amd64.tar.gz

    4. Extract the mirror registry installer in a temporary directory. You may want to keep the directory for later, if you need to uninstall the mirror registry.

      $ mkdir mirror-registry
$ tar xzvf mirror-registry-amd64.tar.gz -C mirror-registry
image-archive.tar
execution-environment.tar
mirror-registry
sqlite3.tar

    5. Run the mirror registry installer.

      $ sudo ./mirror-registry/mirror-registry install -v --quayHostname servera.lab.example.com  --quayRoot /var/quay --initUser microshift --initPassword redhat123
...
INFO[2024-12-19 15:29:40] Quay installed successfully, config data is stored in /var/quay
INFO[2024-12-19 15:29:40] Quay is available at https://servera.lab.example.com:8443 with credentials (microshift, redhat123)

    6. If something goes wrong and you must retry the mirror registry installation, first clean the failed installation using the following command:

      $ sudo ./mirror-registry/mirror-registry uninstall -v --quayRoot /var/quay --autoApprove
...
INFO[2024-12-19 15:25:41] Quay uninstalled successfully

    7. If all is well, you should have three new containers, and three new system services.

      $ sudo podman ps
CONTAINER ID  IMAGE                                         COMMAND     CREATED      STATUS      PORTS                   NAMES
c4fee96c05e0  registry.access.redhat.com/ubi8/pause:8.10-5  infinity    5 hours ago  Up 5 hours  0.0.0.0:8443->8443/tcp  3e6c474403ac-infra
48a7e7a330dc  registry.redhat.io/quay/quay-rhel8:v3.12.2    registry    5 hours ago  Up 5 hours  0.0.0.0:8443->8443/tcp  quay-app
82b8559fcc97  registry.redhat.io/rhel8/redis-6:1-190        run-redis   5 hours ago  Up 5 hours  0.0.0.0:8443->8443/tcp  quay-redis
$ systemctl status quay-app
● quay-app.service - Quay Container
     Loaded: loaded (/etc/systemd/system/quay-app.service; enabled; preset: disabled)
     Active: active (running) since Fri 2024-12-20 09:04:13 EST; 5h 19min ago
...
$ systemctl status quay-redis
● quay-redis.service - Redis Podman Container for Quay
     Loaded: loaded (/etc/systemd/system/quay-redis.service; enabled; preset: disabled)
     Active: active (running) since Fri 2024-12-20 09:04:13 EST; 5h 19min ago
...
...
$ systemctl status quay-pod
● quay-pod.service - Infra Container for Quay
     Loaded: loaded (/etc/systemd/system/quay-pod.service; enabled; preset: disabled)
     Active: active (exited) since Mon 2025-04-28 16:35:15 EDT; 2h 9min ago
   Main PID: 33761 (code=exited, status=0/SUCCESS)
        CPU: 100ms
...

      It is expected that the quay-pod system service runs once and exits.

    8. Publish the CA certificate of the mirror registry on the Apache Web Server, so other machines can download it and connect to the mirror registry without disabling TLS validation.

      $ sudo cp /var/quay/quay-rootCA/rootCA.pem /var/www/html/quay-rootCA.pem

  2. Configure your development machine to access your mirror registry.

    We will install MicroShift with common assumptions of air-gaped environments, where MicroShift should only pull container images that were previously vetted and only from private container registries, which in the course environment is the mirror registry.

    1. Install the RHEL container tools because you need more than just Podman.

      $ sudo dnf install container-tools
...
Complete!

    2. Add the CA certificate of the mirror registry to your system trusted certificates.

      $ wget -q http://servera.lab.example.com/quay-rootCA.pem
$ sudo cp quay-rootCA.pem /etc/pki/ca-trust/source/anchors
$ sudo update-ca-trust

    3. Log in to the mirror registry.

      $ podman login -u microshift -p redhat123 https://servera.lab.example.com:8443
Login Succeeded!

    4. Copy your registry authentication credentials to a pull secret file.

      This file replaces the pull secret of your Red Hat account, that you would use to install OpenShift and MicroShift when connected to the internet.

      $ cp $XDG_RUNTIME_DIR/containers/auth.json mirror-pull-secret
      You will later copy this file to your MicroShift instances, so it is important that it contains only credentials to the mirror registry, and nothing else. If you configured your mirror registry with exactly the same user name and password from the previous step, you can download a sample pull secret file from the course samples repository and just edit the host name of your mirror registry.

    5. Download a file system copy of all required container images from the classroom server.

      When outside of the course environment, follow the instructions from product docs to extract a list of MicroShift release images from the microshift-release-info RPM package and download them to a staging directory. In the course environment, we provide you with a backup of the staging directory to avoid the need for internet access and save on cloud bandwidth fees. 
      $ wget -q http://content.example.com/rhde/oci/microshift-containers.tar.gz
$ tar xzf microshift-containers.tar.gz
$ ls microshift-containers/
lvms4  openshift-release-dev
$ wget -q http://content.example.com/rhde/oci/app-containers.tar.gz
$ tar xzf app-containers.tar.gz
$ ls app-containers
extra-images-list.txt  flozanorht  rhel9  ubi9

  3. Populate the mirror registry with container images required by MicroShift.

    1. Download the MicroShift images upload script. It is based on the script provided by product documentation, with minor edits.

      Please use the copy of the script in the course samples repository as product documentation may change after this course was released.

      $ wget -q https://raw.githubusercontent.com/RedHatQuickCourses/rhde-build-samples/refs/heads/main/sh/upload-microshift.sh

    2. Run the MicroShift images upload script. Check carefully that its output does not indicate any errors.

      $ sh upload-microshift.sh
      OpenShift release images, which are reused by MicroShift, are not identified by a tag. You must refer to them by hash, so they look like different builds of the same openshift-release-dev/ocp-v4.0-art-dev image but they are actually completely different images.

    3. You can check that the upload process worked by listing all images in the mirror registry.

      $ podman search servera.lab.example.com:8443/
NAME                                                                 DESCRIPTION
servera.lab.example.com:8443/lvms4/lvms-rhel9-operator
servera.lab.example.com:8443/openshift-release-dev/ocp-v4.0-art-dev
      The OCI distribution API is very unreliable for searching and listing container images in a container registry. It works here because there are very few images, but may not work in a production private registry with a larger number of images, including a complete set of images for Red Hat OpenShift.

  4. Populate the mirror registry with container images required by sample applications for course activities.

    1. Download the application images upload script. It is very similar to the MicroShift images upload script.

      $ wget -q https://raw.githubusercontent.com/RedHatQuickCourses/rhde-build-samples/refs/heads/main/sh/upload-apps.sh

    2. Run the application images upload script. Check carefully that its output does not indicate any errors.

      $ sh upload-apps.sh
      In production environments, it is not recommended that you mirror images based on floating tags, such as the implicit latest image tag, like we did here. It is recommended that you mirror using non-floating tags or image hashes.

    3. You can check that the upload process worked by listing all images in the mirror registry.

      $ podman search servera.lab.example.com:8443/
NAME                                                                 DESCRIPTION
servera.lab.example.com:8443/lvms4/lvms-rhel9-operator
servera.lab.example.com:8443/openshift-release-dev/ocp-v4.0-art-dev
servera.lab.example.com:8443/rhel9/mysql-80
servera.lab.example.com:8443/flozanorht/php-ubi
servera.lab.example.com:8443/ubi9/ubi

    4. Alternatively, you can open the web GUI of Red Hat Quay at https://servera.lab.example.com:8443/ and browse the images available in your mirror registry.

      The mirror registry for Red Hat OpenShift only supports a subset of the features of Red Hat Quay and it is not configured for reliability and high availability.

  5. Check that your package server machine is already set up with all artifacts required for air-gaped installation of MicroShift. These steps are required for all kinds of MicroShift deployments, be they on package-based or image-based, if you are performing air-gaped deployments.

    In production environments, it is recommended that you deploy Red Hat Satellite to mirror RPM package repositories from Red Hat products, but the course environment uses an Apache Web Server.

    1. Open http://content.example.com/rhel9.5/x86_64/dvd/ in a web browser. This directory is a copy of a RHEL offline installation DVD and contains the baseos and appstreams repositories.

    2. Open http://content.example.com/rhde/rpms/ in a web browser. This directory contains a copy of the Red Hat OpenShift and Fast Datapath for RHEL repositories, created using the reposync command.

You now have your mirror registry machine and your package server machine ready to support the air-gaped deployment of MicroShift in both package-based RHEL and in RHEL for Edge images.

What’s Next

The next chapter features a series of hands-on activities that deploy MicroShift on a RHEL VM and configure unprivileged developer-level access to it.