Updating

Red Hat build of MicroShift 4.16

Updating MicroShift clusters

Red Hat OpenShift Documentation Team

Abstract

Learn to update Red Hat build of MicroShift clusters.

Chapter 1. About Red Hat build of MicroShift updates

Updates are supported on Red Hat build of MicroShift beginning with the General Availability version 4.14. With the 4.16 release, the following updates are supported:

A maximum of two minor versions to the next in sequence, for example, from 4.14 to 4.16.
One minor version to the next in sequence, for example, from 4.15 to 4.16.
Patch updates are also supported from z-stream to z-stream, for example 4.16.1 to 4.16.2.

1.1. Understanding MicroShift updates

Red Hat build of 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-ostree system 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

Note

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

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. For example, an update of MicroShift from 4.14 to 4.16 requires a {op-system} update. Supported configurations of Red Hat Device Edge use verified releases for each together as listed in the following table:

RHEL for Edge Version(s)	MicroShift Version	MicroShift Release Status	Supported MicroShift Version→MicroShift Version Updates
9.4	4.16	Generally Available	4.16.0→4.16.z, 4.14→4.16 and 4.15→4.16
9.2, 9.3	4.15	Generally Available	4.15.0→4.15.z, 4.14→4.15 and 4.15→4.16
9.2, 9.3	4.14	Generally Available	4.14.0→4.14.z, 4.14→4.15 and 4.14→4.16
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.

Important

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.

1.1.3. Checking version update path

Before updating MicroShift or {op-system}, determine the compatibilities. Plan for the versions of each that you intend to use.

Red Hat build of MicroShift update paths

MicroShift version 4.16

Version 4.16 to 4.16.z on {op-system} or RHEL for Edge 9.4

MicroShift version 4.15

Version 4.15 on {op-system} or RHEL for Edge 9.2 or 9.3 to 4.16 on {op-system} or RHEL for Edge 9.4
Version 4.15 to 4.15.z on {op-system} or RHEL for Edge 9.2 or 9.3

MicroShift version 4.14

Version 4.14 on {op-system} or RHEL for Edge 9.2 or 9.3 to 4.16 on {op-system} or RHEL for Edge 9.4
Version 4.14 to 4.15 on {op-system} or RHEL for Edge 9.2 or 9.3
Version 4.14 to 4.14.z on {op-system} or RHEL for Edge 9.2 or 9.3

Chapter 2. Update options with Red Hat build of 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 Red Hat build of MicroShift version if the version combination is supported. See the following table for details:

Red Hat Device Edge release compatibility matrix

RHEL for Edge Version(s)	MicroShift Version	MicroShift Release Status	Supported MicroShift Version→MicroShift Version Updates
9.4	4.16	Generally Available	4.16.0→4.16.z, 4.14→4.16 and 4.15→4.16
9.2, 9.3	4.15	Generally Available	4.15.0→4.15.z, 4.14→4.15 and 4.15→4.16
9.2, 9.3	4.14	Generally Available	4.14.0→4.14.z, 4.14→4.15 and 4.14→4.16
9.2	4.13	Technology Preview	None
8.7	4.12	Developer Preview	None

2.1. Checking version update path

Before updating MicroShift or {op-system}, determine the compatibilities. Plan for the versions of each that you intend to use.

Red Hat build of MicroShift update paths

MicroShift version 4.16

Version 4.16 to 4.16.z on {op-system} or RHEL for Edge 9.4

MicroShift version 4.15

Version 4.15 on {op-system} or RHEL for Edge 9.2 or 9.3 to 4.16 on {op-system} or RHEL for Edge 9.4
Version 4.15 to 4.15.z on {op-system} or RHEL for Edge 9.2 or 9.3

MicroShift version 4.14

Version 4.14 on {op-system} or RHEL for Edge 9.2 or 9.3 to 4.16 on {op-system} or RHEL for Edge 9.4
Version 4.14 to 4.15 on {op-system} or RHEL for Edge 9.2 or 9.3
Version 4.14 to 4.14.z on {op-system} or RHEL for Edge 9.2 or 9.3

Important

Updates of MicroShift are supported with a maximum of two minor versions. For example, you can update from 4.14 to 4.16 in a single step. Updating 4.14 to 4.15 first is not required.

2.2. Standalone MicroShift updates

Consider the following when planning to update MicroShift:

You can potentially update MicroShift without reinstalling your applications and Operators.
RHEL or RHEL for Edge updates are only required to update MicroShift if the existing operating system is not 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.
Operators 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:

Applying updates on an OSTree system

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:

About updating MicroShift RPMs manually

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

Managing RHEL for Edge images

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.

Additional resources

Chapter 3. Updating 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 RHEL for Edge image containing the new version of MicroShift and any associated optional RPMs. 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.16 or from 4.16.0 to 4.16.1.

Red Hat Device Edge release compatibility matrix

RHEL for Edge Version(s)	MicroShift Version	MicroShift Release Status	Supported MicroShift Version→MicroShift Version Updates
9.4	4.16	Generally Available	4.16.0→4.16.z, 4.14→4.16 and 4.15→4.16
9.2, 9.3	4.15	Generally Available	4.15.0→4.15.z, 4.14→4.15 and 4.15→4.16
9.2, 9.3	4.14	Generally Available	4.14.0→4.14.z, 4.14→4.15 and 4.14→4.16
9.2	4.13	Technology Preview	None
8.7	4.12	Developer Preview	None

Note

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.

Note

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.

Note

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

Procedure

Create an Image Builder configuration file for adding the rhocp-4.16 RPM repository source required to pull MicroShift RPMs by running the following command:

$ cat > rhocp-4.16.toml <<EOF
id = "rhocp-4.16"
name = "Red Hat OpenShift Container Platform 4.16 for RHEL 9"
type = "yum-baseurl"
url = "https://cdn.redhat.com/content/dist/layered/rhel9/$(uname -m)/rhocp/4.16/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.16.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:
- Building a RHEL for Edge commit update
Update the host to use the new image of RHEL for Edge. To determine the steps required, use the following documentation:
- Deploying RHEL for Edge image updates
Reboot the host to apply updates by running the following command:
```
$ sudo systemctl reboot
```

Chapter 4. About updating Red Hat build of MicroShift RPMs manually

Updating Red Hat build of MicroShift for non-OSTree systems such as Red Hat Enterprise Linux (RHEL) requires downloading then updating the RPMs. For patch releases, such as 4.16.1 to 4.16.2, download and update the RPMs. For minor-version release updates, add the step of enabling the update repository using your subscription manager.

Important

MicroShift updates are supported with a maximum of two minor versions. For example, you can update to 4.16 from 4.14 in a single step. Updating 4.14 to 4.15 first is not required.

Note

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

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.

Note

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

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.

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.15 to 4.16.

Important

You can only update MicroShift from one version to the next in sequence. Jumping minor versions is not supported. For example, must update 4.15 to 4.16.

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.

Note

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.16-for-rhel-9-$(uname -m)-rpms \
    --enable fast-datapath-for-rhel-9-$(uname -m)-rpms

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

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

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

Backup and restore

Chapter 5. Listing RPM update package contents

You can preview the contents of a MicroShift RPM package update before installing.

5.1. Listing the contents of the MicroShift RPM release package

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

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.16.* 1

1: Replace the example value 4.16.* with the major and minor release numbers you are interested in.

Example output

Updating Subscription Management repositories.
microshift-release-info-0:4.16.0-202406260523.p0.gc5a37df.assembly.4.16.0.el9.noarch
microshift-release-info-0:4.16.1-202406281132.p0.g8babeb9.assembly.4.16.1.el9.noarch
microshift-release-info-0:4.16.10-202408291007.p0.g6e4ee4d.assembly.4.16.10.el9.noarch
microshift-release-info-0:4.16.2-202407040825.p0.g2e0407e.assembly.4.16.2.el9.noarch
microshift-release-info-0:4.16.3-202407111123.p0.ge4206d3.assembly.4.16.3.el9.noarch
microshift-release-info-0:4.16.4-202407191908.p0.g057a9af.assembly.4.16.4.el9.noarch
microshift-release-info-0:4.16.5-202407250951.p0.g0afcb57.assembly.4.16.5.el9.noarch
microshift-release-info-0:4.16.6-202408010822.p0.gc4ded66.assembly.4.16.6.el9.noarch
microshift-release-info-0:4.16.7-202408081107.p0.g0597bb8.assembly.4.16.7.el9.noarch
microshift-release-info-0:4.16.8-202408150851.p0.gc8a3bb1.assembly.4.16.8.el9.noarch
microshift-release-info-0:4.16.9-202408220842.p0.gefa92a2.assembly.4.16.9.el9.noarch

Download the RPM package you want by running the following command:
```
$ sudo dnf download microshift-release-info-<release_version> 1
```
1
Replace <release_version> with the numerical value of the release you are deploying, using the entire version number, for example, 4.16.0.
Example output
```
microshift-release-info-4.16.0.-202311101230.p0.g7dc6a00.assembly.4.16.0.el9.noarch.rpm 1
```
1
Your output should contain the date and commit ID.

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

$ rpm2cpio <microshift_release_info> | cpio -idmv 1

1: Replace <microshift_release_info> with the name of the RPM package from the previous step. For example, microshift-release-info-4.16.10-202408291007.p0.g6e4ee4d.assembly.4.16.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

List the contents by running the following command:

$ cat ./usr/share/microshift/release/release-x86_64.json

Example output

{
  "release": {
    "base": "4.16.10"
  },
  "images": {
    "cli": "....
# ...

Legal Notice

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.

Updating

Updating MicroShift clusters

Chapter 1. About Red Hat build of MicroShift updates

1.1. Understanding MicroShift updates

1.1.1. RPM OSTree updates

1.1.2. Manual RPM updates

1.1.3. Checking version update path

Chapter 2. Update options with Red Hat build of MicroShift and Red Hat Device Edge

2.1. Checking version update path

2.2. Standalone MicroShift updates

2.2.1. RPM-OSTree updates

2.2.2. Manual RPM updates

2.3. Standalone RHEL for Edge updates

2.4. Simultaneous MicroShift and operating system updates

Chapter 3. Updating RPMs on an OSTree system

3.1. Applying updates on an OSTree system

Chapter 4. About updating Red Hat build of MicroShift RPMs manually

4.1. Applying patch updates using RPMs

4.2. Applying minor-version updates with RPMs

Chapter 5. Listing RPM update package contents

5.1. Listing the contents of the MicroShift RPM release package

Legal Notice

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links