Chapter 2. Embedding MicroShift in a RHEL for Edge image

Procedure

1. Create an Image Builder configuration file for adding the rhocp-4.13 RPM repository source required to pull MicroShift RPMs by running the following command:

   $ cat > rhocp-4.13.toml <<EOF
   id = "rhocp-4.13"
   name = "Red Hat OpenShift Container Platform 4.13 for RHEL 9"
   type = "yum-baseurl"
   url = "https://cdn.redhat.com/content/dist/layered/rhel9/$(uname -m)/rhocp/4.13/os"
   check_gpg = true
   check_ssl = true
   system = false
   rhsm = true
   EOF

2. Create an Image Builder configuration file for adding the fast-datapath RPM repository by running the following command:

   $ cat > fast-datapath.toml <<EOF
   id = "fast-datapath"
   name = "Fast Datapath for RHEL 9"
   type = "yum-baseurl"
   url = "https://cdn.redhat.com/content/dist/layered/rhel9/$(uname -m)/fast-datapath/os"
   check_gpg = true
   check_ssl = true
   system = false
   rhsm = true
   EOF

3. Add the sources to the Image Builder by running the following commands:

   $ sudo composer-cli sources add rhocp-4.13.toml

   $ sudo composer-cli sources add fast-datapath.toml

Procedure

1. Use the following example to create your blueprint:

   Image Builder blueprint example

   $ cat > minimal-microshift.toml <<EOF
   name = "minimal-microshift"
   
   description = ""
   version = "0.0.1"
   modules = []
   groups = []
   
   [[packages]]
   name = "microshift"
   version = "*"
   
   [[packages]]
   name = "microshift-greenboot" 1
   version = "*"
   
   [customizations.services]
   enabled = ["microshift"]
   EOF

   1

   Optional microshift-greenboot RPM. For more information, read the "Greenboot health check" guide in the "Running Applications" section.

   Note

   The wildcard * in the commands uses the latest MicroShift RPMs. If you need a specific version, substitute the wildcard for the version you want. For example, insert 4.13.1 to download the MicroShift 4.13.1 RPMs.

2. Add the blueprint to the Image Builder by running the following command:

   $ sudo composer-cli blueprints push minimal-microshift.toml

Verification

1. Verify the Image Builder configuration listing only MicroShift packages by running the following command:

   $ sudo composer-cli blueprints depsolve minimal-microshift | grep microshift

   Example output

   blueprint: minimal-microshift v0.0.1
       microshift-greenboot-4.13.1-202305250827.p0.g4105d3b.assembly.4.13.1.el9.noarch
       microshift-networking-4.13.1-202305250827.p0.g4105d3b.assembly.4.13.1.el9.x86_64
       microshift-release-info-4.13.1-202305250827.p0.g4105d3b.assembly.4.13.1.el9.noarch
       microshift-4.13.1-202305250827.p0.g4105d3b.assembly.4.13.1.el9.x86_64
       microshift-selinux-4.13.1-202305250827.p0.g4105d3b.assembly.4.13.1.el9.noarch

2. Optional: Verify the Image Builder configuration listing all components to be installed by running the following command:

   $ sudo composer-cli blueprints depsolve minimal-microshift

Procedure

1. Start an ostree container image build by running the following command:

   $ BUILDID=$(sudo composer-cli compose start-ostree --ref "rhel/9/$(uname -m)/edge" minimal-microshift edge-container | awk '{print $2}')

   This command also returns the identification (ID) of the build for monitoring.

2. You can check the status of the build periodically by running the following command:

   $ sudo composer-cli compose status

   Example output of a running build

   ID                                     Status     Time                      Blueprint            Version   Type               Size
   cc3377ec-4643-4483-b0e7-6b0ad0ae6332   RUNNING    Wed Jun 7 12:26:23 2023   minimal-microshift   0.0.1     edge-container

   Example output of a completed build

   ID                                     Status     Time                      Blueprint            Version   Type               Size
   cc3377ec-4643-4483-b0e7-6b0ad0ae6332   FINISHED   Wed Jun 7 12:32:37 2023   minimal-microshift   0.0.1     edge-container

   Note

   You can use the watch command to monitor your build if you are familiar with how to start and stop it.

3. Download the container image using the ID and get the image ready for use by running the following command:

   $ sudo composer-cli compose image ${BUILDID}

4. Change the ownership of the downloaded container image to the current user by running the following command:

   $ sudo chown $(whoami). ${BUILDID}-container.tar

5. Add read permissions for the current user to the image by running the following command:

   $ sudo chmod a+r ${BUILDID}-container.tar

6. Bootstrap a server on port 8085 for the ostree container image to be consumed by the ISO build by completing the following steps:

   1. Get the IMAGEID variable result by running the following command:

      $ IMAGEID=$(cat < "./${BUILDID}-container.tar" | sudo podman load | grep -o -P '(?<=sha256[@:])[a-z0-9]*')

   2. Use the IMAGEID variable result to execute the podman command step by running the following command:

      $ sudo podman run -d --name=minimal-microshift-server -p 8085:8080 ${IMAGEID}

      This command also returns the ID of the container saved in the IMAGEID variable for monitoring.

7. Generate the installer blueprint file by running the following command:

   $ cat > microshift-installer.toml <<EOF
   name = "microshift-installer"
   
   description = ""
   version = "0.0.0"
   modules = []
   groups = []
   packages = []
   EOF

1. Add the blueprint to the Image Builder by running the following command:

   $ sudo composer-cli blueprints push microshift-installer.toml

2. Start the ostree ISO build by running the following command:

   $ BUILDID=$(sudo composer-cli compose start-ostree --url http://localhost:8085/repo/ --ref "rhel/9/$(uname -m)/edge" microshift-installer edge-installer | awk '{print $2}')

   This command also returns the identification (ID) of the build for monitoring.

3. You can check the status of the build periodically by running the following command:

   $ sudo composer-cli compose status

   Example output for a running build

   ID                                     Status     Time                      Blueprint              Version   Type               Size
   c793c24f-ca2c-4c79-b5b7-ba36f5078e8d   RUNNING    Wed Jun 7 13:22:20 2023   microshift-installer   0.0.0     edge-installer

   Example output for a completed build

   ID                                     Status     Time                      Blueprint              Version   Type               Size
   c793c24f-ca2c-4c79-b5b7-ba36f5078e8d   FINISHED   Wed Jun 7 13:34:49 2023   microshift-installer   0.0.0     edge-installer

1. Download the ISO using the ID by running the following command:

   $ sudo composer-cli compose image ${BUILDID}

2. Change the ownership of the downloaded container image to the current user by running the following command:

   $ sudo chown $(whoami). ${BUILDID}-installer.iso

3. Add read permissions for the current user to the image by running the following command:

   $ sudo chmod a+r ${BUILDID}-installer.iso

Prerequisites

1. You have created an RHEL for Edge Installer (ISO) image containing your RHEL for Edge commit with MicroShift.

   1. This requirement includes the steps of composing an RFE Container image, creating the RFE Installer blueprint, starting the RFE container, and composing the RFE Installer image.

2. Create a Kickstart file or use an existing one. In the Kickstart file, you must include:

   1. Detailed instructions about how to create a user.
   2. How to fetch and deploy the RHEL for Edge image.

Procedure

1. In the main section of the Kickstart file, update the setup of the filesystem such that it contains an LVM volume group called rhel with at least 10GB system root. Leave free space for the LVMS CSI driver to use for storing the data for your workloads.

   Example kickstart snippet for configuring the filesystem

   # Partition disk such that it contains an LVM volume group called `rhel` with a
   # 10GB+ system root but leaving free space for the LVMS CSI driver for storing data.
   #
   # For example, a 20GB disk would be partitioned in the following way:
   #
   # NAME          MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
   # sda             8:0    0  20G  0 disk
   # ├─sda1          8:1    0 200M  0 part /boot/efi
   # ├─sda1          8:1    0 800M  0 part /boot
   # └─sda2          8:2    0  19G  0 part
   #  └─rhel-root  253:0    0  10G  0 lvm  /sysroot
   #
   ostreesetup --nogpg --osname=rhel --remote=edge \
   --url=file:///run/install/repo/ostree/repo --ref=rhel/<RHEL VERSION NUMBER>/x86_64/edge
   zerombr
   clearpart --all --initlabel
   part /boot/efi --fstype=efi --size=200
   part /boot --fstype=xfs --asprimary --size=800
   # Uncomment this line to add a SWAP partition of the recommended size
   #part swap --fstype=swap --recommended
   part pv.01 --grow
   volgroup rhel pv.01
   logvol / --vgname=rhel --fstype=xfs --size=10000 --name=root
   # To add users, use a line such as the following
   user --name=<YOUR_USER_NAME> \
   --password=<YOUR_HASHED_PASSWORD> \
   --iscrypted --groups=<YOUR_USER_GROUPS>

2. In the %post section of the Kickstart file, add your pull secret and the mandatory firewall rules.

   Example Kickstart snippet for adding the pull secret and firewall rules

   %post --log=/var/log/anaconda/post-install.log --erroronfail
   
   # Add the pull secret to CRI-O and set root user-only read/write permissions
   cat > /etc/crio/openshift-pull-secret << EOF
   YOUR_OPENSHIFT_PULL_SECRET_HERE
   EOF
   chmod 600 /etc/crio/openshift-pull-secret
   
   # Configure the firewall with the mandatory rules for MicroShift
   firewall-offline-cmd --zone=trusted --add-source=10.42.0.0/16
   firewall-offline-cmd --zone=trusted --add-source=169.254.169.1
   
   %end

3. Install the mkksiso tool by running the following command:

   $ sudo yum install -y lorax

4. Update the Kickstart file in the ISO with your new Kickstart file by running the following command:

   $ sudo mkksiso <your_kickstart>.ks <your_installer>.iso <updated_installer>.iso