Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Embedding in a RHEL for Edge image for offline use

You can embed MicroShift in a container by using Red Hat Enterprise Linux (RHEL) for fully offline deployments.

2.1. About offline deployments with RHEL for Edge
Copy link

Embedding MicroShift containers in an rpm-ostree commit means that you can run a node in 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 immediately without network connectivity.

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>

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

      Example output

      release-x86_64.json
release-aarch64.json

      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>

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

      Example RPM output

      microshift-release-info-4.17.1.-202511101230.p0.g7dc6a00.assembly.4.17.1.el9.noarch.rpm

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

      $ rpm2cpio <my_microshift_release_info> | cpio -idmv
./usr/share/microshift/release/release-aarch64.json
./usr/share/microshift/release/release-x86_64.json

      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>

    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>

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

    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"

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

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

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.

Procedure

  1. Create an /etc/osbuild-worker/osbuild-worker.toml directory and configuration file if they do not exist.

  2. 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"
  3. Restart the host to apply configuration changes.

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.

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

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 = "*"

[customizations.services]
enabled = ["microshift"]
EOF

    1
    The name of the TOML file.
    2
    The name of the blueprint.
    Note

    The wildcard * in the commands uses the latest MicroShift RPMs. If you need a specific version, substitute the wildcard for the version you want. For example, insert 4.17.1 to download the MicroShift 4.17.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]]
name = "microshift"
version = "4.17.1"
...
...

[customizations.services]
enabled = ["microshift"]

[customizations.firewall]
ports = ["22:tcp", "80:tcp", "443:tcp", "5353:udp", "6443:tcp", "30000-32767:tcp", "30000-32767:udp"]
...
...

[[containers]]
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

    • [[packages]] name = "microshift": references for all non-optional MicroShift RPM packages using the same version compatible with the microshift-release-info RPM.
    • [customizations.services] enabled = ["microshift"]: references for automatically enabling MicroShift on system startup and applying default networking settings.
    • [[containers]] source = "quay.io/openshift-release-dev/…​: references for all non-optional MicroShift container images necessary for an offline deployment. The SHA depends on the release you are using.

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

    $ sudo composer-cli blueprints push <microshift_blueprint.toml>
    1
    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
    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

  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
    1
    Replace <microshift_blueprint> with the name of your blueprint.

2.4.3. Creating the RHEL for Edge image
Copy link

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 have installed and set up Image Builder and the composer-cli tool.
  • You have root-user access to your build host.
  • You have 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}')

    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

    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.

  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}

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

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

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

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

  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]*')

    2. Use the IMAGEID variable result to run the Podman command step by running the following command: 

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

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

  7. Generate the installation program blueprint file by running the following command: 

    cat > microshift-installer.toml <<EOF
name = "microshift-installer"

description = ""
version = "0.0.0"
modules = []
groups = []
packages = []
EOF
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

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.

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

Legal Notice

Theme

© 2026 Red HatBack to top