Chapter 4. Troubleshoot updates
To troubleshoot MicroShift updates, use the following guide.
You can only update MicroShift from one minor version to the next in sequence. For example, you must update 4.14 to 4.15.
4.1. Troubleshooting MicroShift updates
In some cases, MicroShift might fail to update. In these events, it is helpful to understand failure types and how to troubleshoot them.
4.1.1. Update path is blocked by MicroShift version sequence
MicroShift requires serial updates. Attempting to update MicroShift by skipping a minor version fails:
-
For example, if your current version is
4.14.5, but you try to update from that version to4.16.0, the message,executable (4.16.0) is too recent compared to existing data (4.14.5): version difference is 2, maximum allowed difference is 1appears and MicroShift fails to start.
In this example, you must first update 4.14.5 to a version of 4.15, and then you can upgrade to 4.16.0.
4.1.2. Update path is blocked by version incompatibility
RPM dependency errors result if a MicroShift update is incompatible with the version of Red Hat Enterprise Linux for Edge (RHEL for Edge) or Red Hat Enterprise Linux (RHEL).
Check the following compatibility table:
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 | MicroShift Version | MicroShift Release Status | MicroShift Supported Updates |
| 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 |
Check the following update paths:
Red Hat build of MicroShift update paths
- Generally Available Version 4.14.0 to 4.14.z on RHEL for Edge 9.2
- Generally Available Version 4.14.0 to 4.14.z on RHEL 9.2
4.1.3. OSTree update failed
If you updated on an OSTree system, the greenboot health check automatically logs and acts on system health. A failure can be indicated by a system rollback by greenboot. In cases where the update failed, but greenboot did not complete a system rollback, you can troubleshoot using the RHEL for Edge documentation linked in the "Additional resources" section that follows this content.
- Checking the greenboot logs manually
Manually check the greenboot logs to verify system health by running the following command:
$ sudo systemctl restart --no-block greenboot-healthcheck && sudo journalctl -fu greenboot-healthcheck
4.1.4. Manual RPM update failed
If you updated by using RPMs on a non-OSTree system, an update failure can be indicated by greenboot, but the health checks are only informative. Checking the system logs is the next step in troubleshooting a manual RPM update failure. You can use greenboot and sos report to check both the MicroShift update and the host system.
4.2. Checking journal logs after updates
In some cases, MicroShift might fail to update. In these events, it is helpful to understand failure types and how to troubleshoot them. The journal logs can assist in diagnosing update failures.
The default configuration of the systemd journal service stores data in a volatile directory. To persist system logs across system starts and restarts, enable log persistence and set limits on the maximum journal data size.
Procedure
Check the MicroShift journal logs by running the following command:
$ sudo journalctl -u microshift
Check the greenboot journal logs by running the following command:
$ sudo journalctl -u greenboot-healthcheck
Check the journal logs for a boot of a specific service by running the following command:
$ sudo journalctl --boot <boot> -u <service-name>
Examining the comprehensive logs of a specific boot uses two steps. First list the boots, then select the one you want from the list you obtained:
List the boots present in the journal logs by running the following command:
$ sudo journalctl --list-boots
Check the journal logs for the boot you want by running the following command:
$ sudo journalctl --boot <-my-boot-number>
4.3. Checking the status of greenboot health checks
Check the status of greenboot health checks before making changes to the system or during troubleshooting. You can use any of the following commands to help you ensure that greenboot scripts have finished running.
Procedure
To see a report of health check status, use the following command:
$ systemctl show --property=SubState --value greenboot-healthcheck.service
-
An output of
startmeans that greenboot checks are still running. -
An output of
exitedmeans that checks have passed and greenboot has exited. Greenboot runs the scripts in thegreen.ddirectory when the system is a healthy state. -
An output of
failedmeans that checks have not passed. Greenboot runs the scripts inred.ddirectory when the system is in this state and might restart the system.
-
An output of
To see a report showing the numerical exit code of the service where
0means success and non-zero values mean a failure occurred, use the following command:$ systemctl show --property=ExecMainStatus --value greenboot-healthcheck.service
To see a report showing a message about boot status, such as
Boot Status is GREEN - Health Check SUCCESS, use the following command:$ cat /run/motd.d/boot-status
