From 74d2e13bec47ce3f7f65108de87b7f590b861227 Mon Sep 17 00:00:00 2001 From: "Jonathan H. Cope" Date: Fri, 7 Aug 2026 15:55:18 -0500 Subject: [PATCH] USHIFT-4299: Rewrite RHEL for Edge ISO contributor doc The previous version of rhel4edge_iso.md had a TODO placeholder where the build instructions should be, used the deprecated --cdrom approach for VM deployment, and referenced a nonexistent kickstart. This made the document unusable for building and deploying edge-installer ISOs. Rewrite the doc to reference the official Red Hat documentation for the standard image-builder workflow and cover only the local-RPM delta needed when testing unreleased changes. Add a new microshift-edge.ks kickstart for ostree deployments (separate from microshift-starter.ks which remains for DVD installs). Key changes validated by end-to-end testing: - Use --boot uefi (bootupd only generates UEFI bootloader configs) - Use --location + --initrd-inject instead of --cdrom - Add bootupd workaround in %post to install EFI grub.cfg - Update disk partitioning docs to match actual UEFI layout - Store ISO and disk images in ~/ instead of /var/lib/libvirt/images/ Co-Authored-By: Claude Opus 4.6 --- docs/config/microshift-edge.ks | 66 ++++++++++++++++ docs/contributor/rhel4edge_iso.md | 120 +++++++++++++++++++++--------- 2 files changed, 149 insertions(+), 37 deletions(-) create mode 100644 docs/config/microshift-edge.ks diff --git a/docs/config/microshift-edge.ks b/docs/config/microshift-edge.ks new file mode 100644 index 0000000000..ae7bbf5270 --- /dev/null +++ b/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 < 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 < 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 `` with the IP address of your development VM (run `sudo virsh domifaddr ` 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@:/home/microshift/microshift/_output/image-builder/microshift-installer.$(uname -m).iso ~/ +scp microshift@:/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 ```