USHIFT-4299: Rewrite RHEL for Edge ISO contributor doc

docs/config/microshift-edge.ks

@@ -0,0 +1,66 @@
+lang en_US.UTF-8
+keyboard us
+timezone UTC
+text
+reboot
+
+# Configure network to use DHCP and activate on boot
+network --bootproto=dhcp --device=link --activate --onboot=on
+
+# Partition the disk with hardware-specific boot partitions, adding an LVM
+# volume that contains a 10GB+ system root. The remainder of the volume will
+# be used by the LVMS CSI driver for storing data.
+zerombr
+clearpart --all --initlabel
+reqpart --add-boot
+part pv.01 --grow
+volgroup rhel pv.01
+logvol / --vgname=rhel --fstype=xfs --size=10240 --name=root
+
+# Lock root user account
+rootpw --lock
+
+# Deploy the ostree commit embedded in the edge-installer ISO
+ostreesetup --nogpg --osname=rhel --remote=edge --url=file:///run/install/repo/ostree/repo --ref=rhel/9/x86_64/edge
+
+# Post install configuration
+%post --log=/dev/console --erroronfail
+
+# Create a default redhat user, allowing it to run sudo commands without password
+useradd -m -d /home/redhat -p \$5\$XDVQ6DxT8S5YWLV7\$8f2om5JfjK56v9ofUkUAwZXTxJl3Sqnc9yPnza4xoJ0 redhat
+echo -e 'redhat\tALL=(ALL)\tNOPASSWD: ALL' > /etc/sudoers.d/microshift
+
+# Import Red Hat public keys to allow RPM GPG check (not necessary if a system is registered)
+if ! subscription-manager status >& /dev/null ; then
+   rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-*
+fi
+
+# Make the KUBECONFIG from MicroShift directly available for the root user
+echo -e 'export KUBECONFIG=/var/lib/microshift/resources/kubeadmin/kubeconfig' >> /root/.bash_profile
+
+# Configure systemd journal service to persist logs between boots and limit their size to 1G
+sudo mkdir -p /etc/systemd/journald.conf.d
+cat > /etc/systemd/journald.conf.d/microshift.conf <<EOF
+[Journal]
+Storage=persistent
+SystemMaxUse=1G
+RuntimeMaxUse=1G
+EOF
+
+# Make sure all the Ethernet network interfaces are connected automatically
+# by removing autoconnect option from the configuration files
+find /etc/NetworkManager -name '*.nmconnection' -print0 | while IFS= read -r -d $'\0' file ; do
+    if grep -qE '^type=ethernet' "${file}" ; then
+        sed -i '/autoconnect=.*/d' "${file}"
+    fi
+done
+
+# Work around bootupd not installing the EFI grub.cfg during ostree deployment.
+# Without these files the UEFI firmware loads grubx64.efi but GRUB drops to a
+# shell because it cannot find its configuration.
+if [ -d /boot/efi/EFI/redhat ] && [ -f /usr/lib/bootupd/grub2-static/grub-static-efi.cfg ]; then
+    cp /usr/lib/bootupd/grub2-static/grub-static-efi.cfg /boot/efi/EFI/redhat/grub.cfg
+    cp /boot/grub2/bootuuid.cfg /boot/efi/EFI/redhat/bootuuid.cfg
+fi
+
+%end

docs/contributor/rhel4edge_iso.md

@@ -1,17 +1,24 @@
 # Install MicroShift on RHEL for Edge
 To test MicroShift in a setup similar to the production environment, it is necessary to create a RHEL for Edge ISO installer with all the necessary components preloaded on the image.
 
+The official [Embedding in a RHEL for Edge image](https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/4.22/html/embedding_in_a_rhel_for_edge_image/microshift-embed-in-rpm-ostree) documentation covers the full procedure for building an installer ISO from released MicroShift RPMs. This document describes a modified workflow for building from **locally compiled** RPMs, which is necessary when testing changes that have not been released.
+
 The procedures described in this document require the following setup:
-* A `physical hypervisor host` with the [libvirt](https://libvirt.org/) virtualization platform, to be used for starting virtual machines that run RHEL for Edge OS containing MicroShift binaries
+* A `physical hypervisor host` running RHEL with the [libvirt](https://libvirt.org/) virtualization platform and at least 50GB of free disk space
+  * Packages: `libvirt`, `virt-install`, `virt-viewer`, `qemu-kvm`
 * A `development virtual machine` set up according to the [MicroShift Development Environment](./devenv_setup.md) instructions, to be used for building a RHEL for Edge ISO installer
+  * An active RHEL subscription is required for building images
 
 ## Build RHEL for Edge Installer ISO
-Log into the `development virtual machine` with the `microshift` user credentials.
 
-Follow the instructions in the [RPM Packages](./devenv_setup.md#rpm-packages) section to create MicroShift RPM packages.
+Log into the `development virtual machine` with the `microshift` user credentials.
 
 ### Prerequisites
-Execute the `scripts/devenv-builder/configure-composer.sh` script to install the tools necessary for building the installer image.
+
+Execute the `scripts/devenv-builder/configure-composer.sh` script to install `osbuild-composer` and its dependencies.
+```bash
+~/microshift/scripts/devenv-builder/configure-composer.sh
+```
 
 Download the OpenShift pull secret from the https://console.redhat.com/openshift/downloads#tool-pull-secret page and save it into the `~/.pull-secret.json` file.
 
@@ -20,17 +27,54 @@ Make sure there is more than 20GB of free disk space necessary for the build art
 ~/microshift/scripts/devenv-builder/cleanup-composer.sh -full
 ```
 
-### Building Installer
-> TODO: The `image-builder/build.sh` script has been deprecated.
-> This section will be rewritten in the context of [USHIFT-4299](https://issues.redhat.com/browse/USHIFT-4299).
+### Build MicroShift RPMs
+
+Follow the instructions in the [RPM Packages](./devenv_setup.md#rpm-packages) section or run:
+```bash
+cd ~/microshift
+make rpm
+```
+
+The RPMs are placed under `_output/rpmbuild/RPMS/`.
+
+### Create a Local RPM Repository
+
+Create a local repository from the built RPMs so that `osbuild-composer` can resolve them as a package source. This replaces the released MicroShift RPMs that the [official procedure](https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/4.22/html/embedding_in_a_rhel_for_edge_image/microshift-embed-in-rpm-ostree#adding-microshift-repos-image-builder_microshift-embed-in-rpm-ostree) obtains from CDN.
+
+```bash
+BUILDDIR=~/microshift/_output/image-builder
+mkdir -p "${BUILDDIR}/microshift-local"
+cp ~/microshift/_output/rpmbuild/RPMS/*/*.rpm "${BUILDDIR}/microshift-local/"
+createrepo "${BUILDDIR}/microshift-local"
+chmod -R a+rX "${BUILDDIR}/microshift-local"
+```
+
+Register it with `osbuild-composer`:
+```bash
+cat <<EOF | sudo tee /tmp/microshift-local.toml
+id = "microshift-local"
+name = "MicroShift Local RPM Repo"
+type = "yum-baseurl"
+url = "file://${BUILDDIR}/microshift-local/"
+check_gpg = false
+check_ssl = false
+system = false
+EOF
+
+sudo composer-cli sources add /tmp/microshift-local.toml
+```
+
+### Build the Image
+
+With the local RPM source registered, follow the official documentation starting from [Adding MicroShift repositories to image builder](https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/4.22/html/embedding_in_a_rhel_for_edge_image/microshift-embed-in-rpm-ostree#adding-microshift-repos-image-builder_microshift-embed-in-rpm-ostree) through [Download the ISO and prepare it for use](https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/4.22/html/embedding_in_a_rhel_for_edge_image/microshift-embed-in-rpm-ostree#microshift-download-iso-prep-for-use_microshift-embed-in-rpm-ostree). The procedure is identical — `osbuild-composer` will resolve `microshift` packages from the local repository instead of CDN.
+
+Use `rhel/9/x86_64/edge` as the ostree ref in all `composer-cli compose start-ostree --ref` commands. This must match the ref in the [`microshift-edge.ks`](../config/microshift-edge.ks) kickstart.
 
 ### Disk Partitioning
-The `kickstart.ks` file is configured to partition the main disk using `Logical Volume Manager` (LVM). Such partitioning is required for the data volume to be utilized by the MicroShift CSI driver and it allows for flexible file system customization if the disk space runs out.
+The [`microshift-edge.ks`](../config/microshift-edge.ks) file is configured to partition the main disk using `Logical Volume Manager` (LVM). Such partitioning is required for the data volume to be utilized by the MicroShift CSI driver and it allows for flexible file system customization if the disk space runs out.
 
 By default, the following partition layout is created and formatted with the `XFS` file system:
-* BIOS boot partition (1MB)
-  * It is required to boot ISO to systems with legacy BIOS while using GPT as the partitioning scheme.
-* EFI partition with EFI file system (200MB)
+* EFI System Partition with FAT file system (600MB)
 * Boot partition is allocated on a 1GB volume
 * The rest of the disk is managed by the `LVM` in a single volume group named `rhel`
   * System root partition is allocated on a 10GB volume (minimal recommended size for a root partition)
@@ -41,63 +85,65 @@ By default, the following partition layout is created and formatted with the `XF
 
 As an example, a 20GB disk is partitioned in the following manner by default.
 ```
-$ lsblk /dev/sda
-NAME          MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
-sda             8:0    0   20G  0 disk
-├─sda1          8:1    0    1M  0 part
-├─sda2          8:2    0  200M  0 part /boot/efi
-├─sda3          8:3    0  800M  0 part /boot
-└─sda4          8:4    0   19G  0 part
+$ lsblk /dev/vda
+NAME          MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
+vda           252:0    0   20G  0 disk
+├─vda1        252:1    0  600M  0 part /boot/efi
+├─vda2        252:2    0    1G  0 part /boot
+└─vda3        252:3    0 18.4G  0 part
   └─rhel-root 253:0    0   10G  0 lvm  /sysroot
 
 $ sudo vgdisplay -s
-  "rhel" <19.02 GiB [10.00 GiB  used / <9.02 GiB free]
+  "rhel" 18.41 GiB [10.00 GiB  used / 8.41 GiB free]
 ```
 
-> Unallocated disk space of 9GB size remains in the `rhel` volume group to be used by the CSI driver.
+> Unallocated disk space of 8GB size remains in the `rhel` volume group to be used by the CSI driver.
 
 ## Install MicroShift for Edge
+
 Log into the `physical hypervisor host` using your user credentials. The remainder of this section describes how to install a virtual machine running RHEL for Edge OS containing MicroShift binaries.
 
-Start by copying the installer image from the `development virtual machine` to the host file system.
+Start by copying the installer image and kickstart from the `development virtual machine` to the host file system. Replace `<dev-vm-ip>` with the IP address of your development VM (run `sudo virsh domifaddr <vm-name>` on the hypervisor to find it).
 ```bash
-sudo scp microshift@microshift-dev:/home/microshift/microshift/_output/image-builder/microshift-installer-*.$(uname -m).iso /var/lib/libvirt/images/
+scp microshift@<dev-vm-ip>:/home/microshift/microshift/_output/image-builder/microshift-installer.$(uname -m).iso ~/
+scp microshift@<dev-vm-ip>:/home/microshift/microshift/docs/config/microshift-edge.ks ~/
 ```
 
-Run the following commands to create a virtual machine using the installer image.
+Run the following commands to create a virtual machine using the installer image. The `--boot uefi` flag is required because the ostree image uses `bootupd` for bootloader management, which only supports UEFI. The `--location` flag extracts the installer kernel from the ISO for direct boot, and `--initrd-inject` embeds the kickstart into the installer initrd.
 ```bash
 VMNAME="microshift-edge"
 NETNAME="default"
-sudo bash -c " \
-cd /var/lib/libvirt/images/ && \
-virt-install \
-    --name ${VMNAME} \
+ISOFILE="${HOME}/microshift-installer.$(uname -m).iso"
+
+sudo virt-install \
+    --name "${VMNAME}" \
     --vcpus 2 \
-    --memory 3072 \
-    --disk path=./${VMNAME}.qcow2,size=20 \
-    --network network=${NETNAME},model=virtio \
+    --memory 4096 \
+    --boot uefi \
+    --disk path="${HOME}/${VMNAME}.qcow2,size=50" \
+    --network network="${NETNAME}",model=virtio \
     --events on_reboot=restart \
-    --cdrom ./microshift-installer-*.$(uname -m).iso \
+    --location "${ISOFILE}" \
+    --initrd-inject "${HOME}/microshift-edge.ks" \
+    --extra-args "inst.ks=file://microshift-edge.ks" \
     --noautoconsole \
-    --wait \
-"
+    --wait
 ```
 
 Watch the OS console to see the progress of the installation, waiting until the machine is rebooted and the login prompt appears.
 
 Note that it may be more convenient to access the machine using SSH. Run the following command to get its IP address and use it to remotely connect to the system.
 ```bash
-sudo virsh domifaddr microshift-edge
+sudo virsh domifaddr "${VMNAME}"
 ```
 
-Log into the system using `redhat:redhat` credentials and run the following commands to configure MicroShift access.
+Log into the system using `redhat:redhat` credentials (as configured in [`microshift-edge.ks`](../config/microshift-edge.ks)) and run the following commands to configure MicroShift access.
 ```bash
 mkdir ~/.kube
 sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig > ~/.kube/config
 ```
 
-Finally, check if MicroShift is up and running by executing `oc` commands.
+Verify that MicroShift is up and running.
 ```bash
-oc get cs
 oc get pods -A
 ```