Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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

  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

      Replace <release_version> with the numerical value of the release you are deploying, using the entire version number, such as 4.19.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

      Example output

      release-x86_64.json
release-aarch64.json
      Copy to Clipboard

      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
      1
      Replace <release_version> with the numerical value of the release you are deploying, using the entire version number, such as 4.19.1.

      Example RPM output

      microshift-release-info-4.18.1.-202511101230.p0.g7dc6a00.assembly.4.18.1.el9.noarch.rpm
      Copy to Clipboard

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

    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

  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

    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

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

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

[customizations.services]
enabled = ["microshift"]
EOF
    Copy to Clipboard

    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.19.1 to download the MicroShift 4.19.1 RPMs.

  2. 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
    Copy to Clipboard

    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.

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

    $ sudo composer-cli blueprints push <microshift_blueprint.toml>
    1
    Copy to Clipboard
    1
    Replace <microshift_blueprint.toml> with the name of your TOML file.

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
    1
    Copy to Clipboard
    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
    Copy to Clipboard

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

    $ sudo composer-cli blueprints depsolve <microshift_blueprint>
    1
    Copy to Clipboard
    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

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

    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

    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

    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

  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

  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

  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

    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

      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
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat