Chapter 5. Embedding MicroShift applications tutorial The following tutorial gives a detailed example of how to embed applications in a RHEL for Edge image for use in a MicroShift cluster in various environments. 5.1. Embed application RPMs tutorial The following tutorial reviews the MicroShift installation steps and adds a description of the workflow for embedding applications. If you are already familiar with rpm-ostree systems such as Red Hat Enterprise Linux for Edge (RHEL for Edge) and MicroShift, you can go straight to the procedures. 5.1.1. Installation workflow review Embedding applications requires a similar workflow to embedding MicroShift into a RHEL for Edge image. The following image shows how system artifacts such as RPMs, containers, and files are added to a blueprint and used by the image composer to create an ostree commit. The ostree commit then can follow either the ISO path or the repository path to edge devices. The ISO path can be used for disconnected environments, while the repository path is often used in places were the network is usually connected. Embedding MicroShift workflow Reviewing these steps can help you understand the steps needed to embed an application: To embed MicroShift on RHEL for Edge, you added the MicroShift repositories to image builder. You created a blueprint that declared all the RPMs, container images, files and customizations you needed, including the addition of MicroShift. You added the blueprint to image builder and ran a build with the image builder CLI tool ( composer-cli ). This step created rpm-ostree commits, which were used to create the container image. This image contained RHEL for Edge. You added the installer blueprint to image builder to create an rpm-ostree image (ISO) to boot from. This build contained both RHEL for Edge and MicroShift. You downloaded the ISO with MicroShift embedded, prepared it for use, provisioned it, then installed it onto your edge devices. 5.1.2. Embed application RPMs workflow After you have set up a build host that meets the image builder requirements, you can add your application in the form of a directory of manifests to the image. After those steps, the simplest way to embed your application or workload into a new ISO is to create your own RPMs that include the manifests. Your application RPMs contain all of the configuration files describing your deployment. The following "Embedding applications workflow" image shows how Kubernetes application manifests and RPM spec files are combined in a single application RPM build. This build becomes the RPM artifact included in the workflow for embedding MicroShift in an ostree commit. Embedding applications workflow The following procedures use the rpmbuild tool to create a specification file and local repository. The specification file defines how the package is built, moving your application manifests to the correct location inside the RPM package for MicroShift to pick them up. That RPM package is then embedded in the ISO. 5.1.3. Preparing to make application RPMs To build your own RPMs, choose a tool of your choice, such as the rpmbuild tool, and initialize the RPM build tree in your home directory. The following is an example procedure. As long as your RPMs are accessible to image builder, you can use the method you prefer to build the application RPMs. Prerequisites You have set up a Red Hat Enterprise Linux for Edge (RHEL for Edge) 9.4 build host that meets the image builder system requirements. You have root access to the host. Procedure Install the rpmbuild tool and create the yum repository for it by running the following command: USD sudo dnf install rpmdevtools rpmlint yum-utils createrepo Create the file tree you need to build RPM packages by running the following command: USD rpmdev-setuptree Verification List the directories to confirm creation by running the following command: USD ls ~/rpmbuild/ Example output BUILD RPMS SOURCES SPECS SRPMS 5.1.4. Building the RPM package for the application manifests To build your own RPMs, you must create a spec file that adds the application manifests to the RPM package. The following is an example procedure. As long as the application RPMs and other elements needed for image building are accessible to image builder, you can use the method that you prefer. Prerequisites You have set up a Red Hat Enterprise Linux for Edge (RHEL for Edge) 9.4 build host that meets the image builder system requirements. You have root access to the host. The file tree required to build RPM packages was created. Procedure In the ~/rpmbuild/SPECS directory, create a file such as <application_workload_manifests.spec> using the following template: Example spec file Name: <application_workload_manifests> Version: 0.0.1 Release: 1%{?dist} Summary: Adds workload manifests to microshift BuildArch: noarch License: GPL Source0: %{name}-%{version}.tar.gz #Requires: microshift %description Adds workload manifests to microshift %prep %autosetup %install 1 rm -rf USDRPM_BUILD_ROOT mkdir -p USDRPM_BUILD_ROOT/%{_prefix}/lib/microshift/manifests cp -pr ~/manifests USDRPM_BUILD_ROOT/%{_prefix}/lib/microshift/ %clean rm -rf USDRPM_BUILD_ROOT %files %{_prefix}/lib/microshift/manifests/** %changelog * <DDD MM DD YYYY username@domain - V major.minor.patch> - <your_change_log_comment> 1 The %install section creates the target directory inside the RPM package, /usr/lib/microshift/manifests/ and copies the manifests from the source home directory, ~/manifests . Important All of the required YAML files must be in the source home directory ~/manifests , including a kustomize.yaml file if you are using kustomize. Build your RPM package in the ~/rpmbuild/RPMS directory by running the following command: USD rpmbuild -bb ~/rpmbuild/SPECS/<application_workload_manifests.spec> 5.1.5. Adding application RPMs to a blueprint To add application RPMs to a blueprint, you must create a local repository that image builder can use to create the ISO. With this procedure, the required container images for your workload can be pulled over the network. Prerequisites You have root access to the host. Workload or application RPMs exist in the ~/rpmbuild/RPMS directory. Procedure Create a local RPM repository by running the following command: USD createrepo ~/rpmbuild/RPMS/ Give image builder access to the RPM repository by running the following command: USD sudo chmod a+rx ~ Note You must ensure that image builder has all of the necessary permissions to access all of the files needed for image building, or the build cannot proceed. Create the blueprint file, repo-local-rpmbuild.toml using the following template: id = "local-rpm-build" name = "RPMs build locally" type = "yum-baseurl" url = "file://<path>/rpmbuild/RPMS" 1 check_gpg = false check_ssl = false system = false 1 Specify part of the path to create a location that you choose. Use this path in the later commands to set up the repository and copy the RPMs. Add the repository as a source for image builder by running the following command: USD sudo composer-cli sources add repo-local-rpmbuild.toml Add the RPM to your blueprint, by adding the following lines: ... [[packages]] name = "<application_workload_manifests>" 1 version = "*" ... 1 Add the name of your workload here. Push the updated blueprint to image builder by running the following command: USD sudo composer-cli blueprints push repo-local-rpmbuild.toml At this point, you can either run image builder to create the ISO, or embed the container images for offline use. To create the ISO, start image builder by running the following command: USD sudo composer-cli compose start-ostree repo-local-rpmbuild edge-commit In this scenario, the container images are pulled over the network by the edge device during startup. Additional resources Composing a RHEL for Edge image using the image builder CLI Network-based deployments workflow 5.2. Additional resources Embedding applications for offline use Embedding Red Hat build of MicroShift in an RPM-OSTree image Composing, installing, and managing RHEL for Edge images Preparing for image building Meet Red Hat Device Edge with Red Hat build of MicroShift How to create a Linux RPM package Composing a RHEL for Edge image using image builder command-line Image builder system requirements

Commands:
sudo dnf install rpmdevtools rpmlint yum-utils createrepo
rpmdev-setuptree
ls ~/rpmbuild/
BUILD RPMS SOURCES SPECS SRPMS
Name: <application_workload_manifests> Version: 0.0.1 Release: 1%{?dist} Summary: Adds workload manifests to microshift BuildArch: noarch License: GPL Source0: %{name}-%{version}.tar.gz #Requires: microshift %description Adds workload manifests to microshift %prep %autosetup %install 1 rm -rf USDRPM_BUILD_ROOT mkdir -p USDRPM_BUILD_ROOT/%{_prefix}/lib/microshift/manifests cp -pr ~/manifests USDRPM_BUILD_ROOT/%{_prefix}/lib/microshift/ %clean rm -rf USDRPM_BUILD_ROOT %files %{_prefix}/lib/microshift/manifests/** %changelog * <DDD MM DD YYYY username@domain - V major.minor.patch> - <your_change_log_comment>
rpmbuild -bb ~/rpmbuild/SPECS/<application_workload_manifests.spec>
createrepo ~/rpmbuild/RPMS/
sudo chmod a+rx ~
id = "local-rpm-build" name = "RPMs build locally" type = "yum-baseurl" url = "file://<path>/rpmbuild/RPMS" 1 check_gpg = false check_ssl = false system = false
sudo composer-cli sources add repo-local-rpmbuild.toml
... [[packages]] name = "<application_workload_manifests>" 1 version = "*" ...
sudo composer-cli blueprints push repo-local-rpmbuild.toml
sudo composer-cli compose start-ostree repo-local-rpmbuild edge-commit