Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Updating

Red Hat build of MicroShift 4.21

Updating a MicroShift node

Red Hat OpenShift Documentation Team

Abstract

Update a Red Hat build of MicroShift node or Red Hat Device Edge.

Chapter 1. Update options for Red Hat Device Edge
Copy link

To update Red Hat Device Edge, you can update both Red Hat build of MicroShift and Red Hat Enterprise Linux (RHEL), or each part by itself without updating the other. You must keep the parts in a supported configuration. Consider the following options when planning updates to your current deployments.

1.1. Red Hat Device Edge updates
Copy link

You can update Red Hat Enterprise Linux (RHEL) operating system independently of your Red Hat build of MicroShift version if the version combination is supported.

Warning

Keeping component versions in a supported configuration of Red Hat Device Edge can require updating MicroShift and RHEL at the same time. Ensure that your version of RHEL is compatible with the version of MicroShift you are updating to, especially if you are updating MicroShift across two minor versions. Otherwise, you can create an unsupported configuration, break your node, or both. For more information, see the following link:

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:

Note

Be sure to check the support status of a release on the product lifecycle page.

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

10.0

4.21

4.21.0 → 4.21.z (Technology Preview)

9.6

4.21

4.21.0 → 4.21.z

9.6

4.20

4.20.0 → 4.20.z, 4.20 → 4.21

9.6

4.19

4.19.0 → 4.19.z, 4.19 → 4.20

9.4

4.18

4.18.0 → 4.18.z, 4.18 → 4.20 on RHEL 9.6

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

4.14

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

1.2. Standalone MicroShift updates
Copy link

You can update just your MicroShift version by embedding the new version in a RHEL image or by installing the RPMs on a standard RHEL operating system. Consider your current operating system version and deployments when planning a MicroShift update.

The following factors apply to a standalone MicroShift version update:

  • MicroShift operates as an in-place update and does not require removal of the earlier version.
  • Data backups beyond those required for the usual functioning of your applications are not required.
  • You can potentially update MicroShift without reinstalling your applications and Operators.
  • Only rpm-ostree updates include automatic rollbacks.
Important

You must update RHEL to update MicroShift if your current operating system is not compatible with the new version of MicroShift that you want to use.

1.2.1. Updating MicroShift on RHEL for Edge
Copy link

You can have automated backup and system rollback in case any part of the update fails by using the rpm-ostree update path for a new or existing RHEL for Edge deployment.

  • You can update MicroShift on an rpm-ostree system such as RHEL for Edge by building a new system image containing the new version of MicroShift.
  • The rpm-ostree image can be the same version or an updated version, but the versions of RHEL for Edge and MicroShift must be compatible.

The following features are available in the RHEL for Edge update path:

  • The system automatically rolls back to an earlier healthy system state if the update fails.
  • You do not need to reinstall applications.
  • You do not need to reinstall Operators.
  • You can update an application without updating MicroShift using this update type.
  • The image you build can contain other updates as needed.

To begin a MicroShift update by embedding the new version in a RHEL for Edge image, use the procedures in the following documentation:

To understand more about greenboot, see the following documentation:

1.2.2. Manual RPM updates
Copy link

You can update MicroShift manually on Red Hat Enterprise Linux (RHEL) by updating the RPMs. This type of update is useful for development environments and testing.

  • To complete this update type, use the subscription manager to enable the repository that has the new RPMs.
  • Use manual processes to ensure system health and complete additional system backups.

  • To begin a manual RPM update, use the procedures in the following documentation:

When using RPM updates, avoid creating an unsupported configuration or breaking your node by carefully managing your RHEL repositories.

Prerequisites

Procedure

  1. Avoid unintended updates by locking your operating system version by running the following command: 

    $ sudo subscription-manager release --set=9.6
    Copy to Clipboard Toggle word wrap

  2. If you are using an EUS MicroShift release, disable the RHEL standard-support-scope repositories by running the following command: 

    $ sudo subscription-manager repos \
    --disable=rhel-9-for-$(uname -m)-appstream-rpms \
    --disable=rhel-9-for-$(uname -m)-baseos-rpms
    Copy to Clipboard Toggle word wrap

    You can replace 9 with the major version of your compatible RHEL system if it is not same version given in this example.

  3. After you disable the standard-support repositories, enable the RHEL EUS repos by running the following command: 

    $ sudo subscription-manager repos \
    --enable rhel-9-for-$(uname -m)-appstream-eus-rpms \
    --enable rhel-9-for-$(uname -m)-baseos-eus-rpms
    Copy to Clipboard Toggle word wrap

    You can replace 9 with the major version of your compatible RHEL system if it is not same version given in this example.

Verification

  • List the repositories you have enabled for RHEL by running the following command: 

    $ sudo subscription-manager repos --list-enabled
    Copy to Clipboard Toggle word wrap

    Example output

    +----------------------------------------------------------+
    Available Repositories in /etc/yum.repos.d/redhat.repo
+----------------------------------------------------------+
Repo ID:   rhel-9-for-x86_64-baseos-eus-rpms
Repo Name: Red Hat Enterprise Linux 9 for x86_64 - BaseOS - Extended Update Support (RPMs)
Repo URL:  https://cdn.redhat.com/content/eus/rhel9/$releasever/x86_64/baseos/os
Enabled:   1
Repo ID:   rhel-9-for-x86_64-appstream-eus-rpms
Repo Name: Red Hat Enterprise Linux 9 for x86_64 - AppStream - Extended Update Support (RPMs)
Repo URL:  https://cdn.redhat.com/content/eus/rhel9/$releasever/x86_64/appstream/os
Enabled:   1
    Copy to Clipboard Toggle word wrap

1.3. Standalone RHEL updates
Copy link

You can update to any RHEL type without updating MicroShift if the two final versions in your Red Hat Device Edge are compatible. Check compatibilities before beginning an update. Use the RHEL documentation specific to your use case.

For example:

1.4. Simultaneous MicroShift and RHEL updates
Copy link

You can update your RHEL operating system type and update MicroShift at the same time, if the final versions are a supported configuration of Red Hat Device Edge. You can use following workflow to plan the general steps to take:

  1. Check for compatibility before beginning an update.
  2. Use the RHEL documentation specific to your update path to plan and update the operating system.
  3. Enable the correct MicroShift repository to ensure alignment between your RHEL and MicroShift versions.
  4. Use the MicroShift update type specific to your update path, such as using an RPM installation or embedding MicroShift into an operating system image.

Starting with MicroShift 4.19, you can migrate your MicroShift node from RHEL for Edge to image mode for RHEL if the final versions are a supported configuration of Red Hat Device Edge. Check compatibilities before beginning a migration. See the RHEL documentation for instructions to migrate your image-based RHEL system.

You can update MicroShift on Red Hat Enterprise Linux for Edge (RHEL for Edge) rhel-9 by embedding the new version of MicroShift on a new operating system image.

2.1. MicroShift updates on an RHEL for Edge system
Copy link

Updating MicroShift on a Red Hat Enterprise Linux for Edge (RHEL for Edge) system requires building a new RHEL for Edge image containing the new version of MicroShift and any associated optional RPMs.

After you create the rpm-ostree image with MicroShift embedded, you can boot into that operating system image.

The procedures are the same for minor-version and patch updates. For example, use the same steps to upgrade from 4.20 to 4.21 or from 4.21.2 to 4.21.3. The following details apply:

  • Back up and system rollback are automatic with this update type.
  • You can use the following workflow to update applications running in the MicroShift node. Ensure compatibilities between the application and the adjacent versions of MicroShift and RHEL for Edge before starting an update.

  • Downgrades other than automatic rollbacks are not supported. The following procedure is for updates only.

    Important

    The steps you use depends on how your existing deployment is set up. The following procedure outlines the general steps you can take, with links to the RHEL for Edge documentation. The RHEL for Edge documentation is your resource for specific details on building an updated operating system image.

2.2. Applying updates on an RHEL for Edge system
Copy link

To update MicroShift on Red Hat Enterprise Linux for Edge (RHEL for Edge), embed the new version of MicroShift on a new operating system image.

Important

This procedure is for use with RHEL 9 images only. RHEL 10 images require bootc image building tools. For more information, see the following link:

Important

You cannot downgrade MicroShift with this process. Downgrades other than automatic rollbacks are not supported.

Prerequisites

  • The system requirements for installing MicroShift have been met.
  • You have root user access to the host.
  • The version of MicroShift you have is compatible with the RHEL for Edge image you are preparing to use.

Procedure

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

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

  2. Add the update RPM source to the image builder by running the following command: 

    $ sudo composer-cli sources add rhocp-4.21.toml
    Copy to Clipboard Toggle word wrap

  3. Build a new image of RHEL for Edge that contains the new version of MicroShift. To determine the steps required, use the following documentation:

  4. Update the host to use the new image of RHEL for Edge. To determine the steps required, use the following documentation:

  5. Reboot the host to apply updates by running the following command: 

    $ sudo systemctl reboot
    Copy to Clipboard Toggle word wrap

Chapter 3. Updating RPMs manually
Copy link

You can update MicroShift or Red Hat Device Edge manually using RPMs.

3.1. About updates using RPMs
Copy link

Updating Red Hat build of MicroShift for non-image-based Red Hat Enterprise Linux (RHEL) systems requires updating the RPMs.

  • For patch releases, such as 4.21.1 to 4.21.2, simply update the RPMs.
  • For minor-version release updates, add the step of enabling the compatible update repository by using your subscription manager.
Note

You can back up application data as needed and move the data copy to a secure location when using any update type.

3.2. Applying patch updates using RPMs
Copy link

Updating MicroShift on non rpm-ostree systems such as Red Hat Enterprise Linux (RHEL) requires downloading then updating the RPMs. For example, use the following procedure to upgrade from 4.21.1 to 4.21.2.

Warning

Keeping component versions in a supported configuration of Red Hat Device Edge can require updating MicroShift and RHEL at the same time. Ensure that your version of RHEL is compatible with the version of MicroShift you are updating to, especially if you are updating MicroShift across two minor versions. Otherwise, you can create an unsupported configuration, break your node, or both. For more information, see the following link:

Note

You cannot downgrade MicroShift with this process. Downgrades are not supported.

Prerequisites

  • The system requirements for installing MicroShift have been met.
  • You have root user access to the host.
  • The version of MicroShift you have is compatible to upgrade to the version you are preparing to use.
  • You have verified that your host operating system is compatible with the version of MicroShift you are preparing to install.
  • You have completed a system backup.

Procedure

  1. Update the MicroShift RPMs by running the following command: 

    $ sudo dnf update microshift
    Copy to Clipboard Toggle word wrap

  2. Restart MicroShift by running the following command: 

    $ sudo systemctl restart microshift
    Copy to Clipboard Toggle word wrap
    Note

    The greenboot system health check runs on this update type, but does not perform any actions. If the update fails, an error message appears with the instruction to check the logs.

3.3. Applying minor-version updates with RPMs
Copy link

Updating a MicroShift minor version on non rpm-ostree systems such as Red Hat Enterprise Linux (RHEL) requires downloading then updating the RPMs. For example, use the following procedure to update from 4.18 to 4.20.

Warning

Keeping component versions in a supported configuration of Red Hat Device Edge can require updating MicroShift and RHEL at the same time. Ensure that your version of RHEL is compatible with the version of MicroShift you are updating to, especially if you are updating MicroShift across two minor versions. Otherwise, you can create an unsupported configuration, break your node, or both. For more information, see the following link:

Note

You cannot downgrade MicroShift with this process. Downgrades are not supported.

Prerequisites

  • The system requirements for installing MicroShift have been met.
  • You have root user access to the host.
  • The version of MicroShift you have is compatible to upgrade to the version you are preparing to use.
  • You have verified that your host operating system is compatible with the version of MicroShift you are preparing to install.
  • You have completed a system backup.

Procedure

  1. For all lifecycles, enable the repository for the release you want to update to by running the following command: 

    $ sudo subscription-manager repos \
    --enable rhocp-4.21-for-rhel-9-$(uname -m)-rpms \
    --enable fast-datapath-for-rhel-9-$(uname -m)-rpms
    Copy to Clipboard Toggle word wrap

  2. For extended support (EUS) releases, also enable the EUS repositories by running the following command: 

    $ sudo subscription-manager repos \
    --enable rhel-9-for-$(uname -m)-appstream-eus-rpms \
    --enable rhel-9-for-$(uname -m)-baseos-eus-rpms
    Copy to Clipboard Toggle word wrap

  3. Avoid unintended future updates into an unsupported configuration by locking your operating system version with the following command: 

    $ sudo subscription-manager release --set=9.6
    Copy to Clipboard Toggle word wrap

  4. Update the MicroShift RPMs by running the following command: 

    $ sudo dnf update microshift
    Copy to Clipboard Toggle word wrap

  5. Reboot the host to apply updates by running the following command: 

    $ sudo systemctl reboot
    Copy to Clipboard Toggle word wrap
    Note

    The system health check runs on this update type, but does not perform any actions. If the update fails, an error message appears with the instruction to check the logs.

Verification

  1. Check if the health checks exited with a successful boot by running the following command: 

    $ sudo systemctl status greenboot-healthcheck
    Copy to Clipboard Toggle word wrap

  2. Check the health check logs by running the following command: 

    $ sudo journalctl -u greenboot-healthcheck
    Copy to Clipboard Toggle word wrap

To migrate MicroShift from Red Hat Enterprise Linux for Edge (RHEL for Edge), embed MicroShift on a new image mode for RHEL image.

4.1. Migrating MicroShift to image mode for RHEL
Copy link

Migrating MicroShift from a Red Hat Enterprise Linux for Edge (RHEL for Edge) system to a image mode for RHEL system requires building a new image mode for RHEL image containing the required version of MicroShift and any associated optional RPMs.

See the Red Hat Enterprise Linux (RHEL) documentation for general instructions on migrating RHEL for Edge systems to image mode for RHEL using the bootc switch command. Plan the upgrade process carefully. The following tips apply:

  • Follow the instructions in the RHEL documentation for converting rpm-ostree blueprint files to image mode container files.
  • You can use the rpm-ostree compose container-encapsulate image-compose command to create a base container image that can be used for bootc container builds. Then you can derive and familiarize yourself with an image mode for RHEL image that is based on existing ostree commits.
  • To fully adopt image mode for RHEL, define a container build pipeline.
  • Plan for UID and GID drift because RHEL for Edge and image mode for RHEL are not derived from the same parent image. See the RHEL documentation for more information.

If you do not re-install operating systems that are running MicroShift, you must use a workaround for a possible UID and GID drift during the migration process. One way to solve this problem is to add systemd units that apply the necessary fixes before the affected system services are started.

Prerequisites

  • You have an existing RHEL for Edge deployment running MicroShift.
  • You have root access to the build host.
  • You have an image that you want to deploy.

Procedure

  • Solve the potential UID or GID drift for the Open vSwitch (OVS) systemd service, ovsdb-server.service, by adding the following command to the MicroShift image-build procedure: 

    # Install systemd configuration drop-ins to fix potential permission problems when upgrading from rpm-ostree commits to image mode container layers
RUN mkdir -p /usr/lib/systemd/system/ovsdb-server.service.d && \
    cat > /usr/lib/systemd/system/ovsdb-server.service.d/microshift-ovsdb-ownership.conf <<'EOF'
# The openvswitch database files must be owned by the appropriate user and its primary group. That the user and its group can be overwritten, recreate them.
[Service]
ExecStartPre=/bin/sh -c '/bin/getent passwd openvswitch >/dev/null || useradd -r openvswitch'
ExecStartPre=/bin/sh -c '/bin/getent group hugetlbfs >/dev/null || groupadd -r hugetlbfs'
ExecStartPre=/sbin/usermod -a -G hugetlbfs openvswitch
ExecStartPre=/bin/chown -Rhv openvswitch. /etc/openvswitch
EOF
    Copy to Clipboard Toggle word wrap
    Important

    After the MicroShift migration to image mode for RHEL is complete, this workaround is not needed and can be removed.

Chapter 5. Listing RPM update package contents
Copy link

You can preview the contents of a MicroShift RPM package update before installing. This helps you make sure that the update you are planning is a supported configuration of Red Hat Device Edge.

To see the images included with a MicroShift release, you can list the contents of the microshift-release-info RPM by downloading and unpacking the RPM.

Prerequisites

  • You are using Red Hat Enterprise Linux (RHEL) or an operating system with an RPM package manager.
  • Your MicroShift repositories are enabled.

Procedure

  1. Optional: List which versions of the MicroShift RPM are available for download by running the following command: 

    $ sudo dnf repoquery microshift-release-info-0:4.17.1
    Copy to Clipboard Toggle word wrap

    Replace the example value 4.17.1 with the major and minor release numbers you are interested in.

    Example output

    Updating Subscription Management repositories.
microshift-release-info-0:4.17.1-202406281132.p0.g8babeb9.assembly.4.17.1.el9.noarch
microshift-release-info-0:4.17.10-202408291007.p0.g6e4ee4d.assembly.4.17.10.el9.noarch
microshift-release-info-0:4.17.2-202407040825.p0.g2e0407e.assembly.4.17.2.el9.noarch
microshift-release-info-0:4.17.3-202407111123.p0.ge4206d3.assembly.4.17.3.el9.noarch
microshift-release-info-0:4.17.4-202407191908.p0.g057a9af.assembly.4.17.4.el9.noarch
microshift-release-info-0:4.17.5-202407250951.p0.g0afcb57.assembly.4.17.5.el9.noarch
microshift-release-info-0:4.17.6-202408010822.p0.gc4ded66.assembly.4.17.6.el9.noarch
microshift-release-info-0:4.17.7-202408081107.p0.g0597bb8.assembly.4.17.7.el9.noarch
microshift-release-info-0:4.17.8-202408150851.p0.gc8a3bb1.assembly.4.17.8.el9.noarch
microshift-release-info-0:4.17.9-202408220842.p0.gefa92a2.assembly.4.17.9.el9.noarch
    Copy to Clipboard Toggle word wrap

  2. Download the RPM package you want by running the following command: 

    $ sudo dnf download 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, for example, 4.17.1.

    Example output

    microshift-release-info-4.17.1.-202411101230.p0.g7dc6a00.assembly.4.17.1.el9.noarch.rpm
    Copy to Clipboard Toggle word wrap

    Your output should contain the date and commit ID.

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

    $ rpm2cpio <microshift_release_info> | cpio -idmv
    Copy to Clipboard Toggle word wrap

    Replace <microshift_release_info> with the name of the RPM package from the previous step. For example, microshift-release-info-4.17.10-202408291007.p0.g6e4ee4d.assembly.4.17.10.el9.noarch.rpm.

    Example output

    ./usr/share/microshift
./usr/share/microshift/blueprint
./usr/share/microshift/blueprint/blueprint-aarch64.toml
./usr/share/microshift/blueprint/blueprint-x86_64.toml
./usr/share/microshift/release
./usr/share/microshift/release/release-aarch64.json
./usr/share/microshift/release/release-x86_64.json
    Copy to Clipboard Toggle word wrap

  4. List the contents by running the following command: 

    $ cat ./usr/share/microshift/release/release-x86_64.json
    Copy to Clipboard Toggle word wrap

    Example output

    {
  "release": {
    "base": "4.17.10"
  },
  "images": {
    "cli": "....
# ...
    Copy to Clipboard Toggle word wrap

To update existing objects to their latest version without recreating them, use storage version migration in MicroShift. By creating a StorageVersionMigration custom resource (CR), you request the Kube Storage Version Migrator embedded controller to handle the transition automatically.

Either you or a controller can create a StorageVersionMigration custom resource (CR) that requests a migration through the Migrator Controller.

To update stored data to the latest Kubernetes storage version, perform a storage migration.

The procedure shows an example of converting existing objects on the v1beta1 version to the current version, such as v1beta2, to ensure compatibility with the cluster APIs.

Procedure

  • Either you or any controller that has support for the StorageVersionMigration API must trigger a migration request. Use the following example request for reference:

    Example request

    apiVersion: migration.k8s.io/v1alpha1
kind: StorageVersionMigration
metadata:
  name: v1beta1
spec:
  resource:
    group: example.storage.k8s.io
    resource: volumeclasses
    version: v1alpha1
# ...
    Copy to Clipboard Toggle word wrap

    where:

    resource.resource
    Specifies the plural name of the resource.
    resource.version
    Specifies the version to update to.

Verification

  • To monitor the progress of the update, review the status of the StorageVersionMigration custom resource (CR).
Note

A migration fails when you misname a group or resource. Incompatible versions between the previous and latest versions can also cause a migration to fail.

Legal Notice
Copy link

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . 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, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.
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

© 2026 Red HatBack to top