OSDOCS-6660: add microshift updates

Author: ShaunaDiaz

_attributes/attributes-microshift.adoc

@@ -6,16 +6,17 @@
 :OCP: OpenShift Container Platform
 :ocp-version: 4.14
 :oc-first: pass:quotes[OpenShift CLI (`oc`)]
+:product-title-first: Red Hat build of MicroShift (MicroShift)
 :product-registry: OpenShift image registry
 :product-version: 4.14
 :rhel-major: rhel-9
 :op-system-base-full: Red Hat Enterprise Linux (RHEL)
 :op-system: RHEL
-:op-system-ostree-first: Red Hat Enterprise Linux (RHEL) for Edge
+:op-system-ostree-first: Red Hat Enterprise Linux for Edge (RHEL for Edge)
 :op-system-ostree: RHEL for Edge
 :op-system-version: 9.2
 :op-system-version-major: 9
-:op-system-version-major-short: rhel9
+:op-system-bundle-first: Red Hat Device Edge (RHDE)
 :op-system-bundle: Red Hat Device Edge
 :op-system-bundle-short: RHDE
 :rpm-repo-version: rhocp-4.14

_topic_maps/_topic_map_ms.yml

@@ -56,12 +56,18 @@ Topics:
 - Name: Greenboot health check
   File: microshift-greenboot
 ---
-Name: Updating clusters
+Name: Updating
 Dir: microshift_updating
 Distros: microshift
 Topics:
-- Name: About MicroShift updates
+- Name: About updates
   File: microshift-about-updates
+- Name: Update options
+  File: microshift-update-options
+- Name: Updates with RPM-OSTree systems
+  File: microshift-update-rpms-ostree
+- Name: Manual updates with RPMs
+  File: microshift-update-rpms-manually
 ---
 Name: Support
 Dir: microshift_support
@@ -171,5 +177,9 @@ Topics:
   File: microshift-version
 - Name: Troubleshooting backup and restore
   File: microshift-troubleshoot-backup-restore
+- Name: Troubleshoot the cluster
+  File: microshift-troubleshoot-cluster
+- Name: Troubleshoot updates
+  File: microshift-troubleshoot-updates
 - Name: Additional information
   File: microshift-things-to-know

microshift_troubleshooting/microshift-troubleshoot-cluster.adoc

@@ -0,0 +1,11 @@
+:_content-type: ASSEMBLY
+[id="microshift-troubleshoot-cluster"]
+= Troubleshooting a {product-title} cluster
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-troubleshoot-cluster
+
+toc::[]
+
+To begin troubleshooting a {product-title} cluster, first access the cluster status.
+
+include::modules/microshift-check-cluster-status.adoc[leveloffset=+1]

microshift_troubleshooting/microshift-troubleshoot-updates.adoc

@@ -0,0 +1,28 @@
+:_content-type: ASSEMBLY
+[id="microshift-troubleshoot-updates"]
+= Troubleshoot {product-title} updates
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-troubleshoot-updates
+
+toc::[]
+
+To troubleshoot {product-title} updates, use the following guide.
+
+[IMPORTANT]
+====
+You can only update {product-title} from one minor version to the next in sequence. For example, you must update 4.14 to 4.15.
+====
+
+include::modules/microshift-updates-troubleshooting.adoc[leveloffset=+1]
+
+//additional resources for troubleshooting module
+[role="_additional-resources"]
+.Additional resources
+* xref:../microshift_install/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/microshift-install-rpm.adoc#microshift-service-stopping_microshift-install-rpm[Stopping the MicroShift service]
+* xref:../microshift_install/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]

microshift_updating/microshift-about-updates.adoc

@@ -6,43 +6,37 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-You can update a {product-title} cluster by using the OpenShift CLI (`oc`).
-// This PR is for the book build. Note that the OCP structure consists of a landing page of xrefs to other major sections within the book. MicroShift likely does not require that depth of structure, so starting simply with one page.
+Upgrades are supported on {product-title-first} beginning with the General Availability version 4.14. Supported upgrades include those from one minor version to the next in sequence, for example, from 4.14 to 4.15. Patch updates are also supported from z-stream to z-stream, for example 4.14.1 to 4.14.2.
 
 [id="microshift-about-updates-understanding-microshift-updates"]
 == Understanding {product-title} updates
-{product-title} updates are available as either RPMs or by embedding the {product-title} image in an RPM OSTree blueprint.
-You can update an {product-title} cluster by using the OpenShift CLI (`oc`).
-//Platform administrators can view new update options by looking at the output of the `oc adm upgrade` command.
-//An update begins when...
+{product-title} 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 {product-title} in a new `rpm-ostree` system image such as {op-system-ostree-first}. See * xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an OSTree system]
+* Manually update the RPMs on a non-OSTree system such as {op-system-base-full}. See * xref:../microshift_updating/microshift-update-rpms-manually.adoc#microshift-update-rpms-manually[Applying updates manually with RPMs]
 
 [NOTE]
 ====
-Operators previously installed must be reinstalled using manifests.
+Only `rpm-ostree` updates include automatic rollbacks.
 ====
 
-[id="microshift-about-updates-rpm-updates"]
-=== RPM updates
-Using the RPM update method replaces your existing version. No rollback is possible with this update type.
-//we can call a module here or xref out; not sure the best method for our use case until we have the content
-
 [id="microshift-about-updates-rpm-ostree-updates"]
 === RPM OSTree updates
-Using the RPM OSTree update path allows for system rollback.
-//we can call a module here or xref out; not sure the best method for our use case until we have the content
+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 must build a new `rpm-ostree` image and embed the new {product-title} version in that image. The `rpm-ostree` image can be the same version or an updated version, but the versions of {op-system-ostree} and {product-title} must be compatible.
 
-[id="microshift-about-updates-checking-version-update-compatibility"]
-== Checking version update compatibility
-Before attempting an update, determine which version of {product-title} you have installed. Only the following update paths are supported:
+Check following compatibility table for details:
+
+include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1]
+
+[id="microshift-about-updates-rpm-updates"]
+=== Manual RPM updates
+You can use the manual RPM update path to replace your existing version of {product-title}. The versions of {op-system} and {product-title} must be compatible. Ensuring system health and completing additional system backups are manual processes.
 
-* Version 4.13 to 4.14
-//replace with matrix including RHEL versions?
-//place xref here to version-check assembly
+[id="microshift-about-updates-checking-version-update-path"]
+== Checking version update path
+Before attempting an update of either {op-system-bundle} component, determine which versions of {product-title} and {op-system-ostree} or {op-system} you have installed. Plan for the versions of each that you intend to use.
 
-[id="microshift-about-updates-update-disconnected-environment"]
-== Updating a cluster in a disconnected environment
-//sample topic only
+*{product-title} update paths*
 
-[id="microshift-about-updates-troubleshooting-updates"]
-== Troubleshooting updates
-//sample topic only
+* Generally Available Version 4.14 to 4.14.z on {op-system-ostree} 9.2
+* Generally Available Version 4.14 to 4.14.z on {op-system} 9.2

microshift_updating/microshift-update-options.adoc

@@ -0,0 +1,76 @@
+:_content-type: ASSEMBLY
+[id="microshift-update-options"]
+= Update options with {product-title} and {op-system-bundle}
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-update-options
+
+toc::[]
+
+You can update {op-system-ostree-first} or {op-system-base-full} with or without updating {product-title-first} as long as the two versions are compatible. See the following table for details:
+
+include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1]
+
+*{product-title} update paths*
+
+* Generally Available Version 4.14.0 to 4.14.z on {op-system-ostree} 9.2
+* Generally Available Version 4.14.0 to 4.14.z on {op-system} 9.2
+
+[IMPORTANT]
+====
+Updates of {product-title} from one minor version to the next must be in sequence. For example, you cannot update from 4.14 to 4.16. You must update 4.14 to 4.15.
+====
+
+[id="microshift-update-options-standalone-updates_{context}"]
+== Standalone {product-title} updates
+
+You can update {product-title} without reinstalling the applications you created. {op-system} or {op-system-ostree} updates are also not required to update {product-title}, as long as the existing operating system is compatible with the new version of {product-title} that you want to use.
+
+{product-title} 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.
+
+[id="microshift-update-options-rpm-ostree-updates"]
+=== RPM-OSTree updates
+You can update {product-title} on an `rpm-ostree` system such as {op-system-ostree} by building a new image containing the new version of {product-title}. Ensure that the version of the operating system you want to use is compatible with the new version of {product-title} that you update to.
+
+The following features are available in the {op-system-ostree} update path:
+
+* The system automatically rolls back to a previous healthy system state if the update fails.
+* Applications do not need to be reinstalled.
+* You can update an application without updating {product-title} using this update type.
+* The image you build can contain other updates as needed.
+
+To begin a {product-title} 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/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"]
+=== Manual RPM updates
+You can update {product-title} 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:
+
+* xref:../microshift_updating/microshift-update-rpms-manually.adoc#microshift-update-rpms-manually[About updating MicroShift RPMs manually]
+
+[id="microshift-update-options-standalone-rhel-updates"]
+== Standalone {op-system-ostree} updates
+You can update {op-system-ostree} or {op-system} without updating {product-title}, 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.
+
+//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"]
+== Simultaneous {product-title} and operating system updates
+You can update {op-system-ostree} or {op-system} and update {product-title} 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} documentation specific to your update path to plan and update the operating system. Then use the {product-title} update type specific to your update path.
+
+//additional resources for updating RHEL and MicroShift
+[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]
+* 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/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]

microshift_updating/microshift-update-rpms-manually.adoc

@@ -0,0 +1,24 @@
+:_content-type: ASSEMBLY
+[id="microshift-update-rpms-manually"]
+= About updating {product-title} RPMs manually
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-update-rpms-manually
+
+toc::[]
+
+Updating {product-title-first} for non-OSTree systems such as {op-system-base-full} requires downloading then updating the RPMs. For patch releases, such as 4.14.1 to 4.14.2, download and update the RPMs. For minor-version release updates, add the step of enabling the update repository using your subscription manager.
+
+[IMPORTANT]
+====
+{product-title} updates are supported from one minor version to the next in sequence. For example, you must update 4.14 to 4.15.
+====
+
+For either upgrading with patch updates or a minor-version update, you can back up application data as needed and move the data copy to a secure location.
+
+include::modules/microshift-updating-rpms-z.adoc[leveloffset=+1]
+
+include::modules/microshift-updating-rpms-y.adoc[leveloffset=+1]
+
+//[role="_additional-resources"]
+//.Additional resources
+//TODO: cross reference to backup and restore when merged

microshift_updating/microshift-update-rpms-ostree.adoc

@@ -0,0 +1,20 @@
+:_content-type: ASSEMBLY
+[id="microshift-update-rpms-ostree"]
+= About updating {product-title} RPMs on an OSTree system
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-update-rpms-ostree
+
+toc::[]
+
+Updating {product-title-first} on an `rpm-ostree` system such as {op-system-ostree-first} requires building a new operating system image containing the new version of {product-title}. After you have the `rpm-ostree` image with {product-title} embedded, direct your system to boot into that operating system image.
+
+The procedures are the same for patches and minor-version updates. For example, use the same steps to upgrade from 4.14.0 to 4.14.1 or from 4.14 to 4.15.
+
+include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1]
+
+[NOTE]
+====
+Downgrades are not supported. The following procedure is for upgrades only.
+====
+
+include::modules/microshift-updating-rpms-ostree.adoc[leveloffset=+1]

modules/microshift-adding-repos-to-image-builder.adoc

@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
-// microshift/microshift-embed-into-rpm-ostree.adoc
+// * microshift/microshift-embed-into-rpm-ostree.adoc
+// * microshift/microshift-update-rpms-ostree.adoc
 
 :_content-type: PROCEDURE
 [id="adding-microshift-repos-image-builder_{context}"]
@@ -24,7 +25,7 @@ $ cat > {rpm-repo-version}.toml <<EOF
 id = "{rpm-repo-version}"
 name = "Red Hat OpenShift Container Platform {ocp-version} for RHEL {op-system-version-major}"
 type = "yum-baseurl"
-url = "https://cdn.redhat.com/content/dist/layered/{op-system-version-major-short}/$(uname -m)/rhocp/{ocp-version}/os"
+url = "https://cdn.redhat.com/content/dist/layered/{rhel-major}/$(uname -m)/rhocp/{ocp-version}/os"
 check_gpg = true
 check_ssl = true
 system = false
@@ -40,7 +41,7 @@ $ cat > fast-datapath.toml <<EOF
 id = "fast-datapath"
 name = "Fast Datapath for RHEL 9"
 type = "yum-baseurl"
-url = "https://cdn.redhat.com/content/dist/layered/{op-system-version-major-short}/$(uname -m)/fast-datapath/os"
+url = "https://cdn.redhat.com/content/dist/layered/{rhel-major}/$(uname -m)/fast-datapath/os"
 check_gpg = true
 check_ssl = true
 system = false

modules/microshift-adding-service-to-blueprint.adoc

@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
-// microshift/microshift-embed-into-rpm-ostree.adoc
+// * microshift/microshift-embed-into-rpm-ostree.adoc
+// * microshift/microshift-update-rpms-ostree.adoc
 
 :_content-type: PROCEDURE
 [id="adding-microshift-service-to-blueprint_{context}"]

modules/microshift-check-cluster-status.adoc

@@ -0,0 +1,38 @@
+//Module included in the following assemblies:
+//
+//*  microshift_troubleshooting/microshift-troubleshoot-cluster
+
+:_content-type: PROCEDURE
+[id="microshift-check-cluster-status_{context}"]
+= Checking the status of a {product-title} cluster
+
+You can check the status of a {product-title} cluster or see active pods by running a simple command. Given in the following procedure are three commands you can use to check cluster status. You can choose to run one, two, or all commands to help you retrieve the information you need to troubleshoot the cluster.
+
+.Procedure
+* You can check the {product-title} system status, which returns the cluster status, by running the following command:
++
+[source,terminal]
+----
+$ sudo systemctl status microshift
+----
++
+If {product-title} is failing to start, this command returns the logs from the previous run.
+
+* Optional: You can view the {product-title} logs by running the following command:
++
+[source,terminal]
+----
+$ sudo journalctl -u microshift
+----
+
+[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.
+====
+
+* Optional: If {product-title} is running, you can see active pods by entering the following command:
++
+[source,terminal]
+----
+$ oc get pods -A
+----