USHIFT-4304: Rework image mode documentation for source builds

docs/config/Containerfile.bootc-rhel9

@@ -1,6 +1,6 @@
-FROM registry.redhat.io/rhel9-eus/rhel-9.6-bootc:9.6
+FROM registry.redhat.io/rhel9-eus/rhel-9.8-bootc:9.8
 
-ARG USHIFT_VER=4.18
+ARG USHIFT_VER=4.22
 # hadolint ignore=SC1091
 RUN . /etc/os-release && dnf upgrade -y --releasever="${VERSION_ID}" && \
     dnf config-manager \

docs/config/Containerfile.bootc-source-rhel9

@@ -0,0 +1,84 @@
+FROM registry.redhat.io/rhel9-eus/rhel-9.8-bootc:9.8
+
+# URL of the OpenShift "dependencies" repository that provides the MicroShift
+# runtime dependencies which are NOT part of base RHEL: cri-o, cri-tools,
+# openshift-clients and openvswitch. The version of these packages must match
+# the MicroShift source being built.
+#
+# The default below tracks the current pre-release development stream. For the
+# authoritative value matching the current source tree, see the
+# RHOCP_MINOR_Y_BETA variable in test/bin/common_versions.sh. When building a
+# MicroShift version that is already released through the 'rhocp' stream, replace
+# this repository with the matching 'rhocp-<ver>-for-rhel-9-$(uname -m)-rpms' and
+# 'fast-datapath-for-rhel-9-$(uname -m)-rpms' repositories from your Red Hat
+# subscription instead (see docs/config/Containerfile.bootc-rhel9).
+#
+# NOTE: the URL is architecture specific. Override it with '--build-arg' when
+# building for aarch64 (replace 'x86_64' with 'aarch64').
+ARG DEPS_REPO_URL=https://mirror.openshift.com/pub/openshift-v5/x86_64/dependencies/rpms/5.0-el9-beta
+
+# Copy the locally built MicroShift RPM repository (the RPMs produced by
+# 'make rpm' together with the 'repodata' created by 'createrepo_c') into the
+# image. The build context must be the directory that contains them.
+COPY . /tmp/microshift-local
+
+# Configure the local source RPM repository, then install MicroShift built from
+# source. Its dependencies are resolved from the base RHEL repositories (via the
+# host subscription) and from the OpenShift dependencies repository above.
+RUN cat > /etc/yum.repos.d/microshift-local.repo <<'EOF'
+[microshift-local]
+name=MicroShift RPMs built from source
+baseurl=file:///tmp/microshift-local
+enabled=1
+gpgcheck=0
+EOF
+
+# hadolint ignore=SC1091,DL3059
+RUN . /etc/os-release && dnf upgrade -y --releasever="${VERSION_ID}" && \
+    dnf install -y \
+        --repofrompath="openshift-deps,${DEPS_REPO_URL}" \
+        --setopt=openshift-deps.gpgcheck=0 \
+        firewalld jq microshift microshift-release-info && \
+    systemctl enable microshift && \
+    rm -f /etc/yum.repos.d/microshift-local.repo && \
+    rm -rf /tmp/microshift-local && \
+    dnf clean all
+
+# Create a default 'redhat' user with the specified password.
+# Add it to the 'wheel' group to allow for running sudo commands.
+# The password is passed via a build secret to avoid exposing it in image metadata.
+# hadolint ignore=DL4006
+RUN --mount=type=secret,id=user_passwd \
+    if [ ! -f /run/secrets/user_passwd ]; then \
+        echo "user_passwd secret is required" && exit 1; \
+    fi && \
+    useradd -m -d /var/home/redhat -G wheel redhat && \
+    echo "redhat:$(cat /run/secrets/user_passwd)" | chpasswd
+
+# Mandatory firewall configuration
+RUN firewall-offline-cmd --zone=public --add-port=22/tcp && \
+    firewall-offline-cmd --zone=trusted --add-source=10.42.0.0/16 && \
+    firewall-offline-cmd --zone=trusted --add-source=169.254.169.1 && \
+    firewall-offline-cmd --zone=trusted --add-source=fd01::/48
+    # Application-specific firewall configuration
+RUN firewall-offline-cmd --zone=public --add-port=80/tcp && \
+    firewall-offline-cmd --zone=public --add-port=443/tcp && \
+    firewall-offline-cmd --zone=public --add-port=30000-32767/tcp && \
+    firewall-offline-cmd --zone=public --add-port=30000-32767/udp
+
+# Create a systemd unit to recursively make the root filesystem subtree
+# shared as required by OVN images
+RUN cat > /usr/lib/systemd/system/microshift-make-rshared.service <<'EOF'
+[Unit]
+Description=Make root filesystem shared
+Before=microshift.service
+ConditionVirtualization=container
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/mount --make-rshared /
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# hadolint ignore=DL3059
+RUN systemctl enable microshift-make-rshared.service

docs/contributor/image_mode.md

@@ -1,24 +1,28 @@
 # Image Mode for MicroShift Contributors
 
-Follow the instructions in [Image Mode for MicroShift Users](../user/image_mode.md)
-to create a bootable container image, store this image in a remote registry and
-use it for installing a new RHEL operating system.
+Follow the instructions in [Image Mode for MicroShift (from source)](../user/image_mode.md)
+to build a `bootc` image containing MicroShift built from source.
 
-This document demonstrates how to run a `bootc` image using `podman`.
+This document demonstrates how to run that `bootc` image directly using `podman`,
+which is the fastest way to exercise a source build without installing it on a
+host.
 
-> **NOTE**:<br>
+> **NOTE**:  
+>
 > Use the `podman` approach only for development purposes to benefit from
 > the fast turnaround times it allows. Do not use it for production use cases.
 
 The procedures described below require the following setup:
-* A `RHEL 9.6 host` with an active Red Hat subscription for building MicroShift `bootc`
+
+- A `RHEL 9.8 host` with an active Red Hat subscription for building MicroShift `bootc`
 images and running containers
-* A `remote registry` (e.g. `quay.io`) for storing and accessing `bootc` images
+- A `remote registry` (e.g. `quay.io`) for storing and accessing `bootc` images
+
+
 
 ## Run MicroShift Bootc Image
 
-Log into the `RHEL 9.6 host` using the user credentials that have SUDO
-permissions configured.
+Log into the `RHEL 9.8 host` using the user credentials that have `sudo` permissions configured.
 
 ### Configure CNI
 
@@ -32,12 +36,12 @@ kernel versions are different.
 
 ```bash
 $ find /lib/modules/$(uname -r) -name "openvswitch*"
-/lib/modules/6.9.9-200.fc40.x86_64/kernel/net/openvswitch
-/lib/modules/6.9.9-200.fc40.x86_64/kernel/net/openvswitch/openvswitch.ko.xz
+/lib/modules/5.14.0-687.34.1.el9_8.x86_64/kernel/net/openvswitch
+/lib/modules/5.14.0-687.34.1.el9_8.x86_64/kernel/net/openvswitch/openvswitch.ko.xz
 
-$ IMAGE_NAME=microshift-4.18-bootc
+$ IMAGE_NAME=microshift-source-bootc
 $ sudo podman inspect "${IMAGE_NAME}" | grep kernel-core
-        "created_by": "kernel-core-5.14.0-427.26.1.el9_4.x86_64"
+        "created_by": "kernel-core-5.14.0-687.39.1.el9_8.x86_64"
 ```
 
 When a `bootc` image is started as a container, it uses the host kernel, which is
@@ -96,19 +100,22 @@ the next section.
 > sudo rm -f "${VGFILE}"
 > ```
 
+
+
 ### Run Container
 
 Run the following commands to start the MicroShift `bootc` image in an interactive
 terminal session.
 
 The host shares the following configuration with the container:
-* The `openvswitch` kernel module to be used by the Open vSwitch service
-* A pull secret file for downloading the required OpenShift container images
-* Host container storage for reusing available container images
+
+- The `openvswitch` kernel module to be used by the Open vSwitch service
+- A pull secret file for downloading the required OpenShift container images
+- Host container storage for reusing available container images
 
 ```bash
 PULL_SECRET=~/.pull-secret.json
-IMAGE_NAME=microshift-4.18-bootc
+IMAGE_NAME=microshift-source-bootc
 
 sudo modprobe openvswitch
 sudo podman run --rm -it --privileged \
@@ -141,44 +148,56 @@ watch sudo oc get pods -A \
 
 > Run the `sudo shutdown now` command to stop the container.
 
+
+
 ## Appendix A: Multi-Architecture Image Build
 
 It is often convenient to build multi-architecture container images and store
 them under the same registry URL using manifest lists.
 
 > See [podman-manifest](https://docs.podman.io/en/latest/markdown/podman-manifest.1.html) for more information.
 
-The [Build Image](#build-image) procedure needs to be adjusted in the following
-manner to create multi-architecture images.
+The [Build a MicroShift bootc image from source](../user/image_mode.md#build-a-microshift-bootc-image-from-source)
+procedure needs to be adjusted in the following manner to create
+multi-architecture images.
 
 ```bash
 PULL_SECRET=~/.pull-secret.json
 USER_PASSWD="<your_redhat_user_password>"
 IMAGE_ARCH=amd64 # Use amd64 or arm64 depending on the current platform
 IMAGE_PLATFORM="linux/${IMAGE_ARCH}"
-IMAGE_NAME="microshift-4.18-bootc:linux-${IMAGE_ARCH}"
-
+IMAGE_NAME="microshift-source-bootc:linux-${IMAGE_ARCH}"
+
+# The MicroShift RPMs must have been built for ${IMAGE_ARCH} and published to the
+# local repository first. The OpenShift dependencies repository is architecture
+# specific and uses RPM arch names (x86_64 / aarch64) rather than the amd64 /
+# arm64 names, so derive DEPS_REPO_URL from ${IMAGE_ARCH} and pass it explicitly.
+DEPS_ARCH=$([ "${IMAGE_ARCH}" = "arm64" ] && echo aarch64 || echo x86_64)
+DEPS_REPO_URL="https://mirror.openshift.com/pub/openshift-v5/${DEPS_ARCH}/dependencies/rpms/5.0-el9-beta"
 sudo podman build --authfile "${PULL_SECRET}" -t "${IMAGE_NAME}" \
     --platform "${IMAGE_PLATFORM}" \
-    --build-arg USER_PASSWD="${USER_PASSWD}" \
-    -f Containerfile
+    --secret id=user_passwd,env=USER_PASSWD \
+    --build-arg DEPS_REPO_URL="${DEPS_REPO_URL}" \
+    -f docs/config/Containerfile.bootc-source-rhel9 \
+    _output/rpmbuild/RPMS
 ```
 
-Verify that the local MicroShift 4.18 `bootc` image was created for the specified
+Verify that the local MicroShift `bootc` image was created for the specified
 platform.
 
 ```bash
 $ sudo podman images "${IMAGE_NAME}"
-REPOSITORY                       TAG          IMAGE ID      CREATED         SIZE
-localhost/microshift-4.18-bootc  linux-amd64  3f7e136fccb5  13 minutes ago  2.19 GB
+REPOSITORY                          TAG          IMAGE ID      CREATED         SIZE
+localhost/microshift-source-bootc   linux-amd64  3f7e136fccb5  13 minutes ago  2.89 GB
 ```
 
 Repeat the procedure on the other platform (i.e. `arm64`) and proceed by publishing
 the platform-specific `amd64` and `arm64` images to the remote registry as described
-in the [Publish Image](#publish-image) section.
+in the openshift-docs [Installing and publishing a bootc image to a registry](https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/latest/html/installing_with_image_mode_for_rhel/microshift-install-bootc-image)
+section.
 
 > Cross-platform `podman` builds are not in the scope of this document. Log into
-> the RHEL 9.6 host running on the appropriate architecture to perform the container
+> the RHEL 9.8 host running on the appropriate architecture to perform the container
 > image builds and publish the platform-specific image to the remote registry.
 
 Finally, create a manifest containing the platform-specific image references
@@ -190,7 +209,7 @@ and publish it to the remote registry.
 ```bash
 REGISTRY_URL=quay.io
 REGISTRY_ORG=myorg/mypath
-BASE_NAME=microshift-4.18-bootc
+BASE_NAME=microshift-source-bootc
 MANIFEST_NAME="${BASE_NAME}:latest"
 
 sudo podman manifest create -a "localhost/${MANIFEST_NAME}" \
@@ -216,7 +235,7 @@ $ sudo podman manifest inspect \
 ```
 
 It is now possible to access images using the manifest name with the `latest` tag
-(e.g. `quay.io/myorg/mypath/microshift-4.18-bootc:latest`). The image for the
+(e.g. `quay.io/myorg/mypath/microshift-source-bootc:latest`). The image for the
 current platform will automatically be pulled from the registry if it is part of
 the manifest list.
 
@@ -225,11 +244,12 @@ the manifest list.
 Refer to RHEL documentation for generic instructions on upgrading `rpm-ostree`
 systems to Image Mode. The upgrade process should be planned carefully considering
 the following guidelines:
-* Follow instructions in RHEL documentation for converting `rpm-ostree` blueprints to
-  Image Mode container files
-* Consider using [rpm-ostree compose container-encapsulate](https://coreos.github.io/rpm-ostree/container/#converting-ostree-commits-to-new-base-images)
-  to experiment with Image Mode based on the existing `ostree` commits
-* Invest in defining a proper container build pipeline for fully adopting Image Mode
+
+- Follow instructions in RHEL documentation for converting `rpm-ostree` blueprints to
+Image Mode container files
+- Consider using [rpm-ostree compose container-encapsulate](https://coreos.github.io/rpm-ostree/container/#converting-ostree-commits-to-new-base-images)
+to experiment with Image Mode based on the existing `ostree` commits
+- Invest in defining a proper container build pipeline for fully adopting Image Mode
 
 If reinstalling MicroShift devices from scratch is not an option, read the remainder
 of this section that outlines the upgrade details specific to MicroShift.
@@ -262,3 +282,5 @@ ExecStartPre=/bin/sh -c '/bin/getent group hugetlbfs >/dev/null || groupadd -r h
 ExecStartPre=/sbin/usermod -a -G hugetlbfs openvswitch
 ExecStartPre=/bin/chown -Rhv openvswitch. /etc/openvswitch
 EOF
+```
+

docs/contributor/layered_product_ci.md

@@ -14,22 +14,22 @@ can be conducted manually or integrated into the package CI/CD processes. See
 
 ## Build and Publish MicroShift Container Image
 
-Follow the instructions in the [Build Image](./image_mode.md#build-image) section
-to implement the MicroShift container image layer build procedure.
+Follow the openshift-docs [Installing and publishing a bootc image to a registry](https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/latest/html/installing_with_image_mode_for_rhel/microshift-install-bootc-image)
+instructions to implement the MicroShift container image layer build procedure.
 
 > Prebuilt MicroShift bootc container images are not currently available for
 > download.
 
 Customize the `Containerfile` file according to the requirements of the layered
 product to be tested. A typical customization would be to select a custom version
 of MicroShift, which may also include pre-released ones that are published at
-[OpenShift Mirror](mirror.openshift.com).
+[OpenShift Mirror](https://mirror.openshift.com).
 
 > For a given MicroShift `4.y` version, it is always recommended to use the
 > production builds of MicroShift RPMs as soon as they are available at the
 > `rhocp-4.y-for-rhel-9-$(uname -m)-rpms` repository.
 > Otherwise, use pre-released engineering or release candidate packages from
-> [OpenShift Mirror](mirror.openshift.com).
+> [OpenShift Mirror](https://mirror.openshift.com).
 
 **Example: MicroShift 4.17 Engineering Candidate Packages (fragment)**
 
@@ -87,13 +87,13 @@ RUN dnf install -y firewalld microshift && \
     dnf clean all
 ```
 
-Finally, follow the instructions in the [Publish Image](./image_mode.md#publish-image)
-section to push the MicroShift images to a container registry.
+Finally, follow the same openshift-docs [Installing and publishing a bootc image to a registry](https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/latest/html/installing_with_image_mode_for_rhel/microshift-install-bootc-image)
+instructions to push the MicroShift images to a container registry.
 
 ## Build and Publish Layered Product Container Image
 
-Follow the instructions in the [Build Image](./image_mode.md#build-image) section
-to implement the Layered Product container image layer build procedure.
+Follow the openshift-docs [Installing and publishing a bootc image to a registry](https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/latest/html/installing_with_image_mode_for_rhel/microshift-install-bootc-image)
+instructions to implement the Layered Product container image layer build procedure.
 
 Customize the `Containerfile` file according to the requirements of the layered
 product to be tested. A typical customization would be to select a custom version
@@ -113,8 +113,8 @@ RUN dnf install -y microshift-gitops && \
 > The `FROM` statement should be updated to denote a valid reference to the base
 > MicroShift container image.
 
-Finally, follow the instructions in the [Publish Image](./image_mode.md#publish-image)
-section to push the Layered Product images to a container registry.
+Finally, follow the same openshift-docs [Installing and publishing a bootc image to a registry](https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/latest/html/installing_with_image_mode_for_rhel/microshift-install-bootc-image)
+instructions to push the Layered Product images to a container registry.
 
 ## Run Layered Product Container Image
 

docs/user/README.md

@@ -22,5 +22,5 @@ List of the documents in alphabetical file name order.
 - [How To Configure a Workload with Custom Security Context](./howto_pod_security.md)
 - [MicroShift Mitigation of System Configuration Changes](./howto_sysconf_watch.md)
 - [Running MicroShift Fully Offline](./howto_test_offline.md)
-- [Image Mode for MicroShift Users](./image_mode.md)
+- [Image Mode for MicroShift (from source)](./image_mode.md)
 - [Known Limitations](./known_limitations.md)