openshift · ShaunaDiaz · Oct 14, 2025 · Oct 8, 2025
diff --git a/microshift_troubleshooting/microshift-installing-troubleshooting.adoc b/microshift_troubleshooting/microshift-installing-troubleshooting.adoc
@@ -10,7 +10,7 @@ To troubleshoot a failed {microshift-short} installation, you can run an sos rep
 
 include::modules/microshift-gathering-sos-report.adoc[leveloffset=+1]
 
-[id="additional-resources_microshift-installing-troubleshooting_{context}"]
+[id="additional-resources_microshift-installing-troubleshooting"]
 [role="_additional-resources"]
 == Additional resources
 * xref:../microshift_support/microshift-sos-report.adoc#microshift-sos-report[About {microshift-short} sos reports]

diff --git a/microshift_troubleshooting/microshift-troubleshoot-updates.adoc b/microshift_troubleshooting/microshift-troubleshoot-updates.adoc
@@ -1,12 +1,14 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-troubleshoot-updates"]
-= Troubleshoot updates
+= Troubleshooting updates
+
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-troubleshoot-updates
 
 toc::[]
 
-To troubleshoot {microshift-short} updates, use the following guide.
+[role="_abstract"]
+To troubleshoot {microshift-short} updates, you can check update paths, review journal and greenboot health check logs, and use other techniques to help you solve update problems.
 
 //[IMPORTANT]
 //====
@@ -15,16 +17,16 @@ To troubleshoot {microshift-short} updates, use the following guide.
 
 include::modules/microshift-updates-troubleshooting.adoc[leveloffset=+1]
 
-//additional resources for troubleshooting module
+include::modules/microshift-check-journal-logs-updates.adoc[leveloffset=+1]
+
+include::modules/microshift-greenboot-check-status.adoc[leveloffset=+1]
+
+[id="additional-resources_microshift-troubleshoot-updates"]
 [role="_additional-resources"]
-.Additional resources
+== Additional resources
 * xref:../microshift_install_get_ready/microshift-greenboot.adoc#microshift-greenboot-systemd-journal-data_microshift-greenboot[Enabling `systemd` journal service data persistency]
 * xref:../microshift_troubleshooting/microshift-version.adoc#microshift-version[Checking the MicroShift version]
 * xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-service-stopping_microshift-install-rpm[Stopping the MicroShift service]
 * xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-service-starting_microshift-install-rpm[Starting the MicroShift service]
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/index[Composing, installing, and managing RHEL for Edge images]
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/composing_installing_and_managing_rhel_for_edge_images/index#rolling_back_rhel_for_edge_images[Rolling back RHEL for Edge images]
-
-include::modules/microshift-check-journal-logs-updates.adoc[leveloffset=+1]
-
-include::modules/microshift-greenboot-check-status.adoc[leveloffset=+1]
+* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/index[Composing, installing, and managing RHEL for Edge images]
+* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/composing_installing_and_managing_rhel_for_edge_images/index#rolling_back_rhel_for_edge_images[Rolling back RHEL for Edge images]
diff --git a/microshift_updating/microshift-list-update-contents.adoc b/microshift_updating/microshift-list-update-contents.adoc
@@ -1,11 +1,13 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-list-update-contents"]
 = Listing RPM update package contents
+
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-list-update-contents
 
 toc::[]
 
-You can preview the contents of a {microshift-short} RPM package update before installing.
+[role="_abstract"]
+You can preview the contents of a {microshift-short} RPM package update before installing. This helps you make sure that the update you are planning is a supported configuration of {op-system-bundle}.
 
 include::modules/microshift-get-rpm-release-info.adoc[leveloffset=+1]
diff --git a/microshift_updating/microshift-update-options.adoc b/microshift_updating/microshift-update-options.adoc
@@ -1,96 +1,35 @@
 :_mod-docs-content-type: ASSEMBLY
-include::_attributes/attributes-microshift.adoc[]
 [id="microshift-update-options"]
-= Update options with {product-title} and {op-system-bundle}
+= Update options for Red Hat Device Edge
+
+include::_attributes/attributes-microshift.adoc[]
 :context: microshift-update-options
 
 toc::[]
 
-Updates are supported on {product-title} beginning with the General Availability version 4.14.
-
-[id="red-hat-device-edge-updates_{context}"]
-== {op-system-bundle} updates
-You can update {op-system-ostree-first} images or {op-system-base-full} with or without updating the {product-title} version if the version combination is supported. See the following table for details:
-
-include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1]
-
-include::snippets/microshift-unsupported-config-warn.adoc[leveloffset=+1]
-
-[id="microshift-update-options-standalone-updates_{context}"]
-== Standalone {microshift-short} updates
-Consider the following when planning to update {microshift-short}:
-
-* You can potentially update {microshift-short} without reinstalling your applications and Operators.
-* {op-system-base} or {op-system-ostree} updates are only required to update {microshift-short} if the existing operating system is not compatible with the new version of {microshift-short} that you want to use.
-* {microshift-short} 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.
-
-include::snippets/microshift-update-paths-snip.adoc[leveloffset=+1]
-
-[NOTE]
-====
-Only `rpm-ostree` updates include automatic rollbacks.
-====
-
-[id="microshift-update-options-rpm-ostree-updates_{context}"]
-=== RPM-OSTree updates
-Using the {op-system-ostree} `rpm-ostree` update path allows for automated backup and system rollback in case any part of the update fails.
+[role="_abstract"]
+To update {op-system-bundle}, you can update both {product-title} and {op-system-base-full}, 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.
 
-* You can update {microshift-short} on an `rpm-ostree` system such as {op-system-ostree} by building a new system image containing the new version of {microshift-short}.
-* The `rpm-ostree` image can be the same version or an updated version, but the versions of {op-system-ostree} and {microshift-short} must be compatible.
+include::modules/microshift-rhde-updates.adoc[leveloffset=+1]
 
-The following features are available in the {op-system-ostree} update path:
+include::modules/microshift-standalone-updates.adoc[leveloffset=+1]
 
-* 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-short} using this update type.
-* The image you build can contain other updates as needed.
+include::modules/microshift-rpm-ostree-updates.adoc[leveloffset=+2]
 
-To begin a {microshift-short} update by embedding in a {op-system-ostree} image, use the procedures in the following documentation:
-
-* xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an OSTree system]
-
-To understand more about Greenboot, see the following documentation:
-
-* xref:../microshift_install_get_ready/microshift-greenboot.adoc#microshift-greenboot[The Greenboot health check]
-* xref:../microshift_running_apps/microshift-greenboot-workload-scripts.adoc#microshift-greenboot-workload-scripts[Greenboot workload health check scripts]
-
-[id="microshift-update-options-manual-rpm-updates_{context}"]
-=== Manual RPM updates
-You can update {microshift-short} manually on a non-OSTree system such as {op-system-base-full} by updating the RPMs.
-
-* To complete this update type, use the subscription manager to enable the repository that contains 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:
-
-* xref:../microshift_updating/microshift-update-rpms-manually.adoc#microshift-update-rpms-manually[About updating MicroShift RPMs manually]
+include::modules/microshift-manual-rpm-updates.adoc[leveloffset=+2]
 
 include::modules/microshift-updates-rhde-config-rhel-repos.adoc[leveloffset=+3]
 
-[id="microshift-update-options-standalone-rhel-updates_{context}"]
-== Standalone {op-system-ostree} updates
-You can update {op-system-ostree} or {op-system-base} without updating {microshift-short}, on the condition that the two versions are compatible. Check compatibilities before beginning an update. Use the {op-system-ostree} documentation specific to your update path.
+include::modules/microshift-standalone-rhel-updates.adoc[leveloffset=+1]
 
-//additional resources for updating RHEL alone
-[role="_additional-resources"]
-.Additional resources
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/index[Managing RHEL for Edge images]
-
-[id="microshift-update-options-simultaneous-microshift-rhel-updates_{context}"]
-== Simultaneous {microshift-short} and operating system updates
-You can update {op-system-ostree} or {op-system-base} and update {microshift-short} at the same time, on the condition that the versions are compatible. Use the following workflow:
-
-. Check for compatibility before beginning an update.
-. Use the {op-system-ostree} and {op-system-base} documentation specific to your update path to plan and update the operating system.
-. Enable the correct {microshift-short} repository to ensure alignment between your {op-system-base} and {microshift-short} versions.
-. Use the {microshift-short} update type specific to your update path.
+include::modules/microshift-simultaneous-microshift-rhel-updates.adoc[leveloffset=+1]
 
-//additional resources for updating RHEL and MicroShift
+[id="additional-resources_microshift-update-options"]
 [role="_additional-resources"]
-.Additional resources
+== Additional resources
+
 * link:https://access.redhat.com/articles/rhel-eus#c5[How to Access EUS]
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/index[Composing a customized RHEL system image]
-* xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an OSTree system]
-* xref:../microshift_updating/microshift-update-rpms-manually.adoc#microshift-update-rpms-manually[Applying updates manually with RPMs]
-* xref:../microshift_install_get_ready/microshift-greenboot.adoc#microshift-greenboot[The Greenboot system health check]
-* xref:../microshift_running_apps/microshift-greenboot-workload-scripts.adoc#microshift-greenboot-workload-scripts[Greenboot workload scripts]
+* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/index[Composing a customized RHEL system image]
+* xref:../microshift_install_get_ready/microshift-greenboot.adoc#microshift-greenboot[The greenboot system health check]
+* xref:../microshift_running_apps/microshift-greenboot-workload-scripts.adoc#microshift-greenboot-workload-scripts[Greenboot workload health checks]
+
diff --git a/microshift_updating/microshift-update-rpms-manually.adoc b/microshift_updating/microshift-update-rpms-manually.adoc
@@ -1,12 +1,14 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-update-rpms-manually"]
-= About updating RPMs manually
+= Updating RPMs manually
+
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-update-rpms-manually
 
 toc::[]
 
-Updating {product-title} for non-OSTree systems such as {op-system-base-full} requires updating the RPMs. For patch releases, such as 4.17.1 to 4.17.2, simply update the RPMs. For minor-version release updates, add the step of enabling the update repository using your subscription manager.
+[role="_abstract"]
+Updating {product-title} for non-image-based {op-system-base-full} systems requires updating the RPMs. For patch releases, such as {product-version}.1 to {product-version}.2, simply update the RPMs. For minor-version release updates, add the step of enabling the update repository by using your subscription manager.
 
 [NOTE]
 ====
@@ -17,7 +19,8 @@ include::modules/microshift-updating-rpms-z.adoc[leveloffset=+1]
 
 include::modules/microshift-updating-rpms-y.adoc[leveloffset=+1]
 
-//additional resources for backup and restore
+[id="additional-resources_microshift-update-rpms-manually"]
 [role="_additional-resources"]
-.Additional resources
-* xref:../microshift_backup_and_restore/microshift-backup-and-restore.adoc#microshift-backup-and-restore[Backup and restore]
+== Additional resources
+
+* xref:../microshift_backup_and_restore/microshift-backup-and-restore.adoc#microshift-backup-and-restore[Backup and restore]
diff --git a/microshift_updating/microshift-update-rpms-ostree.adoc b/microshift_updating/microshift-update-rpms-ostree.adoc
@@ -1,18 +1,20 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-update-rpms-ostree"]
-= Updating RPMs on an OSTree system
+= Updating RPMs on a RHEL for Edge system
+
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-update-rpms-ostree
 
 toc::[]
 
-Updating {microshift-short} on an `rpm-ostree` system such as {op-system-ostree-first} requires building a new {op-system-ostree} image containing the new version of {microshift-short} and any associated optional RPMs. After you have the `rpm-ostree` image with {microshift-short} 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.16 to 4.17 or from 4.17.2 to 4.17.3.
+[role="_abstract"]
+You can update {microshift-short} on {op-system-ostree-first} by embedding the new version of {microshift-short} on a new operating system image. The procedures are the same for minor-version and patch updates. For example, use the same steps to upgrade from 4.16 to 4.17 or from {ocp-version}.2 to {ocp-version}.3.
 
 [NOTE]
 ====
 Downgrades other than automatic rollbacks are not supported. The following procedure is for updates only.
 ====
 
+include::modules/microshift-updates-rpms-ostree-con.adoc[leveloffset=+1]
+
 include::modules/microshift-updating-rpms-ostree.adoc[leveloffset=+1]
diff --git a/microshift_welcome/index.adoc b/microshift_welcome/index.adoc
@@ -49,7 +49,8 @@ In addition to standard Kubernetes APIs, {microshift-short} includes a small sub
 
 include::modules/microshift-k8s-apis.adoc[leveloffset=+1]
 
+[id="additional-resources_microshift-welcome-index"]
 [role="_additional-resources"]
-.Additional resources
+== Additional resources
 * xref:../microshift_rest_api/index.adoc#api-index[API index]
 * link:https://www.redhat.com/en/technologies/cloud-computing/openshift/kubernetes-engine[{oke}]
diff --git a/modules/microshift-check-journal-logs-updates.adoc b/modules/microshift-check-journal-logs-updates.adoc
@@ -6,12 +6,8 @@
 [id="microshift-check-journal-logs-updates_{context}"]
 = Checking journal logs after updates
 
-In some cases, {microshift-short} 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.
-
-[NOTE]
-====
-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.
-====
+[role="_abstract"]
+Journal logs can assist in diagnosing {microshift-short} 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
 

diff --git a/modules/microshift-get-rpm-release-info.adoc b/modules/microshift-get-rpm-release-info.adoc
@@ -6,6 +6,7 @@
 [id="microshift-get-rpm-release-info_{context}"]
 = Listing the contents of the {microshift-short} RPM release package
 
+[role="_abstract"]
 To see the images included with a {microshift-short} release, you can list the contents of the `microshift-release-info` RPM by downloading and unpacking the RPM.
 
 .Prerequisites

diff --git a/modules/microshift-greenboot-check-status.adoc b/modules/microshift-greenboot-check-status.adoc
@@ -6,7 +6,8 @@
 [id="microshift-greenboot-check-status_{context}"]
 = 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.
+[role="_abstract"]
+Check the status of greenboot health checks before making changes to the system and while troubleshooting. You can use any of the following commands to help you ensure that greenboot scripts have finished running.
 
 .Procedure
 

diff --git a/modules/microshift-manual-rpm-updates.adoc b/modules/microshift-manual-rpm-updates.adoc
@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+//microshift_updating/microshift-update-options.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-manual-rpm-updates_{context}"]
+= Manual RPM updates
+
+[role="_abstract"]
+You can update {microshift-short} manually on {op-system-base-full} 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:
+
+* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/updating/microshift-update-rpms-manually[About updating MicroShift RPMs manually]
diff --git a/modules/microshift-rhde-updates.adoc b/modules/microshift-rhde-updates.adoc
@@ -0,0 +1,14 @@
+// Module included in the following assemblies:
+//
+//microshift_updating/microshift-update-options.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-rhde-updates_{context}"]
+= {op-system-bundle} updates
+
+[role="_abstract"]
+You can update {op-system-base-full} operating system independently of your {product-title} version if the version combination is supported. See the following table for details:
+
+include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1]
+
+include::snippets/microshift-unsupported-config-warn.adoc[leveloffset=+1]
diff --git a/modules/microshift-rpm-ostree-updates.adoc b/modules/microshift-rpm-ostree-updates.adoc
@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+//microshift_updating/microshift-update-options.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-rpm-ostree-updates_{context}"]
+= Updating {microshift-short} on {op-system-ostree}
+
+[role="_abstract"]
+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 {op-system-ostree} deployment.
+
+* You can update {microshift-short} on an `rpm-ostree` system such as {op-system-ostree} by building a new system image containing the new version of {microshift-short}.
+* The `rpm-ostree` image can be the same version or an updated version, but the versions of {op-system-ostree} and {microshift-short} must be compatible.
+
+The following features are available in the {op-system-ostree} 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-short} using this update type.
+* The image you build can contain other updates as needed.
+
+To begin a {microshift-short} update by embedding the new version in a {op-system-ostree} image, use the procedures in the following documentation:
+
+* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/updating/microshift-update-rpms-ostree#microshift-updates-rpms-ostree_microshift-update-rpms-ostree[Applying updates on a RHEL for Edge system]
+
+To understand more about greenboot, see the following documentation:
+
+* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/getting_ready_to_install_microshift/microshift-greenboot[The greenboot health check framework]
+
+* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/running_applications/microshift-greenboot-workload-health-checks[Using greenboot for application and workload health checks]