Merge pull request #86227 from obrown1205/OSDOCS-12920

OSDOCS-12920: oc adm upgrade recommend TP doc

Author: jeana-redhat

modules/update-upgrading-oc-adm-upgrade-recommend.adoc

@@ -0,0 +1,85 @@
+// Module included in the following assemblies:
+//
+// * updating/updating_a_cluster/updating-cluster-cli.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="update-upgrading-oc-adm-upgrade-recommend_{context}"]
+= Finding recommended update paths with oc adm upgrade recommend (Technology Preview)
+
+When updating your cluster, the `oc adm upgrade` command returns a list of the next available versions. You can use the `oc adm upgrade recommend` command to narrow down your suggestions and recommend a new target release before you launch your update.
+
+The `oc adm upgrade recommend` command is read-only and cannot alter the state of your cluster.  
+
+:FeatureName: The `oc adm upgrade recommend` command
+include::snippets/technology-preview.adoc[]
+
+[NOTE]
+====
+Your cluster does not need to be a Technology Preview-enabled cluster in order for you to use the `oc adm upgrade recommend` command. 
+====
+
+.Procedure 
+
+. Set the `OC_ENABLE_CMD_UPGRADE_RECOMMEND` environment variable to `true` by running the following command:
++
+[source,terminal]
+----
+$ export OC_ENABLE_CMD_UPGRADE_RECOMMEND=true
+----
+. Run one of the following commands:
+
+** To list the recommended versions for your update, run the `oc adm upgrade recommend` command:
++
+[source,terminal]
+----
+$ oc adm upgrade recommend
+----
++
+.Example output
+
+[source,terminal]
+----
+Upstream is unset, so the cluster will use an appropriate default.
+Channel: stable-4.13 (available channels: candidate-4.12, candidate-4.13, eus-4.12, eus-4.14, fast-4.12, fast-4.13, stable-4.12, stable-4.13)
+
+Updates to 4.13:
+
+Version: 4.13.50
+Image: quay.io/openshift-release-dev/ocp-release@sha256:6afb11e1cac46fd26476ca134072937115256b9c6360f7a1cd1812992c065f02
+Reason: AdminAckRequired
+Message: Kubernetes 1.26 and therefore OpenShift 4.13 remove several APIs which require admin consideration. Please see the knowledge article https://access.redhat.com/articles/6958394 for details and instructions.
+
+Version: 4.13.49
+Image: quay.io/openshift-release-dev/ocp-release@sha256:ab6f574665395d809511db9dc57764358278538eaae248c6d199208b3c30ab7d
+Reason: AdminAckRequired
+Message: Kubernetes 1.26 and therefore OpenShift 4.13 remove several APIs which require admin consideration. Please see the knowledge article https://access.redhat.com/articles/6958394 for details and instructions.
+
+Updates to 4.12:
+VERSION     ISSUES
+4.12.64     no known issues
+4.12.63     no known issues
+And 43 older 4.12 updates you can see with '--show-outdated-releases' or '--version VERSION'.
+----
+
+** To determine whether a specific version is recommended for your update, run the `oc adm upgrade recommend --version` command:
++
+[source,terminal]
+----
+$ oc adm upgrade recommend --version 4.12.51
+----
++
+.Example output
+
+[source,terminal]
+----
+Upstream is unset, so the cluster will use an appropriate default.
+Channel: stable-4.13 (available channels: candidate-4.12, candidate-4.13, eus-4.12, eus-4.14, fast-4.12, fast-4.13, stable-4.12, stable-4.13)
+
+Update to 4.12.51 Recommended=False:
+Image: quay.io/openshift-release-dev/ocp-release@sha256:158ced797e49f6caf7862acccef58484be63b642fdd2f66e6416295fa7958ab0
+Release URL: https://access.redhat.com/errata/RHSA-2024:1052
+Reason: MultipleReasons
+Message: An unintended reversion to the default kubelet nodeStatusReportFrequency can cause significant load on the control plane. https://issues.redhat.com/browse/MCO-1094
+  
+After rebooting into kernel-4.18.0-372.88.1.el8_6 or later, kernel nodes experience high load average and io_wait times. The nodes might fail to start or stop pods and probes may fail. Workload and host processes may become unresponsive and workload may be disrupted. https://issues.redhat.com/browse/COS-2705
+----

modules/update-upgrading-oc-adm-upgrade-status.adoc

@@ -6,23 +6,23 @@
 [id="update-upgrading-oc-adm-upgrade-status_{context}"]
 = Gathering cluster update status using oc adm upgrade status (Technology Preview)
 
-When updating your cluster, it is useful to understand how your update is progressing. While the `oc adm upgrade` command returns limited information about the status of your update, this release introduces the `oc adm upgrade status` command as a Technology Preview feature. This command decouples status information from the `oc adm upgrade` command and provides specific information regarding a cluster update, including the status of the control plane and worker node updates.
+When updating your cluster, the `oc adm upgrade` command returns returns limited information about the status of your update. You can use the `oc adm upgrade status` command to decouple status information from the `oc adm upgrade` command and return specific information regarding a cluster update, including the status of the control plane and worker node updates.
 
-The `oc adm upgrade status` command is read-only and will never alter any state in your cluster. 
+The `oc adm upgrade status` command is read-only and does not alter any state in your cluster. 
 
 :FeatureName: The `oc adm upgrade status` command
 include::snippets/technology-preview.adoc[]
 
 The `oc adm upgrade status` command can be used for clusters from version 4.12 up to the latest supported release. 
 
-[IMPORTANT]
+[NOTE]
 ====
-While your cluster does not need to be a Technology Preview-enabled cluster, you must enable the `OC_ENABLE_CMD_UPGRADE_STATUS` Technology Preview environment variable, otherwise the {oc-first} will not recognize the command and you will not be able to use the feature. 
+Your cluster does not need to be a Technology Preview-enabled cluster in order for you to use the `oc adm upgrade status` command. 
 ====
 
 .Procedure 
 
-. Set the `OC_ENABLE_CMD_UPGRADE_STATUS` environmental variable to `true` by running the following command:
+. Set the `OC_ENABLE_CMD_UPGRADE_STATUS` environment variable to `true` by running the following command:
 +
 [source,terminal]
 ----
@@ -36,8 +36,7 @@ $ oc adm upgrade status
 ----
 +
 .Example output for an update progressing successfully
-[%collapsible]
-====
+
 [source,terminal]
 ----
 = Control Plane =
@@ -80,6 +79,4 @@ ip-10-0-4-159-infra.us-east-2.compute.internal   Progressing   Draining   4.14.0
 = Update Health =
 SINCE   LEVEL   IMPACT   MESSAGE
 14m4s   Info    None     Update is proceeding well
-----
-====
-With this information, you can make informed decisions on how to proceed with your update.
+----

updating/updating_a_cluster/updating-cluster-cli.adoc

@@ -57,7 +57,10 @@ include::modules/updating-sno.adoc[leveloffset=+1]
 // Updating a cluster by using the CLI
 include::modules/update-upgrading-cli.adoc[leveloffset=+1]
 
-//Introducing oc adm upgrade status - Tech Preview
+//Finding recommended update paths with oc adm upgrade recommend (Technology Preview)
+include::modules/update-upgrading-oc-adm-upgrade-recommend.adoc[leveloffset=+1]
+
+//Gathering cluster update status using oc adm upgrade status (Technology Preview)
 include::modules/update-upgrading-oc-adm-upgrade-status.adoc[leveloffset=+1]
 
 [role="_additional-resources"]