OSDOCS-11139: updates Updating for MicroShift 4.17

Author: ShaunaDiaz

_topic_maps/_topic_map_ms.yml

@@ -59,8 +59,6 @@ Name: Updating
 Dir: microshift_updating
 Distros: microshift
 Topics:
-- Name: About updates
-  File: microshift-about-updates
 - Name: Update options
   File: microshift-update-options
 - Name: Updates with rpm-ostree systems

microshift_updating/microshift-about-updates.adoc

@@ -6,17 +6,14 @@ include::_attributes/attributes-microshift.adoc[]
 
 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-update-paths-snip.adoc[leveloffset=+1]
-
-[IMPORTANT]
-====
-Updates of {microshift-short} 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.
-====
-
 [id="microshift-update-options-standalone-updates_{context}"]
 == Standalone {microshift-short} updates
 Consider the following when planning to update {microshift-short}:
@@ -25,9 +22,19 @@ Consider the following when planning to update {microshift-short}:
 * {op-system} 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
-You can update {microshift-short} on an `rpm-ostree` system such as {op-system-ostree} by building a new image containing the new version of {microshift-short}. Ensure that the version of the operating system you want to use is compatible with the new version of {microshift-short} that you update to.
+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.
 
 The following features are available in the {op-system-ostree} update path:
 
@@ -48,10 +55,19 @@ To understand more about Greenboot, see the following documentation:
 
 [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 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:
+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]
 
+[WARNING]
+====
+Keeping versions in a supported configuration of {op-system-bundle} can require updating {microshift-short} and {op-system} at the same time. Ensure that your version of {op-system} is compatible with the version of {microshift-short} you are updating to, especially if you are updating {microshift-short} across two minor versions. Otherwise, you can create an unsupported configuration, break your cluster, or both.
+====
+
 [id="microshift-update-options-standalone-rhel-updates_{context}"]
 == Standalone {op-system-ostree} updates
 You can update {op-system-ostree} or {op-system} 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.
@@ -63,7 +79,12 @@ You can update {op-system-ostree} or {op-system} without updating {microshift-sh
 
 [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} and update {microshift-short} at the same time, on the condition that the versions are compatible. Check for compatibility before beginning an update. First use the {op-system-ostree} and {op-system} documentation specific to your update path to plan and update the operating system. Then use the {microshift-short} update type specific to your update path.
+You can update {op-system-ostree} or {op-system} 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} 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} and {microshift-short} versions.
+. Use the {microshift-short} update type specific to your update path.
 
 //additional resources for updating RHEL and MicroShift
 [role="_additional-resources"]

microshift_updating/microshift-update-options.adoc

@@ -6,12 +6,7 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-Updating {product-title} for non-OSTree systems such as {op-system-base-full} requires downloading then updating the RPMs. For patch releases, such as 4.17.1 to 4.17.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-short} 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.
-====
+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.
 
 [NOTE]
 ====

microshift_updating/microshift-update-rpms-manually.adoc

@@ -8,13 +8,11 @@ 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.0 to 4.17.1.
-
-include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1]
+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.
 
 [NOTE]
 ====
-Downgrades are not supported. The following procedure is for upgrades only.
+Downgrades other than automatic rollbacks are not supported. The following procedure is for updates only.
 ====
 
 include::modules/microshift-updating-rpms-ostree.adoc[leveloffset=+1]

microshift_updating/microshift-update-rpms-ostree.adoc

@@ -4,13 +4,16 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="microshift-updates-rpms-ostree_{context}"]
-= Applying updates on an OSTree system
+= Applying updates on an rpm-ostree system
 
-To update {microshift-short} on an `rpm-ostree` system such as {op-system-ostree-first}, embed the new version of {microshift-short} 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 {op-system-ostree} documentation. The {op-system-ostree} 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.
+To update {microshift-short} on an `rpm-ostree` system such as {op-system-ostree-first}, embed the new version of {microshift-short} on a new operating system image.
 
-[NOTE]
+* Back up and system rollback are automatic with this update type.
+* You can also use this workflow to update applications running in the {microshift-short} cluster. Ensure compatibility between the application and the adjacent versions of {microshift-short} and {op-system-ostree} before starting an update.
+
+[IMPORTANT]
 ====
-You can also use this workflow to update applications running in the {microshift-short} cluster. Ensure compatibility between the application and the adjacent versions of {microshift-short} and {op-system-ostree} before starting an update.
+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 {op-system-ostree} documentation. The {op-system-ostree} documentation is your resource for specific details on building an updated operating system image.
 ====
 
 .Prerequisites
@@ -19,9 +22,9 @@ You can also use this workflow to update applications running in the {microshift
 * You have root user access to the host.
 * The version of {microshift-short} you have is compatible with the {op-system-ostree} image you are preparing to use.
 
-[NOTE]
+[IMPORTANT]
 ====
-You cannot downgrade {microshift-short} with this process. Downgrades are not supported.
+You cannot downgrade {microshift-short} with this process. Downgrades other than automatic rollbacks are not supported.
 ====
 
 .Procedure

modules/microshift-updating-rpms-ostree.adoc

@@ -7,42 +7,32 @@
 
 .{op-system-bundle} release compatibility matrix
 
-{op-system-base-full} and {microshift-short} 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-short} from 4.14 to 4.16 requires a {op-system} update. Supported configurations of {op-system-bundle} use verified releases for each together as listed in the following table:
+{op-system-base-full} and {microshift-short} work together as a single solution for device-edge computing. You can update each component separately, but the product versions must be compatible. Supported configurations of {op-system-bundle} use verified releases for each together as listed in the following table:
 
-[cols="4",%autowidth]
+[cols="4",cols="~,~,~,20h"]
 |===
-^|*{op-system-ostree} Version(s)*
+^|*{op-system} Version(s)*
 ^|*{microshift-short} Version*
 ^|*{microshift-short} Release Status*
-^|*Supported {microshift-short} Version→{microshift-short} Version Updates*
+^|*Supported {microshift-short} Version{nbsp}→{nbsp}Version Updates*
 
 ^|9.4
 ^|4.17
 ^|Generally Available
-^|4.17.0→4.17.z and 4.16→4.17
+^|4.17.0{nbsp}→{nbsp}4.17.z
 
 ^|9.4
 ^|4.16
 ^|Generally Available
-^|4.16.0→4.16.z, 4.14→4.16, 4.15→4.16 and 4.16→4.17
+^|4.16.0{nbsp}→{nbsp}4.16.z, 4.16{nbsp}→{nbsp}4.17
 
 ^|9.2, 9.3
 ^|4.15
 ^|Generally Available
-^|4.15.0→4.15.z, 4.14→4.15 and 4.15→4.16
+^|4.15.0{nbsp}→{nbsp}4.15.z, 4.15{nbsp}→{nbsp}4.16, 4.15{nbsp}→{nbsp}4.17
 
 ^|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
+^|4.14.0{nbsp}→{nbsp}4.14.z, 4.14{nbsp}→{nbsp}4.15, 4.14{nbsp}→{nbsp}4.16
 |===

snippets/microshift-rhde-compatibility-table-snip.adoc

@@ -6,24 +6,24 @@
 :_mod-docs-content-type: SNIPPET
 
 [id="microshift-about-updates-checking-version-update-path_{context}"]
-= Checking version update path
+= Checking the {microshift-short} version update path
 
 Before updating {microshift-short} or {op-system}, determine the compatibilities. Plan for the versions of each that you intend to use.
 
 *{product-title} update paths*
 
 {microshift-short} version 4.17::
-* Version 4.17 to 4.17.z on {op-system} or {op-system-ostree} 9.4
+* Version 4.17{nbsp}→{nbsp}4.17.z on {op-system} 9.4
 
 {microshift-short} version 4.16::
-* Version 4.16 on {op-system} or {op-system-ostree} 9.4 to 4.17 on {op-system} or {op-system-ostree} 9.4
-* Version 4.16 to 4.16.z on {op-system} or {op-system-ostree} 9.4
+* Version 4.16{nbsp}→{nbsp}4.17 on {op-system} 9.4
+* Version 4.16{nbsp}→{nbsp}4.16.z on {op-system} 9.4
 
 {microshift-short} version 4.15::
-* Version 4.15 on {op-system} or {op-system-ostree} 9.2 or 9.3 to 4.16 on {op-system} or {op-system-ostree} 9.4
-* Version 4.15 to 4.15.z on {op-system} or {op-system-ostree} 9.2 or 9.3
+* Version 4.15 on {op-system} 9.2 or 9.3{nbsp}→{nbsp}4.16 on {op-system} 9.4
+* Version 4.15{nbsp}→{nbsp}4.15.z on {op-system} 9.2 or 9.3
 
 {microshift-short} version 4.14::
-* Version 4.14 on {op-system} or {op-system-ostree} 9.2 or 9.3 to 4.16 on {op-system} or {op-system-ostree} 9.4
-* Version 4.14 to 4.15 on {op-system} or {op-system-ostree} 9.2 or 9.3
-* Version 4.14 to 4.14.z on {op-system} or {op-system-ostree} 9.2 or 9.3
+* Version 4.14 on {op-system} 9.2 or 9.3{nbsp}→{nbsp}4.16 on {op-system} 9.4
+* Version 4.14{nbsp}→{nbsp}4.15 on {op-system} 9.2 or 9.3
+* Version 4.14{nbsp}→{nbsp}4.14.z on {op-system} 9.2 or 9.3