Merge pull request #40412 from sagidlow/OSDOCS-2911-prod

OSDOCS-2911: Adding documentation about conditional updates

Author: sagidlow

modules/understanding-upgrade-channels.adoc

@@ -88,13 +88,13 @@ endif::openshift-origin[]
 The service recommends only upgrades that have been tested and have no serious issues. It will not suggest updating to a version of {product-title} that contains known vulnerabilities. For example, if your cluster is on {product-version}.1 and {product-title} suggests {product-version}.4, then it is safe for you to update from {product-version}.1 to {product-version}.4. Do not rely on consecutive patch numbers. In this example, {product-version}.2 is not and never was available in the channel.
 
 ifndef::openshift-origin[]
-Update stability depends on your channel. The presence of an update recommendation in the `candidate-{product-version}` channel does not imply that the update is supported. It means that no serious issues have been found with the update yet, but there might not be significant traffic through the update to suggest stability. The presence of an update recommendation in the `fast-{product-version}` or `stable-{product-version}` channels at any point is a declaration that the update is supported. While releases will never be removed from a channel, update recommendations that exhibit serious issues will be removed from all channels. Updates initiated after the update recommendation has been removed are still supported.
+Update stability depends on your channel. The presence of an update recommendation in the `candidate-{product-version}` channel does not imply that the update is supported. It means that no serious issues have been found with the update yet, but there might not be significant traffic through the update to suggest stability. The presence of an update recommendation in the `fast-{product-version}` or `stable-{product-version}` channels at any point is a declaration that the update is supported. While releases will never be removed from a channel, update recommendations that exhibit serious issues will be removed or made conditional from all channels. When an update recommendation is supported, it remains supported for the life of {product-version}, even if the update recommendation is later dropped or made conditional.
 
 Red Hat will eventually provide supported update paths from any supported release in the `fast-{product-version}` or `stable-{product-version}` channels to the latest release in {product-version}.z, although there can be delays while safe paths away from troubled releases are constructed and verified.
 endif::openshift-origin[]
 
 ifdef::openshift-origin[]
-The presence of an update recommendation in the `stable-4` channel at any point is a declaration that the update is supported. While releases will never be removed from the channel, update recommendations that exhibit serious issues will be removed from the channel. Updates initiated after the update recommendation has been removed are still supported.
+The presence of an update recommendation in the `stable-4` channel at any point is a declaration that the update is supported. While releases will never be removed from the channel, update recommendations that exhibit serious issues will be removed or made conditional from all channels. When an update recommendation is supported, it remains supported for the life of {product-version}, even if the update recommendation is later dropped or made conditional.
 endif::openshift-origin[]
 
 ifndef::openshift-origin[]
@@ -136,3 +136,11 @@ Changing your channel might impact the supportability of your cluster. The follo
 
 * You can always switch from the `fast-{product-version}` channel to the `stable-{product-version}` channel. There is a possible delay of up to a day for the release to be promoted to `stable-{product-version}` if the current release was recently promoted.
 endif::openshift-origin[]
+
+[id="conditional-updates-overview_{context}"]
+== Conditional updates
+
+The OpenShift Update Service might declare conditionally recommended updates associated with known risks.
+The Cluster Version Operator (CVO) continually evaluates known risks associated with updates from the current {product-title} release to later releases.
+When no risks apply, the update is recommended. You can update from the Administrator perspective on the web console, as well as the OpenShift CLI (`oc`).
+When an update is not recommended because a risk might apply, you can view the update from the OpenShift CLI (`oc`). If the cluster administrator evaluates the potential known risks and decides it is acceptable for the current cluster, the administrator can waive the safety guards and proceed to an update.

modules/update-conditional-updates.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * updating/updating-cluster-cli.adoc
+// * updating/understanding-upgrade-channels-releases.adoc
+
+[id="update-conditional-upgrade-path{context}"]
+= Updating along a conditional upgrade path
+
+You can update along a recommended conditional upgrade path using the web console or the OpenShift CLI (`oc`).
+When a conditional update is not recommended for your cluster, you can update along a conditional upgrade path using the OpenShift CLI (`oc`) 4.10 or later.
+
+.Procedure
+
+. To view the description of the update when it is not recommended because a risk might apply, run the following command:
++
+[source,terminal]
+----
+$ oc adm upgrade --include-not-recommended
+----
+
+. If the cluster administrator evaluates the potential known risks and decides it is acceptable for the current cluster, then the administrator can waive the safety guards and proceed the update by running the following command:
++
+[source,terminal]
+----
+$ oc adm upgrade --allow-not-recommended --to <version> <.>
+----
+<.> `<version>` is the supported but not recommended update version that you obtained from the output of the previous command.

updating/understanding-the-update-service.adoc

@@ -14,4 +14,9 @@ If you are on a restricted network where disconnected clusters cannot access the
 
 include::modules/update-service-overview.adoc[leveloffset=+1]
 
+.Additional resources
+
+* xref:../updating/understanding-upgrade-channels-release.adoc#understanding-upgrade-channels_understanding-upgrade-channels-releases[Understanding upgrade channels and releases]
+
+
 include::modules/unmanaged-operators.adoc[leveloffset=+1]

updating/understanding-upgrade-channels-release.adoc

@@ -33,3 +33,6 @@ ifdef::openshift-origin[]
 endif::openshift-origin[]
 
 include::modules/understanding-upgrade-channels.adoc[leveloffset=+1]
+
+.Additional resources
+* For more information, see xref:../updating/updating-cluster-cli.adoc#update-conditional-upgrade-pathupdating-cluster-cli[Updating along a conditional upgrade path]

updating/updating-cluster-cli.adoc

@@ -42,5 +42,10 @@ include::modules/updating-sno.adoc[leveloffset=+1]
 For information on which machine configuration changes require a reboot, see the note in xref:../architecture/control-plane.adoc#understanding-machine-config-operator_control-plane[Understanding the Machine Config Operator].
 
 include::modules/update-upgrading-cli.adoc[leveloffset=+1]
+include::modules/update-conditional-updates.adoc[leveloffset=+1]
+
+.Additional resources
+
+* xref:../updating/understanding-upgrade-channels-release.adoc#understanding-upgrade-channels_understanding-upgrade-channels-releases[Upgrade channels and release paths]
 
 include::modules/update-changing-update-server-cli.adoc[leveloffset=+1]

updating/updating-cluster-within-minor.adoc

@@ -59,3 +59,7 @@ include::modules/updating-sno.adoc[leveloffset=+1]
 include::modules/update-upgrading-web.adoc[leveloffset=+1]
 
 include::modules/update-changing-update-server-web.adoc[leveloffset=+1]
+
+.Additional resources
+
+* xref:../updating/understanding-upgrade-channels-release.adoc#understanding-upgrade-channels_understanding-upgrade-channels-releases[Understanding upgrade channels and releases]