Chapter 3. Embedding in a RHEL for Edge image for offline use Embedding MicroShift containers in an rpm-ostree commit means that you can run a cluster in air-gapped, disconnected, or offline environments. You can embed Red Hat build of MicroShift containers in a Red Hat Enterprise Linux for Edge (RHEL for Edge) image so that container engines do not need to pull images over a network from a container registry. Workloads can start up immediately without network connectivity. 3.1. Embedding MicroShift containers for offline deployments You can use image builder to create RHEL for Edge images with embedded MicroShift container images. To embed container images, you must add the image references to your image builder blueprint file. Prerequisites You have root-user access to your build host. Your build host meets the image builder system requirements. You installed and set up image builder and the composer-cli tool. You created a RHEL for Edge image blueprint. You installed jq. Procedure Get the exact list of container image references used by the MicroShift version you are deploying. You can either install the microshift-release-info RPM package by following step 2 or download and unpack the RPM by following step 3. To install the microshift-release-info RPM package: Install the microshift-release-info RPM package by running the following command: USD sudo dnf install -y microshift-release-info-<release_version> Replace <release_version> with the numerical value of the release you are deploying, using the entire version number, such as 4.18.1 . List the contents of the /usr/share/microshift/release directory to verify the presence of the release information files by running the following command: USD sudo ls /usr/share/microshift/release Example output release-x86_64.json release-aarch64.json If you installed the microshift-release-info RPM, proceed to step 4. If you did not complete step 2, download and unpack the microshift-release-info RPM without installing it: Download the RPM package by running the following command: USD sudo dnf download microshift-release-info- <release_version> 1 1 Replace <release_version> with the numerical value of the release you are deploying, using the entire version number, such as 4.18.1 . Example RPM output microshift-release-info-4.18.1.-202511101230.p0.g7dc6a00.assembly.4.18.1.el9.noarch.rpm Unpack the RPM package without installing it by running the following command: USD rpm2cpio <my_microshift_release_info> | cpio -idmv 1 ./usr/share/microshift/release/release-aarch64.json ./usr/share/microshift/release/release-x86_64.json 1 Replace <my_microshift_release_info> with the name of the RPM package from the step. Define the location of your JSON file, which contains the container reference information, by running the following command: USD RELEASE_FILE= </path/to/your/release-USD(uname -m).json> 1 1 Replace </path/to/your/release-USD(uname -m).json> with the full path to your JSON file. Be sure to use the file needed for your architecture. Define the location of your TOML file, which contains instructions for building the image, by running the following command: USD BLUEPRINT_FILE= </path/to/your/blueprint.toml> 1 1 Replace </path/to/your/blueprint.toml> with the full path to your TOML file. Generate and then embed the container image references in your blueprint TOML file by running the following command: USD jq -r '.images | .[] | ("[[containers]]\nsource = \"" + . + "\"\n")' "USD{RELEASE_FILE}" >> "USD{BLUEPRINT_FILE}" Example resulting TOML fragment showing container references [[containers]] source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:82cfef91557f9a70cff5a90accba45841a37524e9b93f98a97b20f6b2b69e5db" [[containers]] source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:82cfef91557f9a70cff5a90accba45841a37524e9b93f98a97b20f6b2b69e5db" You can manually embed any container image by adding it to an image builder blueprint file using the following example: Example section for manually embedding container image to a blueprint [[containers]] source = " <my_image_pullspec_with_tag_or_digest> " Replace <my_image_pullspec_with_tag_or_digest> with the exact reference to a container image used by the MicroShift version you are deploying. 3.2. Adding registry authentication to prepare for image building After you have updated the blueprint, you must add authentication for the container registries to build the image with embedded MicroShift containers. To do this, update one of the systemd service files that are part of the Image Builder configuration. Prerequisites You have root-user access to your build host. Your build host meets the Image Builder system requirements. You have installed and set up Image Builder and the composer-cli tool. Note You can create an /etc/osbuild-worker/osbuild-worker.toml directory and configuration file if they do not exist. Procedure Add a pull secret for authenticating to the registry by setting the auth_file_path in the [containers] section of the /etc/osbuild-worker/osbuild-worker.toml configuration file: [containers] auth_file_path = "/etc/osbuild-worker/pull-secret.json" Restart the host to apply configuration changes. 3.3. Build and use the rpm-ostree image for offline deployments You can use image builder to create rpm-ostree system images with embedded MicroShift container images. To embed container images, you must add the image references to your image builder blueprint. You can create the commit and ISO as needed for your use case. Add the prerequisites listed here to the ones that are included in the procedures that follow. 3.3.1. Additional prerequisites for offline deployments You have created and updated a RHEL for Edge image blueprint for offline use. The following procedures use the example of a blueprint created with container images. You must use the updated blueprint you created in the "Embedding MicroShift containers for offline deployments" procedure. You have updated the /etc/osbuild-worker/osbuild-worker.toml configuration file for offline use. Important Replace minimal-microshift.toml in the following procedures with the name of the TOML you updated for offline use, <my_blueprint_name>. 3.3.2. Adding the MicroShift service to a blueprint Adding the MicroShift RPM package to an image builder blueprint enables the build of a RHEL for Edge image with MicroShift embedded. Start with step 1 to create your own minimal blueprint file which results in a faster MicroShift installation. Start with step 2 to use the generated blueprint for installation which includes all the RPM packages and container images. This is a longer installation process, but a faster start up because container references are accessed locally. Important Replace <microshift_blueprint.toml> in the following procedures with the name of the TOML file you are using. Replace <microshift_blueprint> in the following procedures with the name you want to use for your blueprint. Procedure Use the following example to create your own blueprint file: Custom image builder blueprint example cat > <microshift_blueprint.toml> <<EOF 1 name = " <microshift_blueprint> " 2 description = "" version = "0.0.1" modules = [] groups = [] [[packages]] name = "microshift" version = "4.18.1" 3 [customizations.services] enabled = ["microshift"] EOF 1 The name of the TOML file. 2 The name of the blueprint. 3 Substitute the value for the version you want. For example, insert 4.18.1 to download the MicroShift 4.18.1 RPMs. Optional. Use the blueprint installed in the /usr/share/microshift/blueprint directory that is specific to your platform architecture. See the following example snippet for an explanation of the blueprint sections: Generated image builder blueprint example snippet name = "microshift_blueprint" description = "MicroShift 4.17.1 on x86_64 platform" version = "0.0.1" modules = [] groups = [] [[packages]] 1 name = "microshift" version = "4.17.1" ... ... [customizations.services] 2 enabled = ["microshift"] [customizations.firewall] ports = ["22:tcp", "80:tcp", "443:tcp", "5353:udp", "6443:tcp", "30000-32767:tcp", "30000-32767:udp"] ... ... [[containers]] 3 source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:f41e79c17e8b41f1b0a5a32c3e2dd7cd15b8274554d3f1ba12b2598a347475f4" [[containers]] source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:dbc65f1fba7d92b36cf7514cd130fe83a9bd211005ddb23a8dc479e0eea645fd" ... ... EOF 1 References for all non-optional MicroShift RPM packages using the same version compatible with the microshift-release-info RPM. 2 References for automatically enabling MicroShift on system startup and applying default networking settings. 3 References for all non-optional MicroShift container images necessary for an offline deployment. Add the blueprint to the image builder by running the following command: USD sudo composer-cli blueprints push <microshift_blueprint.toml> 1 1 Replace <microshift_blueprint.toml> with the name of your TOML file. Verification Verify the image builder configuration listing only MicroShift packages by running the following command: USD sudo composer-cli blueprints depsolve <microshift_blueprint> | grep microshift 1 1 Replace <microshift_blueprint> with the name of your blueprint. Example output blueprint: microshift_blueprint v0.0.1 microshift-greenboot-4.17.1-202305250827.p0.g4105d3b.assembly.4.17.1.el9.noarch microshift-networking-4.17.1-202305250827.p0.g4105d3b.assembly.4.17.1.el9.x86_64 microshift-release-info-4.17.1-202305250827.p0.g4105d3b.assembly.4.17.1.el9.noarch microshift-4.17.1-202305250827.p0.g4105d3b.assembly.4.17.1.el9.x86_64 microshift-selinux-4.17.1-202305250827.p0.g4105d3b.assembly.4.17.1.el9.noarch Optional: Verify the image builder configuration listing all components to be installed by running the following command: USD sudo composer-cli blueprints depsolve <microshift_blueprint> 1 1 Replace <microshift_blueprint> with the name of your blueprint. 3.3.3. Creating the RHEL for Edge image with image builder Use the following procedure to create the ISO. The RHEL for Edge Installer image pulls the commit from the running container and creates an installable boot ISO with a Kickstart file configured to use the embedded rpm-ostree commit. Prerequisites Your build host meets the image builder system requirements. You installed and set up image builder and the composer-cli tool. You root-user access to your build host. You installed the podman tool. Procedure Start an ostree container image build by running the following command: USD BUILDID=USD(sudo composer-cli compose start-ostree --ref "rhel/{op-system-version-major}/USD(uname -m)/edge" <microshift_blueprint> edge-container | awk '/^Compose/ {print USD2}') 1 1 Replace <microshift_blueprint> with the name of your blueprint. This command also returns the identification (ID) of the build for monitoring. You can check the status of the build periodically by running the following command: USD 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 microshift_blueprint 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 microshift_blueprint 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. Download the container image using the ID and get the image ready for use by running the following command: USD sudo composer-cli compose image USD{BUILDID} Change the ownership of the downloaded container image to the current user by running the following command: USD sudo chown USD(whoami). USD{BUILDID}-container.tar Add read permissions for the current user to the image by running the following command: USD sudo chmod a+r USD{BUILDID}-container.tar Bootstrap a server on port 8085 for the ostree container image to be consumed by the ISO build by completing the following steps: Get the IMAGEID variable result by running the following command: USD IMAGEID=USD(cat < "./USD{BUILDID}-container.tar" | sudo podman load | grep -o -P '(?<=sha256[@:])[a-z0-9]*') Use the IMAGEID variable result to execute the podman command step by running the following command: USD sudo podman run -d --name=minimal-microshift-server -p 8085:8080 USD{IMAGEID} This command also returns the ID of the container saved in the IMAGEID variable for monitoring. 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 3.4. Additional resources Pushing a container to a registry and embedding it into an image Container registry credentials Configuring network settings for fully disconnected hosts Using Operator Lifecycle Manager with MicroShift Creating custom catalogs using the oc-mirror plugin

Commands:
sudo dnf install -y microshift-release-info-<release_version>
sudo ls /usr/share/microshift/release
release-x86_64.json release-aarch64.json
sudo dnf download microshift-release-info- <release_version> 1
microshift-release-info-4.18.1.-202511101230.p0.g7dc6a00.assembly.4.18.1.el9.noarch.rpm
rpm2cpio <my_microshift_release_info> | cpio -idmv 1 ./usr/share/microshift/release/release-aarch64.json ./usr/share/microshift/release/release-x86_64.json
RELEASE_FILE= </path/to/your/release-USD(uname -m).json> 1
BLUEPRINT_FILE= </path/to/your/blueprint.toml> 1
jq -r '.images | .[] | ("[[containers]]\nsource = \"" + . + "\"\n")' "USD{RELEASE_FILE}" >> "USD{BLUEPRINT_FILE}"
[[containers]] source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:82cfef91557f9a70cff5a90accba45841a37524e9b93f98a97b20f6b2b69e5db" [[containers]] source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:82cfef91557f9a70cff5a90accba45841a37524e9b93f98a97b20f6b2b69e5db"
[[containers]] source = " <my_image_pullspec_with_tag_or_digest> "
[containers] auth_file_path = "/etc/osbuild-worker/pull-secret.json"
cat > <microshift_blueprint.toml> <<EOF 1 name = " <microshift_blueprint> " 2 description = "" version = "0.0.1" modules = [] groups = [] [[packages]] name = "microshift" version = "4.18.1" 3 [customizations.services] enabled = ["microshift"] EOF
name = "microshift_blueprint" description = "MicroShift 4.17.1 on x86_64 platform" version = "0.0.1" modules = [] groups = [] [[packages]] 1 name = "microshift" version = "4.17.1" [customizations.services] 2 enabled = ["microshift"] [customizations.firewall] ports = ["22:tcp", "80:tcp", "443:tcp", "5353:udp", "6443:tcp", "30000-32767:tcp", "30000-32767:udp"] [[containers]] 3 source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:f41e79c17e8b41f1b0a5a32c3e2dd7cd15b8274554d3f1ba12b2598a347475f4" [[containers]] source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:dbc65f1fba7d92b36cf7514cd130fe83a9bd211005ddb23a8dc479e0eea645fd" ... EOF
sudo composer-cli blueprints push <microshift_blueprint.toml> 1
sudo composer-cli blueprints depsolve <microshift_blueprint> | grep microshift 1
blueprint: microshift_blueprint v0.0.1 microshift-greenboot-4.17.1-202305250827.p0.g4105d3b.assembly.4.17.1.el9.noarch microshift-networking-4.17.1-202305250827.p0.g4105d3b.assembly.4.17.1.el9.x86_64 microshift-release-info-4.17.1-202305250827.p0.g4105d3b.assembly.4.17.1.el9.noarch microshift-4.17.1-202305250827.p0.g4105d3b.assembly.4.17.1.el9.x86_64 microshift-selinux-4.17.1-202305250827.p0.g4105d3b.assembly.4.17.1.el9.noarch
sudo composer-cli blueprints depsolve <microshift_blueprint> 1
BUILDID=USD(sudo composer-cli compose start-ostree --ref "rhel/{op-system-version-major}/USD(uname -m)/edge" <microshift_blueprint> edge-container | awk '/^Compose/ {print USD2}') 1
sudo composer-cli compose status
ID Status Time Blueprint Version Type Size cc3377ec-4643-4483-b0e7-6b0ad0ae6332 RUNNING Wed Jun 7 12:26:23 2023 microshift_blueprint 0.0.1 edge-container
ID Status Time Blueprint Version Type Size cc3377ec-4643-4483-b0e7-6b0ad0ae6332 FINISHED Wed Jun 7 12:32:37 2023 microshift_blueprint 0.0.1 edge-container
sudo composer-cli compose image USD{BUILDID}
sudo chown USD(whoami). USD{BUILDID}-container.tar
sudo chmod a+r USD{BUILDID}-container.tar
IMAGEID=USD(cat < "./USD{BUILDID}-container.tar" | sudo podman load | grep -o -P '(?<=sha256[@:])[a-z0-9]*')
sudo podman run -d --name=minimal-microshift-server -p 8085:8080 USD{IMAGEID}
cat > microshift-installer.toml <<EOF name = "microshift-installer" description = "" version = "0.0.0" modules = [] groups = [] packages = [] EOF