openshift · ShaunaDiaz · Oct 13, 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,25 +1,27 @@
 :_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.
 
 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,102 +1,37 @@
 :_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.
-
-[NOTE]
-====
-Only `rpm-ostree` updates include automatic rollbacks.
-====
-
-[id="microshift-update-options-rpm-ostree-updates_{context}"]
-=== {op-system-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.
-
-* 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.
+[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.
 
-The following features are available in the {op-system-ostree} update path:
+include::modules/microshift-rhde-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-standalone-updates.adoc[leveloffset=+1]
 
-To begin a {microshift-short} update by embedding in a {op-system-ostree} image, use the procedures in the following documentation:
+include::modules/microshift-rpm-ostree-updates.adoc[leveloffset=+2]
 
-* 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-health-checks.adoc#microshift-greenboot-workload-health-checks[Greenboot workload health checks]
-
-[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://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]
-
-[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]
 
-[id="microshift-update-options-edge-to-image_{context}"]
-== Migrating {microshift-short} from {op-system-ostree} to {op-system-image}
+include::modules/microshift-migrate-rhel-edge-to-image-mode.adoc[leveloffset=+1]
 
-Starting with {microshift-short} 4.19, you can migrate your {microshift-short} node from {op-system-ostree} to {op-system-image} if the versions are compatible. Check compatibilities before beginning a migration. See the {op-system-base} documentation for instructions to migrate your image-based {op-system-base} system.
-//RHEL docs are coming soon
-
-//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://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_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an {op-system-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-health-checks.adoc#microshift-greenboot-workload-health-checks[Greenboot workload health checks]
-//* xref:../microshift_updating/microshift-update-rhel-edge-to-image-mode.adoc#microshift-update-rhel-edge-to-image[Migrating {microshift-short} from {op-system-ostree} to {op-system-image}]
+
diff --git a/microshift_updating/microshift-update-rhel-edge-to-image-mode.adoc b/microshift_updating/microshift-update-rhel-edge-to-image-mode.adoc
@@ -2,17 +2,14 @@
 [id="microshift-update-rhel-edge-to-image-mode"]
 include::_attributes/attributes-microshift.adoc[]
 = Migrating {microshift-short} from {op-system-ostree} to {op-system-image}
+
 :context: microshift-update-rhel-edge-to-image
 
 toc::[]
 
+[role="_abstract"]
 To migrate {microshift-short} from {op-system-ostree-first}, embed {microshift-short} on a new {op-system-image} image.
 
 include::modules/microshift-update-edge-to-image.adoc[leveloffset=+1]
 
-include::modules/microshift-updates-edge-to-image-uid-drift.adoc[leveloffset=+1]
-
-//additional resources for image mode docs in RHEL
-//[role="_additional-resources"]
-//.Additional resources
-//TODO Add RHEL doc links when published
+include::modules/microshift-updates-edge-to-image-uid-drift.adoc[leveloffset=+2]
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-image-based {op-system-base-full} systems requires updating the RPMs. For patch releases, such as 4.20.1 to 4.20.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,11 +1,13 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-update-rpms-ostree"]
 = Updating RPMs on a RHEL for Edge system
+
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-update-rpms-ostree
 
 toc::[]
 
+[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.
 
 include::modules/microshift-updates-rpms-ostree-con.adoc[leveloffset=+1]

diff --git a/microshift_welcome/index.adoc b/microshift_welcome/index.adoc
@@ -50,7 +50,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-migrate-rhel-edge-to-image-mode.adoc b/modules/microshift-migrate-rhel-edge-to-image-mode.adoc
@@ -0,0 +1,11 @@
+
+// Module included in the following assemblies:
+//
+//microshift_updating/microshift-update-options.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-migrate-rhel-edge-to-image-mode_{context}"]
+= Migrating {microshift-short} from {op-system-ostree} to {op-system-image}
+
+[role="_abstract"]
+Starting with {microshift-short} 4.19, you can migrate your {microshift-short} node from {op-system-ostree} to {op-system-image} if the final versions are a supported configuration of {op-system-bundle}. Check compatibilities before beginning a migration. See the {op-system-base} documentation for instructions to migrate your image-based {op-system-base} system.
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]