Updating
Updating MicroShift clusters
Abstract
Chapter 1. About MicroShift updates
Updates are supported on MicroShift beginning with the General Availability version 4.14. Supported updates include those from one minor version to the next in sequence, for example, from 4.14 to 4.15. Patch updates are also supported from z-stream to z-stream, for example 4.14.1 to 4.14.2.
1.1. Understanding MicroShift updates
MicroShift updates are supported on both rpm-ostree edge-deployed hosts and non-OSTree hosts. You can complete updates using the following methods:
-
Embed the latest version of MicroShift in a new
rpm-ostreesystem image such as Red Hat Enterprise Linux for Edge (RHEL for Edge). See * Applying updates on an OSTree system - Manually update the RPMs on a non-OSTree system such as Red Hat Enterprise Linux (RHEL). See * Applying updates manually with RPMs
Only rpm-ostree updates include automatic rollbacks.
1.1.1. RPM OSTree updates
Using the RHEL for Edge rpm-ostree update path allows for automated backup and system rollback in case any part of the update fails. You must build a new rpm-ostree image and embed the new MicroShift version in that image. 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.
Check following compatibility table for details:
Red Hat Device Edge release compatibility matrix
The two products of Red Hat Device Edge work together as a single solution for device-edge computing. To successfully pair your products, use the verified releases together for each as listed in the following table:
| RHEL for Edge Version(s) | MicroShift Version | MicroShift Release Status | MicroShift Supported Updates |
| 9.2, 9.3 | 4.15 | Generally Available | 4.15.0→4.15.z and 4.15→future minor version |
| 9.2, 9.3 | 4.14 | Generally Available | 4.14.0→4.14.z and 4.14→4.15 |
| 9.2 | 4.13 | Technology Preview | None |
| 8.7 | 4.12 | Developer Preview | None |
1.1.2. Manual RPM updates
You can use the manual RPM update path to replace your existing version of MicroShift. The versions of RHEL and MicroShift must be compatible. Ensuring system health and completing additional system backups are manual processes.
1.1.3. Checking version update path
Before attempting an update of either Red Hat Device Edge component, determine which versions of MicroShift and RHEL for Edge or RHEL are installed. Plan for the versions of each that you intend to use.
MicroShift update paths
- Generally Available Version 4.14 to 4.14.z or 4.15 on RHEL for Edge 9.2 or 9.3
- Generally Available Version 4.14 to 4.14.z or 4.15 on RHEL 9.2 or 9.3
- Generally Available Version 4.15 to 4.15.z on RHEL for Edge 9.2 or 9.3
- Generally Available Version 4.15 to 4.15.z on RHEL 9.2 or 9.3
Chapter 2. Update options with MicroShift and Red Hat Device Edge
You can update Red Hat Enterprise Linux for Edge (RHEL for Edge) images or Red Hat Enterprise Linux (RHEL) with or without updating the MicroShift version if the version combination is supported. See the following table for details:
Red Hat Device Edge release compatibility matrix
The two products of Red Hat Device Edge work together as a single solution for device-edge computing. To successfully pair your products, use the verified releases together for each as listed in the following table:
| RHEL for Edge Version(s) | MicroShift Version | MicroShift Release Status | MicroShift Supported Updates |
| 9.2, 9.3 | 4.15 | Generally Available | 4.15.0→4.15.z and 4.15→future minor version |
| 9.2, 9.3 | 4.14 | Generally Available | 4.14.0→4.14.z and 4.14→4.15 |
| 9.2 | 4.13 | Technology Preview | None |
| 8.7 | 4.12 | Developer Preview | None |
2.1. Checking version update path
Before attempting an update of either Red Hat Device Edge component, determine which versions of MicroShift and RHEL for Edge or RHEL are installed. Plan for the versions of each that you intend to use.
MicroShift update paths
- Generally Available Version 4.14 to 4.14.z or 4.15 on RHEL for Edge 9.2 or 9.3
- Generally Available Version 4.14 to 4.14.z or 4.15 on RHEL 9.2 or 9.3
- Generally Available Version 4.15 to 4.15.z on RHEL for Edge 9.2 or 9.3
- Generally Available Version 4.15 to 4.15.z on RHEL 9.2 or 9.3
Updates of MicroShift from one minor version to the next must be in sequence. For example, you cannot update from 4.14 to 4.16. You must update 4.14 to 4.15 and so on.
2.2. Standalone MicroShift updates
You can update MicroShift without reinstalling your applications. RHEL or RHEL for Edge updates are also not required to update MicroShift, as long as the existing operating system is compatible with the new version of MicroShift that you want to use.
MicroShift operates as an in-place update and does not require removal of the previous version. Data backups beyond those required for the usual functioning of your applications are also not required.
2.2.1. RPM-OSTree updates
You can update MicroShift on an rpm-ostree system such as RHEL for Edge by building a new image containing the new version of MicroShift. Ensure that the version of the operating system you want to use is compatible with the new version of MicroShift that you update to.
The following features are available in the RHEL for Edge update path:
- The system automatically rolls back to a previous healthy system state if the update fails.
- Applications do not need to be reinstalled.
- 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 in a RHEL for Edge image, use the procedures in the following documentation:
To understand more about Greenboot, see the following documentation:
2.2.2. Manual RPM updates
You can update MicroShift manually on a non-OSTree system such as Red Hat Enterprise Linux (RHEL) by downloading and updating the RPMs. To complete this update type, use the subscription manager to access the repository containing the new RPMs. To begin a manual RPM update, use the procedures in the following documentation:
2.3. Standalone RHEL for Edge updates
You can update RHEL for Edge or RHEL without updating MicroShift, on the condition that the two versions are compatible. Check compatibilities before beginning an update. Use the RHEL for Edge documentation specific to your update path.
Additional resources
2.4. Simultaneous MicroShift and operating system updates
You can update RHEL for Edge or RHEL and update MicroShift at the same time, on the condition that the versions are compatible. Check for compatibility before beginning an update. First use the RHEL for Edge and RHEL documentation specific to your update path to plan and update the operating system. Then use the MicroShift update type specific to your update path.
Chapter 3. About updating MicroShift RPMs on an OSTree system
Updating MicroShift on an rpm-ostree system such as Red Hat Enterprise Linux for Edge (RHEL for Edge) requires building a new operating system image containing the new version of MicroShift. After you have the rpm-ostree image with MicroShift embedded, direct your system to 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.14 to 4.15 or from 4.15.0 to 4.15.1.
Red Hat Device Edge release compatibility matrix
The two products of Red Hat Device Edge work together as a single solution for device-edge computing. To successfully pair your products, use the verified releases together for each as listed in the following table:
| RHEL for Edge Version(s) | MicroShift Version | MicroShift Release Status | MicroShift Supported Updates |
| 9.2, 9.3 | 4.15 | Generally Available | 4.15.0→4.15.z and 4.15→future minor version |
| 9.2, 9.3 | 4.14 | Generally Available | 4.14.0→4.14.z and 4.14→4.15 |
| 9.2 | 4.13 | Technology Preview | None |
| 8.7 | 4.12 | Developer Preview | None |
Downgrades are not supported. The following procedure is for upgrades only.
3.1. Applying updates on an OSTree system
To update MicroShift on an rpm-ostree system such as Red Hat Enterprise Linux for Edge (RHEL for Edge), embed the new version of MicroShift on a new operating system image. 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. Back up and system rollback are automatic with this update type.
You can also use this workflow to update applications running in the MicroShift cluster. Ensure compatibility between the application and the adjacent versions of MicroShift and RHEL for Edge before starting an update.
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.
You cannot downgrade MicroShift with this process. Downgrades are not supported.
Procedure
Create an Image Builder configuration file for adding the
rhocp-4.15RPM repository source required to pull MicroShift RPMs by running the following command:$ cat > rhocp-4.15.toml <<EOF id = "rhocp-4.15" name = "Red Hat OpenShift Container Platform 4.15 for RHEL 9" type = "yum-baseurl" url = "https://cdn.redhat.com/content/dist/layered/rhel9/$(uname -m)/rhocp/4.15/os" check_gpg = true check_ssl = true system = false rhsm = true EOF
Add the update RPM source to the Image Builder by running the following command:
$ sudo composer-cli sources add rhocp-4.15.toml
Build a new image of RHEL for Edge that contains the new version of MicroShift. To determine the steps required, use the following documentation:
Update the host to use the new image of RHEL for Edge. To determine the steps required, use the following documentation:
Reboot the host to apply updates by running the following command:
$ sudo systemctl reboot
Chapter 4. About updating MicroShift RPMs manually
Updating MicroShift for non-OSTree systems such as Red Hat Enterprise Linux (RHEL) requires downloading then updating the RPMs. For patch releases, such as 4.15.1 to 4.15.2, download and update the RPMs. For minor-version release updates, add the step of enabling the update repository using your subscription manager.
MicroShift updates are supported from one minor version to the next in sequence. For example, you must update 4.14 to 4.15.
For either upgrading with patch updates or a minor-version update, you can back up application data as needed and move the data copy to a secure location.
4.1. Applying patch updates using RPMs
Updating MicroShift on non rpm-ostree systems such as Red Hat Enterprise Linux (RHEL) requires downloading then updating the RPMs. A system reboot is not required for patch updates. For example, use the following procedure to upgrade from 4.14.0 to 4.14.1.
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.
You cannot downgrade MicroShift with this process. Downgrades are not supported.
Procedure
Update the MicroShift RPMs by running the following command:
$ sudo dnf update microshift
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.
4.2. Applying minor-version updates with RPMs
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.14 to 4.15.
You can only update MicroShift from one version to the next in sequence. Jumping minor versions is not supported. For example, must update 4.14 to 4.15.
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.
You cannot downgrade MicroShift with this process. Downgrades are not supported.
Procedure
Enable the MicroShift repositories by running the following command:
$ sudo subscription-manager repos \ --enable rhocp-4.15-for-rhel-9-$(uname -m)-rpms \ --enable fast-datapath-for-rhel-9-$(uname -m)-rpmsUpdate the MicroShift RPMs by running the following command:
$ sudo dnf update microshift
Reboot the host to apply updates by running the following command:
$ sudo systemctl reboot
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
Check if the health checks exited with a successful boot by running the following command:
$ sudo systemctl status greenboot-healthcheck
Check the health check logs by running the following command:
$ sudo journalctl -u greenboot-healthcheck
Additional resources
