From dd707d14bb8399613118e8661b82929f0a06af28 Mon Sep 17 00:00:00 2001 From: "Jonathan H. Cope" Date: Fri, 7 Aug 2026 15:55:18 -0500 Subject: [PATCH 1/3] 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 ``` From 352f1a191036eb9cfdfdfcfbc00176199d017e00 Mon Sep 17 00:00:00 2001 From: "Jonathan H. Cope" Date: Tue, 11 Aug 2026 12:55:52 -0500 Subject: [PATCH 2/3] Apply CodeRabbit suggestions from PR #7161 Auto-applied: - rhel4edge_iso.md:76: Fix filesystem description (not all partitions are XFS) - rhel4edge_iso.md:128: Fix inst.ks URI (file:// -> file:/) - rhel4edge_iso.md:143: Add chmod go-r for kubeconfig Co-Authored-By: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-Authored-By: Claude Opus 4.6 --- docs/contributor/rhel4edge_iso.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/contributor/rhel4edge_iso.md b/docs/contributor/rhel4edge_iso.md index 72f7f9ab01..1420f0ded1 100644 --- a/docs/contributor/rhel4edge_iso.md +++ b/docs/contributor/rhel4edge_iso.md @@ -73,7 +73,7 @@ Use `rhel/9/x86_64/edge` as the ostree ref in all `composer-cli compose start-os ### Disk Partitioning 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: +By default, the following partition layout is created. The `/boot` and root partitions use the `XFS` file system: * 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` @@ -125,7 +125,7 @@ sudo virt-install \ --events on_reboot=restart \ --location "${ISOFILE}" \ --initrd-inject "${HOME}/microshift-edge.ks" \ - --extra-args "inst.ks=file://microshift-edge.ks" \ + --extra-args "inst.ks=file:/microshift-edge.ks" \ --noautoconsole \ --wait ``` @@ -141,6 +141,7 @@ Log into the system using `redhat:redhat` credentials (as configured in [`micros ```bash mkdir ~/.kube sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig > ~/.kube/config +chmod go-r ~/.kube/config ``` Verify that MicroShift is up and running. From 5fcf21d7ba0457908615d98197fab5124b4d4c22 Mon Sep 17 00:00:00 2001 From: "Jonathan H. Cope" Date: Tue, 11 Aug 2026 15:07:56 -0500 Subject: [PATCH 3/3] Fix inst.ks kickstart URI in documentation The file:// (double-slash) form parses the filename as a URI hostname. The correct form is file:/ (single-slash), matching the tested scripts in create-vm.sh and scenario.sh. Co-Authored-By: Claude Opus 4.6 --- docs/user/image_mode.md | 4 ++-- packaging/imagemode/README.md | 2 +- packaging/kickstart/README.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user/image_mode.md b/docs/user/image_mode.md index 264c18b0b7..7c1f02f260 100644 --- a/docs/user/image_mode.md +++ b/docs/user/image_mode.md @@ -218,7 +218,7 @@ sudo virt-install \ --events on_reboot=restart \ --location /var/lib/libvirt/images/rhel-9.6-$(uname -m)-boot.iso \ --initrd-inject kickstart.ks \ - --extra-args "inst.ks=file://kickstart.ks" \ + --extra-args "inst.ks=file:/kickstart.ks" \ --wait ``` @@ -336,7 +336,7 @@ sudo virt-install \ --events on_reboot=restart \ --location /var/lib/libvirt/images/${VMNAME}.iso \ --initrd-inject kickstart.ks \ - --extra-args "inst.ks=file://kickstart.ks" \ + --extra-args "inst.ks=file:/kickstart.ks" \ --wait ``` diff --git a/packaging/imagemode/README.md b/packaging/imagemode/README.md index e824cf1bdf..f207d95fb6 100644 --- a/packaging/imagemode/README.md +++ b/packaging/imagemode/README.md @@ -322,7 +322,7 @@ sudo virt-install \ --location "/var/lib/libvirt/images/${VMNAME}.iso" \ --osinfo detect=on \ --initrd-inject kickstart.ks \ - --extra-args "inst.ks=file://kickstart.ks" \ + --extra-args "inst.ks=file:/kickstart.ks" \ --wait ``` diff --git a/packaging/kickstart/README.md b/packaging/kickstart/README.md index 885d669534..5ffa5fc354 100644 --- a/packaging/kickstart/README.md +++ b/packaging/kickstart/README.md @@ -158,7 +158,7 @@ sudo virt-install \ --events on_reboot=restart \ --location /var/lib/libvirt/images/rhel-9.4-$(uname -m)-boot.iso \ --initrd-inject "${HOME}/kickstart.ks" \ - --extra-args "inst.ks=file://kickstart.ks" \ + --extra-args "inst.ks=file:/kickstart.ks" \ --wait ```