Embedding in a RHEL for Edge image

Procedure

1. Create the /etc/osbuild-composer/repositories directory by running the following command:

   $ sudo mkdir -p /etc/osbuild-composer/repositories

   Copy to Clipboard Toggle word wrap

2. Copy the /usr/share/osbuild-composer/repositories/rhel-9.4.json file into the /etc/osbuild-composer/repositories directory by running the following command:

   $ sudo cp /usr/share/osbuild-composer/repositories/rhel-9.4.json /etc/osbuild-composer/repositories/rhel-9.4.json

   Copy to Clipboard Toggle word wrap

3. Update the baseos source by modifying the /etc/osbuild-composer/repositories/rhel-9.4.json file with the following values:

   # ...
   "baseurl": "https://cdn.redhat.com/content/eus/rhel<9>/<9.4>//baseos/os", 

   1

   
   # ...

   Copy to Clipboard Toggle word wrap

   1

   Replace <9> with the major RHEL version you are using, and replace <9.4> with the <major.minor> version. Be certain that the RHEL version you choose is compatible with the MicroShift version you are using.

4. Optional. Apply the baseos update by running the following command:

   $ sudo sed -i "s,dist/rhel<9>/<9.4>/$(uname -m)/baseos/,eus/rhel<9>/<9.4>/$(uname -m)/baseos/,g" \
   /etc/osbuild-composer/repositories/rhel-<9.4>.json 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace <9> with the major RHEL version you are using, and replace <9.4> with the <major.minor> version. Be certain that the RHEL version you choose is compatible with the MicroShift version you are using.

5. Update the appstream source by modifying the /etc/osbuild-composer/repositories/rhel-<major.minor>.json file with the following values:

   # ...
   "baseurl": "https://cdn.redhat.com/content/eus/rhel<9>/<9.4>//appstream/os", 

   1

   
   # ...

   Copy to Clipboard Toggle word wrap

   1

   Replace <9> with the major RHEL version you are using, and replace <9.4> with the <major.minor> version. Be certain that the RHEL version you choose is compatible with the MicroShift version you are using.

6. Optional. Apply the appstream update by running the following command:

   $ sudo sed -i "s,dist/rhel<9>/<9.4>/$(uname -m)/appstream/,eus/rhel<9>/<9.4>/$(uname -m)/appstream/,g" \
   /etc/osbuild-composer/repositories/rhel-<9.4>.json 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace <9> with the major RHEL version you are using, and replace <9.4> with the <major.minor> version. Be certain that the RHEL version you choose is compatible with the MicroShift version you are using.

1. Verify the baseos source by running the following command:

   $ sudo composer-cli sources info baseos | grep 'url ='

   Copy to Clipboard Toggle word wrap

   Example output

   url = "https://cdn.redhat.com/content/eus/rhel9/9.4/x86_64/baseos/os"

   Copy to Clipboard Toggle word wrap

2. Verify the appstream source by running the following command:

   $ sudo composer-cli sources info appstream | grep 'url ='

   Copy to Clipboard Toggle word wrap

   Example output

   url = "https://cdn.redhat.com/content/eus/rhel9/9.4/x86_64/appstream/os"

   Copy to Clipboard Toggle word wrap

Procedure

1. Create an image builder configuration file for adding the rhocp-4.18 RPM repository source required to pull MicroShift RPMs by running the following command:

   cat > rhocp-4.18.toml <<EOF
   id = "rhocp-4.18"
   name = "Red Hat OpenShift Container Platform 4.18 for RHEL 9"
   type = "yum-baseurl"
   url = "https://cdn.redhat.com/content/dist/layered/rhel9/$(uname -m)/rhocp/4.18/os"
   check_gpg = true
   check_ssl = true
   system = false
   rhsm = true
   EOF

   Copy to Clipboard Toggle word wrap

2. Create an image builder configuration file for adding the fast-datapath RPM repository by running the following command:

   cat > fast-datapath.toml <<EOF
   id = "fast-datapath"
   name = "Fast Datapath for RHEL 9"
   type = "yum-baseurl"
   url = "https://cdn.redhat.com/content/dist/layered/rhel9/$(uname -m)/fast-datapath/os"
   check_gpg = true
   check_ssl = true
   system = false
   rhsm = true
   EOF

   Copy to Clipboard Toggle word wrap

3. Add the sources to the image builder by running the following commands:

   $ sudo composer-cli sources add rhocp-4.18.toml

   Copy to Clipboard Toggle word wrap

   $ sudo composer-cli sources add fast-datapath.toml

   Copy to Clipboard Toggle word wrap

Procedure

1. 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.18.1 on x86_64 platform"
   version = "0.0.1"
   modules = []
   groups = []
   
   [[packages]] 

   1

   
   name = "microshift"
   version = "4.18.1"
   ...
   ...
   
   [customizations.services] 

   2

   
   enabled = ["microshift"]
   
   [customizations.firewall]
   ports = ["ssh"]
   ...
   ...
   
   [[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

   Copy to Clipboard Toggle word wrap

   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. The SHA depends on the release you are using.

2. Add the blueprint to the image builder by running the following command:

   $ sudo composer-cli blueprints push microshift_blueprint.toml

   Copy to Clipboard Toggle word wrap

Verification

1. Verify the image builder configuration listing only MicroShift packages by running the following command:

   $ sudo composer-cli blueprints depsolve microshift_blueprint | grep microshift

   Copy to Clipboard Toggle word wrap

   Example output

   blueprint: microshift_blueprint v0.0.1
       microshift-release-info-4.18.1-202511250827.p0.g4105d3b.assembly.4.18.1.el9.noarch
       microshift-4.18.1-202511250827.p0.g4105d3b.assembly.4.18.1.el9.x86_64

   Copy to Clipboard Toggle word wrap

2. Optional: Verify the image builder configuration that lists all of the components to be installed by running the following command:

   $ sudo composer-cli blueprints depsolve microshift_blueprint

   Copy to Clipboard Toggle word wrap

Procedure

1. Edit your ostree blueprint by running the following command:

   $ vi <microshift_blueprint.toml> 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace <microshift_blueprint.toml> with the name of the blueprint file used for the MicroShift service.

2. Add the following example text to your blueprint:

   [[packages]] 

   1

   
   name = "<microshift-additional-package-name>" 

   2

   
   version = "*"

   Copy to Clipboard Toggle word wrap

   1

   Include one stanza for each additional service that you want to add.

   2

   Replace <microshift-additional-package-name> with the name the RPM for the service you want to include. For example, microshift-olm.

Next steps

1. Add custom certificate authorities to the blueprint as needed.

2. After you are done adding to your blueprint, you can apply the manifests to an active cluster by building a new ostree system and deploying it on the client:

   • Create the ISO.
   • Add the blueprint and build the ISO.
   • Download the ISO and prepare it for use.
   • Do any provisioning that is needed.

Procedure

1. Start an ostree container image build by running the following command:

   $ BUILDID=$(sudo composer-cli compose start-ostree --ref "rhel/{op-system-version-major}/$(uname -m)/edge" <microshift_blueprint> edge-container | awk '/^Compose/ {print $2}') 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace <microshift_blueprint> with the name of your blueprint.

   This command also returns the identification (ID) of the build for monitoring.

2. You can check the status of the build periodically by running the following command:

   $ sudo composer-cli compose status

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   Note

   You can use the watch command to monitor your build if you are familiar with how to start and stop it.

3. Download the container image using the ID and get the image ready for use by running the following command:

   $ sudo composer-cli compose image ${BUILDID}

   Copy to Clipboard Toggle word wrap

4. Change the ownership of the downloaded container image to the current user by running the following command:

   $ sudo chown $(whoami). ${BUILDID}-container.tar

   Copy to Clipboard Toggle word wrap

5. Add read permissions for the current user to the image by running the following command:

   $ sudo chmod a+r ${BUILDID}-container.tar

   Copy to Clipboard Toggle word wrap

6. Bootstrap a server on port 8085 for the ostree container image to be consumed by the ISO build by completing the following steps:

   1. Get the IMAGEID variable result by running the following command:

      $ IMAGEID=$(cat < "./${BUILDID}-container.tar" | sudo podman load | grep -o -P '(?<=sha256[@:])[a-z0-9]*')

      Copy to Clipboard Toggle word wrap

   2. Use the IMAGEID variable result to execute the podman command step by running the following command:

      $ sudo podman run -d --name=minimal-microshift-server -p 8085:8080 ${IMAGEID}

      Copy to Clipboard Toggle word wrap

      This command also returns the ID of the container saved in the IMAGEID variable for monitoring.

7. 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

   Copy to Clipboard Toggle word wrap

1. Add the blueprint to the image builder by running the following command:

   $ sudo composer-cli blueprints push microshift-installer.toml

   Copy to Clipboard Toggle word wrap

2. Start the ostree ISO build by running the following command:

   $ BUILDID=$(sudo composer-cli compose start-ostree --url http://localhost:8085/repo/ --ref "rhel/9/$(uname -m)/edge" microshift-installer edge-installer | awk '{print $2}')

   Copy to Clipboard Toggle word wrap

   This command also returns the identification (ID) of the build for monitoring.

3. You can check the status of the build periodically by running the following command:

   $ sudo composer-cli compose status

   Copy to Clipboard Toggle word wrap

   Example output for a running build

   ID                                     Status     Time                      Blueprint              Version   Type               Size
   c793c24f-ca2c-4c79-b5b7-ba36f5078e8d   RUNNING    Wed Jun 7 13:22:20 2023   microshift-installer   0.0.0     edge-installer

   Copy to Clipboard Toggle word wrap

   Example output for a completed build

   ID                                     Status     Time                      Blueprint              Version   Type               Size
   c793c24f-ca2c-4c79-b5b7-ba36f5078e8d   FINISHED   Wed Jun 7 13:34:49 2023   microshift-installer   0.0.0     edge-installer

   Copy to Clipboard Toggle word wrap

1. Download the ISO using the ID by running the following command:

   $ sudo composer-cli compose image ${BUILDID}

   Copy to Clipboard Toggle word wrap

2. Change the ownership of the downloaded container image to the current user by running the following command:

   $ sudo chown $(whoami). ${BUILDID}-installer.iso

   Copy to Clipboard Toggle word wrap

3. Add read permissions for the current user to the image by running the following command:

   $ sudo chmod a+r ${BUILDID}-installer.iso

   Copy to Clipboard Toggle word wrap

Procedure

1. 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.

2. To install the microshift-release-info RPM package:

   1. Install the microshift-release-info RPM package by running the following command:

      $ sudo dnf install -y microshift-release-info-<release_version>

      Copy to Clipboard Toggle word wrap

      Replace <release_version> with the numerical value of the release you are deploying, using the entire version number, such as 4.18.1.

   2. List the contents of the /usr/share/microshift/release directory to verify the presence of the release information files by running the following command:

      $ sudo ls /usr/share/microshift/release

      Copy to Clipboard Toggle word wrap

      Example output

      release-x86_64.json
      release-aarch64.json

      Copy to Clipboard Toggle word wrap

      If you installed the microshift-release-info RPM, proceed to step 4.

3. If you did not complete step 2, download and unpack the microshift-release-info RPM without installing it:

   1. Download the RPM package by running the following command:

      $ sudo dnf download microshift-release-info-<release_version> 

      1

      Copy to Clipboard Toggle word wrap

      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

      Copy to Clipboard Toggle word wrap

   2. Unpack the RPM package without installing it by running the following command:

      $ rpm2cpio <my_microshift_release_info> | cpio -idmv 

      1

      
      ./usr/share/microshift/release/release-aarch64.json
      ./usr/share/microshift/release/release-x86_64.json

      Copy to Clipboard Toggle word wrap

      1

      Replace <my_microshift_release_info> with the name of the RPM package from the previous step.

4. Define the location of your JSON file, which contains the container reference information, by running the following command:

   $ RELEASE_FILE=</path/to/your/release-$(uname -m).json> 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace </path/to/your/release-$(uname -m).json> with the full path to your JSON file. Be sure to use the file needed for your architecture.

5. Define the location of your TOML file, which contains instructions for building the image, by running the following command:

   $ BLUEPRINT_FILE=</path/to/your/blueprint.toml> 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace </path/to/your/blueprint.toml> with the full path to your TOML file.

6. Generate and then embed the container image references in your blueprint TOML file by running the following command:

   $  jq -r '.images | .[] | ("[[containers]]\nsource = \"" + . + "\"\n")' "${RELEASE_FILE}" >> "${BLUEPRINT_FILE}"

   Copy to Clipboard Toggle word wrap

   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"

   Copy to Clipboard Toggle word wrap

7. 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>"

   Copy to Clipboard Toggle word wrap

   Replace <my_image_pullspec_with_tag_or_digest> with the exact reference to a container image used by the MicroShift version you are deploying.

Procedure

1. 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"

   Copy to Clipboard Toggle word wrap
2. Restart the host to apply configuration changes.