Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Getting ready to install MicroShift

Red Hat build of MicroShift 4.18

Plan for your MicroShift installation and learn about important configurations

Red Hat OpenShift Documentation Team

Abstract

This document provides information about planning your MicroShift installation and provides details about important configuration processes.

Chapter 1. Getting ready to install MicroShift
Copy link

To use Red Hat Device Edge to compute at the edge, plan your Red Hat Enterprise Linux (RHEL) installation type and your MicroShift configuration.

1.1. System requirements for installing MicroShift
Copy link

These requirements are the minimum system requirements for MicroShift and Red Hat Enterprise Linux (RHEL). Add the system requirements for the workload you plan to run.

For example, if an IoT gateway solution requires 4 GB of RAM, your system needs to have at least 2 GB for RHEL and MicroShift, plus 4 GB for the workloads. Thus, this example deployment requires 6 GB of RAM in total.

Allow for extra capacity for future needs if you are deploying physical devices in remote locations. If you are uncertain of the RAM required, use the maximum RAM capacity that the device can support.

The following conditions must be met before installing MicroShift:

  • A compatible version of RHEL. For more information, see the following link:

  • Hardware or hypervisors that are certified for your RHEL version are strongly recommended. For more information, see the following links:

  • AArch64 or x86_64 system architecture.
  • 2 CPU cores.
  • 2 GB RAM. Installing from the network (UEFI HTTPs or PXE boot) requires 3 GB RAM for RHEL.
  • 10 GB of storage.
  • You have an active MicroShift subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information.
  • If your workload requires Persistent Volumes (PVs), you have a Logical Volume Manager (LVM) Volume Group (VG) with enough free capacity for the workloads.

  • You configure secure access to the system to be able to manage it. For more information, see the following link:

1.2. Compatibility table
Copy link

You must pair a supported version of Red Hat Enterprise Linux (RHEL) with the MicroShift version you are using as described in the following compatibility table.

Red Hat Device Edge release compatibility matrix

Red Hat Enterprise Linux (RHEL) and MicroShift work together as a single solution for device-edge computing. You can update each component separately, but the product versions must be compatible. Supported configurations of Red Hat Device Edge use verified releases for each together as listed in the following table:

Expand
RHEL Version(s)MicroShift VersionSupported MicroShift Version → Version Updates

9.4

4.18

4.18.0 → 4.18.z

9.4

4.17

4.17.1 → 4.17.z, 4.17 → 4.18

9.4

4.16

4.16.0 → 4.16.z, 4.16 → 4.17, 4.16 → 4.18

9.2, 9.3

4.15

4.15.0 → 4.15.z, 4.15 → 4.16 on RHEL 9.4

9.2, 9.3

4.14

4.14.0 → 4.14.z, 4.14 → 4.15, 4.14 → 4.16 on RHEL 9.4

1.3. MicroShift installation tools
Copy link

To use MicroShift, you must already have or plan to install a Red Hat Enterprise Linux (RHEL) type, such as on bare metal, or as a virtual machine (VM) that you provision. Although each use case has different details, each installation of Red Hat Device Edge uses RHEL tools and the OpenShift CLI (oc).

You can use RPMs to install MicroShift on an existing RHEL machine. You do not need other tools unless you are also installing an image-based RHEL system or VM at the same time.

1.4. RHEL installation types
Copy link

Choose the best Red Hat Enterprise Linux (RHEL) installation type based on where you want to run your cluster and what your applications need to do. For the best results, apply the following principles:

  • For every installation target, you must configure both the operating system and MicroShift.
  • Consider your application storage needs, networking for cluster or application access, and your authentication and security requirements.
  • Understand the differences between the RHEL installation types, including the support scope of each, and the tools used.

1.4.1. Using RPMs, or package-based installation
Copy link

This simple installation type uses a basic command to install MicroShift on an existing RHEL machine. Basic CLI tools are required for this installation type.

1.4.2. RHEL image-based installations
Copy link

Image-based installation types involve creating an rpm-ostree-based, immutable version of RHEL that is optimized for edge deployment.

  • RHEL for Edge can be deployed to the edge in production environments. You can use this installation type where network connections are present, restricted, or completely offline, depending on the local environment.

  • Image mode for RHEL is based on OCI container images and bootable containers. See the following link for an introduction to bootc technology:

When choosing an image-based installation, consider whether the installation target is intended to be in an offline or networked state, where you plan to build system images, and how you plan to load your Red Hat Device Edge. Use the following scenarios as general guidance:

  • If you build either a fully self-contained RHEL for Edge or an image mode for RHEL ISO outside a disconnected environment, and then install the ISO locally on your edge devices, you likely do not need an RPM repository or a mirror registry.
  • If you build an ISO outside a disconnected environment that does not include the container images, but consists of only the RPMs, you need a mirror registry inside your disconnected environment. You use your mirror registry to pull container images.

  • If you build images inside a disconnected environment, or use package-based installations, you need both a mirror registry and a local RPM mirror repository. You can use either the RHEL reposync utility or Red Hat Satellite for advanced use cases. See the following links for more information:

1.5. RHEL installation tools and concepts
Copy link

Familiarize yourself with the following RHEL tools and concepts:

1.6. Red Hat Device Edge installation steps
Copy link

For most installation types, you must also take the following steps:

  • Download the pull secret from the Red Hat Hybrid Cloud Console using the following link:

  • Be ready to configure MicroShift by adding parameters and values to the MicroShift YAML configuration file. For more information, see the following link:

  • Decide whether you need to configure storage for the application and tasks you are using in your MicroShift cluster, or disable the MicroShift storage plug-in completely.

  • For more information about creating volume groups and persistent volumes on RHEL, see the following link:

  • Configure networking settings according to the access needs you plan for your MicroShift cluster and applications. Consider whether you want to use single or dual-stack networks, configure a firewall, or configure routes.

    Note

    You can use the Red Hat Enterprise Linux for Real Time (real-time kernel) where predictable latency is critical. Workload partitioning is also required for low-latency applications. For more information about low latency and the real-time kernel, see the following link:

Chapter 2. Using FIPS mode with MicroShift
Copy link

You can use FIPS mode with RPM-based installations of MicroShift on Red Hat Enterprise Linux (RHEL) 9.

  • To enable FIPS mode in MicroShift containers, the worker machine kernel must be enabled to run in FIPS mode before the machine starts.
  • Using FIPS with Red Hat Enterprise Linux for Edge (RHEL for Edge) images is not supported.
  • Using FIPS with image mode for RHEL is not supported.

2.1. FIPS mode with RHEL RPM-based installations
Copy link

Using FIPS with MicroShift requires enabling the cryptographic module self-checks in your Red Hat Enterprise Linux (RHEL) installation. After the host operating system has been configured to start with the FIPS modules, MicroShift containers are automatically enabled to run in FIPS mode.

  • When RHEL is started in FIPS mode, MicroShift core components use the RHEL cryptographic libraries that have been submitted to NIST for FIPS 140-2/140-3 validation on only the x86_64 architectures.

  • You must enable FIPS mode when you install RHEL 9 on the machines that you plan to use as worker machines.

    Important

    Because FIPS must be enabled before the operating system that your cluster uses starts for the first time, you cannot enable FIPS after you deploy a cluster.

  • MicroShift uses a FIPS-compatible Golang compiler.
  • FIPS is supported in the CRI-O container runtime.

2.1.1. Limitations
Copy link

  • TLS implementation FIPS support is not complete.
  • The FIPS implementation does not offer a single function that both computes hash functions and validates the keys that are based on that hash. This limitation continues to be evaluated for improvement in future MicroShift releases.

Chapter 3. The greenboot health check framework
Copy link

Greenboot is the generic health check framework for the systemd service on rpm-ostree systems such as Red Hat Enterprise Linux for Edge (RHEL for Edge). This framework is included in MicroShift installations with the microshift-greenboot and greenboot-default-health-checks RPM packages.

Greenboot health checks run at various times to assess system health and automate a rollback on rpm-ostree systems to the last healthy state in cases of software trouble, for example:

  • Default health check scripts run each time the system starts.
  • In addition the to the default health checks, you can write, install, and configure application health check scripts to also run every time the system starts.
  • Greenboot can reduce your risk of being locked out of edge devices during updates and prevent a significant interruption of service if an update fails.
  • When a failure is detected, the system boots into the last known working configuration using the rpm-ostree rollback capability. This feature is especially useful automation for edge devices where direct serviceability is either limited or non-existent.

A MicroShift application health check script is included in the microshift-greenboot RPM. The greenboot-default-health-checks RPM includes health check scripts verifying that DNS and ostree services are accessible. You can create your own health check scripts for the workloads you are running. You can write one that verifies that an application has started, for example.

3.1. How greenboot uses directories to run scripts
Copy link

Health check scripts run from four /etc/greenboot directories. These scripts run in alphabetical order. Keep this in mind when you configure the scripts for your workloads.

When the system starts, greenboot runs the scripts in the required.d and wanted.d directories. Depending on the outcome of those scripts, greenboot continues the startup or attempts a rollback as follows:

  1. System as expected: When all of the scripts in the required.d directory are successfully run, greenboot runs any scripts present in the /etc/greenboot/green.d directory.
  2. System trouble: If any of the scripts in the required.d directory fail, greenboot runs any prerollback scripts present in the red.d directory, then restarts the system.
Note

Greenboot redirects script and health check output to the system log. When you are logged in, a daily message provides the overall system health output.

3.1.1. Greenboot directories details
Copy link

Returning a nonzero exit code from any script means that script has failed. Greenboot restarts the system a few times to retry the scripts before attempting to roll back to the previous version.

  • /etc/greenboot/check/required.d contains the health checks that must not fail.

    • If the scripts fail, greenboot retries them three times by default. You can configure the number of retries in the /etc/greenboot/greenboot.conf file by setting the GREENBOOT_MAX_BOOTS parameter to the desired number of retries.
    • After all retries fail, greenboot automatically initiates a rollback if one is available. If a rollback is not available, the system log output shows that manual intervention is required.
    • The 40_microshift_running_check.sh health check script for MicroShift is installed into this directory.

  • /etc/greenboot/check/wanted.d contains health scripts that are allowed to fail without causing the system to be rolled back.

    • If any of these scripts fail, greenboot logs the failure but does not initiate a rollback.
  • /etc/greenboot/green.d contains scripts that run after greenboot has declared the start successful.
  • /etc/greenboot/red.d contains scripts that run after greenboot has declared the startup as failed, including the 40_microshift_pre_rollback.sh prerollback script. This script is executed right before a system rollback. The script performs MicroShift pod and OVN-Kubernetes cleanup to avoid potential conflicts after the system is rolled back to a previous version.
Important

If you customize the values of any environment variable in the /etc/greenboot/greenboot.conf file, these changes can be lost when the greenboot RPM package is updated or downgraded.

  • To retain customizations when building system images with MicroShift, add the greenboot.conf file to a blueprint.
  • To retain customizations when using an RPM installation, apply changes to the greenboot.conf file after you install MicroShift and greenboot RPMs.

3.2. The MicroShift health check script
Copy link

The 40_microshift_running_check.sh health check script only performs validation of core MicroShift services. Install your customized workload health check scripts in the greenboot directories to ensure successful application operations after system updates. Scripts run in alphabetical order.

MicroShift health checks are listed in the following table:

Expand
Table 3.1. Validation statuses and outcome for MicroShift
ValidationPassFail

Check that the script runs with root permissions

Next

exit 0

Check that the microshift.service is enabled

Next

exit 0

Wait for the microshift.service to be active (!failed)

Next

exit 1

Wait for Kubernetes API health endpoints to be working and receiving traffic

Next

exit 1

Wait for any pod to start

Next

exit 1

For each core namespace, wait for images to be pulled

Next

exit 1

For each core namespace, wait for pods to be ready

Next

exit 1

For each core namespace, check if pods are not restarting

exit 0

exit 1

3.2.1. Validation wait period
Copy link

The wait period in each validation is 10 minutes by default. After the wait period, if the validation has not succeeded, it is declared a failure. This wait period is incrementally increased by the base wait period after each boot in the verification loop.

  • You can override the base-time wait period by setting the MICROSHIFT_WAIT_TIMEOUT_SEC environment variable in the /etc/greenboot/greenboot.conf configuration file. For example, you can change the wait time to 5 minutes by resetting the value to 300 seconds, such as MICROSHIFT_WAIT_TIMEOUT_SEC=300.

The default configuration of the systemd journal service stores the data in the volatile /run/log/journal directory. To view system logs across system starts and restarts, you must enable log persistence and set limits on the maximal journal data size.

Procedure

  1. Make the directory by running the following command: 

    $ sudo mkdir -p /etc/systemd/journald.conf.d
    Copy to Clipboard Toggle word wrap

  2. Create the configuration file by running the following command: 

    cat <<EOF | sudo tee /etc/systemd/journald.conf.d/microshift.conf &>/dev/null
[Journal]
Storage=persistent
SystemMaxUse=1G
RuntimeMaxUse=1G
EOF
    Copy to Clipboard Toggle word wrap
  3. Edit the configuration file values for your size requirements.

3.4. Updates and third-party workloads
Copy link

Health checks are especially useful after an update. You can examine the output of greenboot health checks and determine whether the update was declared valid. This health check can help you determine if the system is working properly.

Health check scripts for updates are installed into the /etc/greenboot/check/required.d directory and are automatically executed during each system start. Exiting scripts with a nonzero status means the system start is declared as failed.

Important

Wait until after an update is declared valid before starting third-party workloads. If a rollback is performed after workloads start, you can lose data. Some third-party workloads create or update data on a device before an update is complete. Upon rollback, the file system reverts to its state before the update.

3.5. Checking the results of an update
Copy link

After a successful start, greenboot sets the variable boot_success= to 1 in GRUB. You can view the overall status of system health checks after an update in the system log by using the following procedure.

Procedure

  • To access the overall status of system health checks, run the following command: 

    $ sudo grub2-editenv - list | grep ^boot_success
    Copy to Clipboard Toggle word wrap

Example output for a successful system start

boot_success=1
Copy to Clipboard Toggle word wrap

You can manually access the output of health checks in the system log by using the following procedure.

Procedure

  • To access the results of a health check, run the following command: 

    $ sudo journalctl -o cat -u greenboot-healthcheck.service
    Copy to Clipboard Toggle word wrap

Example output of a failed health check

...
...
Running Required Health Check Scripts...
STARTED
GRUB boot variables:
boot_success=0
boot_indeterminate=0
boot_counter=2
...
...
Waiting 600s for MicroShift service to be active and not failed
FAILURE
...
...
Copy to Clipboard Toggle word wrap

You can access the output of health check scripts in the system log. For example, check the results of a prerollback script using the following procedure.

Procedure

  • To access the results of a prerollback script, run the following command: 

    $ sudo journalctl -o cat -u redboot-task-runner.service
    Copy to Clipboard Toggle word wrap

Example output of a prerollback script

...
...
Running Red Scripts...
STARTED
GRUB boot variables:
boot_success=0
boot_indeterminate=0
boot_counter=0
The ostree status:
* rhel c0baa75d9b585f3dd989a9cf05f647eb7ca27ee0dbd4b94fe8c93ed3a4b9e4a5.0
    Version: 9.1
    origin: <unknown origin type>
  rhel 6869c1347b0e0ba1bbf0be750cdf32da5138a1fcbc5a4c6325ab9eb647b64663.0 (rollback)
    Version: 9.1
    origin refspec: edge:rhel/9/x86_64/edge
System rollback imminent - preparing MicroShift for a clean start
Stopping MicroShift services
Removing MicroShift pods
Killing conmon, pause and OVN processes
Removing OVN configuration
Finished greenboot Failure Scripts Runner.
Cleanup succeeded
Script '40_microshift_pre_rollback.sh' SUCCESS
FINISHED
redboot-task-runner.service: Deactivated successfully.
Copy to Clipboard Toggle word wrap

3.8. Checking updates with a health check script
Copy link

Access the output of greenboot health check scripts in the system log after an update by using the following procedure.

Procedure

  • To access the result of update checks, run the following command: 

    $ sudo grub2-editenv - list | grep ^boot_success
    Copy to Clipboard Toggle word wrap

Example output for a successful update

boot_success=1
Copy to Clipboard Toggle word wrap

If your command returns boot_success=0, either the greenboot health check is still running, or the update is a failure.

Legal Notice
Copy link

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
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