openshift · skopacz1 · Mar 20, 2026 · Mar 6, 2026
diff --git a/modules/before-updating-ocp.adoc b/modules/before-updating-ocp.adoc
@@ -6,14 +6,23 @@
 [id="before-updating-ocp_{context}"]
 = Before updating the {product-title} cluster
 
-Before updating, consider the following:
+[role="_abstract"]
+Before updating your cluster, you must consider several factors in order to improve the chances of performing a successful update.
 
-* You have recently backed up etcd.
+Consider the following information:
+
+* Whether you have recently backed up etcd.
 
 * In `PodDisruptionBudget`, if `minAvailable` is set to `1`, the nodes are drained to apply pending machine configs that might block the eviction process. If several nodes are rebooted, all the pods might run on only one node, and the `PodDisruptionBudget` field can prevent the node drain.
 
 * You might need to update the cloud provider resources for the new release if your cluster uses manually maintained credentials.
 
 * You must review administrator acknowledgement requests, take any recommended actions, and provide the acknowledgement when you are ready.
 
-* You can perform a partial update by updating the worker or custom pool nodes to accommodate the time it takes to update. You can pause and resume within the progress bar of each pool.
+* You can perform a partial update by updating the worker or custom pool nodes to accommodate the time it takes to update. You can pause and resume within the progress bar of each pool.
+
+[IMPORTANT]
+====
+* When an update is failing to complete, the Cluster Version Operator (CVO) reports the status of any blocking components while attempting to reconcile the update. Rolling your cluster back to a previous version is not supported. If your update is failing to complete, contact Red{nbsp}Hat support.
+* Using the `unsupportedConfigOverrides` section to modify the configuration of an Operator is unsupported and might block cluster updates. You must remove this setting before you can update your cluster.
+====
diff --git a/modules/machine-health-checks-pausing-web-console.adoc b/modules/machine-health-checks-pausing-web-console.adoc
@@ -6,7 +6,8 @@
 [id="machine-health-checks-pausing-web-console_{context}"]
 = Pausing a MachineHealthCheck resource by using the web console
 
-During the update process, nodes in the cluster might become temporarily unavailable. In the case of worker nodes, the machine health check might identify such nodes as unhealthy and reboot them. To avoid rebooting such nodes, pause all the `MachineHealthCheck` resources before updating the cluster.
+[role="_abstract"]
+During the update process, nodes in the cluster might become temporarily unavailable. For worker nodes, the machine health check might identify such nodes as unhealthy and reboot them. To avoid rebooting such nodes, pause all the `MachineHealthCheck` resources before updating the cluster.
 
 .Prerequisites
 
@@ -15,9 +16,8 @@ During the update process, nodes in the cluster might become temporarily unavail
 
 .Procedure
 
-. Log in to the {product-title} web console.
-. Navigate to *Compute* -> *MachineHealthChecks*.
-. To pause the machine health checks, add the `cluster.x-k8s.io/paused=""` annotation to each `MachineHealthCheck` resource. For example, to add the annotation to the `machine-api-termination-handler` resource, complete the following steps:
+. On the web console, navigate to *Compute* -> *MachineHealthChecks*.
+. For each `MachineHealthCheck` resource, pause the machine health checks by adding the `cluster.x-k8s.io/paused=""` annotation to the resource. For example, to add the annotation to the `machine-api-termination-handler` resource, complete the following steps:
 .. Click the Options menu {kebab} next to the `machine-api-termination-handler` and click *Edit annotations*.
 .. In the *Edit annotations* dialog, click *Add more*.
 .. In the *Key* and *Value* fields, add `cluster.x-k8s.io/paused` and `""` values, respectively, and click *Save*.
diff --git a/modules/update-changing-update-server-web.adoc b/modules/update-changing-update-server-web.adoc
@@ -6,6 +6,9 @@
 [id="update-changing-update-server-web_{context}"]
 = Changing the update server by using the web console
 
+[role="_abstract"]
+You can change the update server your cluster uses to retrieve information about update paths.
+
 ifndef::openshift-origin[]
 Changing the update server is optional. If you have an OpenShift Update Service (OSUS) installed and configured locally, you must set the URL for the server as the `upstream` to use the local server during updates.
 endif::openshift-origin[]
@@ -20,21 +23,21 @@ endif::openshift-origin[]
 
 .Procedure
 
-. Navigate to *Administration* -> *Cluster Settings*, click *version*.
+. On the web console, navigate to *Administration* -> *Cluster Settings* and click *version*.
 . Click the *YAML* tab and then edit the `upstream` parameter value:
 +
-.Example output
-+
+.Example YAML snippet
 [source,yaml]
 ----
   ...
   spec:
     clusterID: db93436d-7b05-42cc-b856-43e11ad2d31a
-    upstream: '<update-server-url>' <1>
+    upstream: '<update_server_url>'
   ...
 ----
-<1> The `<update-server-url>` variable specifies the URL for the update server.
 +
-The default `upstream` is `\https://api.openshift.com/api/upgrades_info/v1/graph`.
+Replace `<update_server_url>` with the URL for the update server.
++
+The default `upstream` value is `\https://api.openshift.com/api/upgrades_info/v1/graph`.
 
 . Click *Save*.
diff --git a/modules/update-conditional-web-console.adoc b/modules/update-conditional-web-console.adoc
@@ -6,6 +6,7 @@
 [id="update-conditional-web-console_{context}"]
 = Viewing conditional updates in the web console
 
+[role="_abstract"]
 You can view and assess the risks associated with particular updates with conditional updates.
 
 .Prerequisites

diff --git a/modules/update-upgrading-web.adoc b/modules/update-upgrading-web.adoc
@@ -11,6 +11,7 @@ endif::[]
 [id="update-upgrading-web_{context}"]
 = Updating a cluster by using the web console
 
+[role="_abstract"]
 If updates are available, you can update your cluster from the web console.
 
 You can find information about available {product-title} advisories and updates
@@ -49,14 +50,16 @@ endif::openshift-origin[]
 [NOTE]
 ====
 When you are ready to move to the next minor version, choose the channel that corresponds to that minor version.
-The sooner the update channel is declared, the more effectively the cluster can recommend update paths to your target version.
+The sooner you declare the update channel, the more effectively the cluster can recommend update paths to your target version.
 The cluster might take some time to evaluate all the possible updates that are available and offer the best update recommendations to choose from.
 Update recommendations can change over time, as they are based on what update options are available at the time.
 
 If you cannot see an update path to your target minor version, keep updating your cluster to the latest patch release for your current version until the next minor version is available in the path.
 ====
-** If the *Update status* is not *Updates available*, you cannot update your cluster.
-** *Select channel* indicates the cluster version that your cluster is running or is updating to.
++
+If the *Update status* is not *Updates available*, you cannot update your cluster.
++
+*Select channel* indicates the cluster version that your cluster is running or is updating to.
 
 . Select a version to update to, and click *Save*.
 +

diff --git a/modules/update-using-custom-machine-config-pools-canary.adoc b/modules/update-using-custom-machine-config-pools-canary.adoc
@@ -2,10 +2,14 @@
 //
 // * updating/updating_a_cluster/updating-cluster-web-console.adoc
 
+:_mod-docs-content-type: CONCEPT
 [id="update-using-custom-machine-config-pools-canary_{context}"]
 = Performing a canary rollout update
 
-In some specific use cases, you might want a more controlled update process where you do not want specific nodes updated concurrently with the rest of the cluster. These use cases include, but are not limited to:
+[role="_abstract"]
+In some specific use cases, you might want a more controlled update process where you do not want specific nodes updated concurrently with the rest of the cluster.
+
+These use cases include, but are not limited to the following situations:
 
 * You have mission-critical applications that you do not want unavailable during the update. You can slowly test the applications on your nodes in small batches after the update.
 * You have a small maintenance window that does not allow the time for all nodes to be updated, or you have multiple maintenance windows.
@@ -29,4 +33,4 @@ The rolling update process described in this topic involves:
 Pausing an MCP should be done with careful consideration and for short periods of time only.
 ====
 
-//link that follows is in the assembly: updating-cluster-between-minor
+If you want to use the canary rollout update process, see "Performing a canary rollout update".
diff --git a/updating/updating_a_cluster/updating-cluster-web-console.adoc b/updating/updating_a_cluster/updating-cluster-web-console.adoc
@@ -6,12 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-////
-WARNING: This assembly has been moved into a subdirectory for 4.14+. Changes to this assembly for earlier versions should be done in separate PRs based off of their respective version branches. Otherwise, your cherry picks may fail.
-
-To do: Remove this comment once 4.13 docs are EOL.
-////
-
+[role="_abstract"]
 You can perform minor version and patch updates on an {product-title} cluster by using the web console.
 
 [NOTE]
@@ -21,12 +16,6 @@ Use the web console or `oc adm upgrade channel _<channel>_` to change the update
 
 include::modules/before-updating-ocp.adoc[leveloffset=+1]
 
-[IMPORTANT]
-====
-* When an update is failing to complete, the Cluster Version Operator (CVO) reports the status of any blocking components while attempting to reconcile the update. Rolling your cluster back to a previous version is not supported. If your update is failing to complete, contact Red{nbsp}Hat support.
-* Using the `unsupportedConfigOverrides` section to modify the configuration of an Operator is unsupported and might block cluster updates. You must remove this setting before you can update your cluster.
-====
-
 include::modules/update-changing-update-server-web.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -54,11 +43,14 @@ include::modules/update-conditional-web-console.adoc[leveloffset=+1]
 
 include::modules/update-using-custom-machine-config-pools-canary.adoc[leveloffset=+1]
 
-If you want to use the canary rollout update process, see xref:../../updating/updating_a_cluster/update-using-custom-machine-config-pools.adoc#update-using-custom-machine-config-pools[Performing a canary rollout update].
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../updating/updating_a_cluster/update-using-custom-machine-config-pools.adoc#update-using-custom-machine-config-pools[Performing a canary rollout update]
 
 include::modules/updating-sno.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../architecture/control-plane.adoc#about-machine-config-operator_control-plane[About the Machine Config Operator].
+* xref:../../machine_configuration/index.adoc#about-machine-config-operator_machine-config-index[About the Machine Config Operator]