Merge pull request #71004 from skopacz1/OSDOCS-9497

OSDOCS#9497: editing canary rollout update page

Author: jab-rh

modules/update-using-custom-machine-config-pools-about.adoc

@@ -6,28 +6,29 @@
 [id="update-using-custom-machine-config-pools-about_{context}"]
 = About performing a canary rollout update
 
-This topic describes the general workflow of this canary rollout update process. The steps to perform each task in the workflow are described in the following sections.
+The following steps outline the high-level workflow of the canary rollout update process:
 
-. Create MCPs based on the worker pool. The number of nodes in each MCP depends on a few factors, such as your maintenance window duration for each MCP, and the amount of reserve capacity, meaning extra worker nodes, available in your cluster.
+. Create custom machine config pools (MCP) based on the worker pool.
 +
 [NOTE]
 ====
-You can change the `maxUnavailable` setting in an MCP to specify the percentage or the number of machines that can be updating at any given time. The default is 1.
+You can change the `maxUnavailable` setting in an MCP to specify the percentage or the number of machines that can be updating at any given time. The default is `1`.
 ====
 
 . Add a node selector to the custom MCPs. For each node that you do not want to update simultaneously with the rest of the cluster, add a matching label to the nodes. This label associates the node to the MCP.
 +
-[NOTE]
+[IMPORTANT]
 ====
-Do not remove the default worker label from the nodes. The nodes *must* have a role label to function properly in the cluster.
+Do not remove the default worker label from the nodes. The nodes must have a role label to function properly in the cluster.
 ====
 
 . Pause the MCPs you do not want to update as part of the update process.
 
 . Perform the cluster update. The update process updates the MCPs that are not paused, including the control plane nodes.
 
-. Test the applications on the updated nodes to ensure they are working as expected.
+. Test your applications on the updated nodes to ensure they are working as expected.
 
-. Unpause the remaining MCPs one-by-one and test the applications on those nodes until all worker nodes are updated. Unpausing an MCP starts the update process for the nodes associated with that MCP. You can check the progress of the update from the web console by clicking *Administration* -> *Cluster settings*. Or, use the `oc get machineconfigpools` CLI command.
+. Unpause one of the remaining MCPs, wait for the nodes in that pool to finish updating, and test the applications on those nodes.
+Repeat this process until all worker nodes are updated.
 
-. Optionally, remove the custom label from updated nodes and delete the custom MCPs.
+. Optional: Remove the custom label from updated nodes and delete the custom MCPs.

modules/update-using-custom-machine-config-pools-mcp-remove.adoc

@@ -5,14 +5,14 @@
 [id="update-using-custom-machine-config-pools-mcp-remove_{context}"]
 = Moving a node to the original machine config pool
 
-In this canary rollout update process, after you have unpaused a custom machine config pool (MCP) and verified that the applications on the nodes associated with that MCP are working as expected, you should move the node back to its original MCP by removing the custom label you added to the node.
+After you update and verify applications on nodes in a custom machine config pool (MCP), move the nodes back to their original MCP by removing the custom label that you added to the nodes.
 
 [IMPORTANT]
 ====
 A node must have a role to be properly functioning in the cluster.
 ====
 
-To move a node to its original MCP:
+.Procedure
 
 ////
 . Ensure that the nodes have a `worker` label or a label from an MCP that is updated.
@@ -32,11 +32,11 @@ error: 'node-role.kubernetes.io/worker' already has a value (), and --overwrite
 If the node does not have a `worker` label or a label from an updated MCP, add the label.
 ////
 
-. Remove the custom label from the node.
+. For each node in a custom MCP, remove the custom label from the node by running the following command:
 +
 [source,terminal]
 ----
-$ oc label node <node_name> node-role.kubernetes.io/<custom-label>-
+$ oc label node <node_name> node-role.kubernetes.io/<custom_label>-
 ----
 +
 For example:
@@ -53,15 +53,16 @@ $ oc label node ci-ln-0qv1yp2-f76d1-kl2tq-worker-a-j2ssz node-role.kubernetes.io
 node/ci-ln-0qv1yp2-f76d1-kl2tq-worker-a-j2ssz labeled
 ----
 +
-The MCO moves the nodes back to the original MCP and reconciles the node to the MCP configuration.
+The Machine Config Operator moves the nodes back to the original MCP and reconciles the node to the MCP configuration.
 
-. View the list of MCPs in the cluster and their current state:
+. To ensure that node has been removed from the custom MCP, view the list of MCPs in the cluster and their current state by running the following command:
 +
 [source,terminal]
 ----
-$oc get mcp
+$ oc get mcp
 ----
 +
+.Example output
 [source,terminal]
 ----
 NAME                CONFIG                                                   UPDATED   UPDATING   DEGRADED   MACHINECOUNT   READYMACHINECOUNT   UPDATEDMACHINECOUNT   DEGRADEDMACHINECOUNT   AGE
@@ -70,9 +71,9 @@ workerpool-canary   rendered-mcp-noupdate-5ad4791166c468f3a35cd16e734c9028   Tru
 worker              rendered-worker-5ad4791166c468f3a35cd16e734c9028         True      False      False      3              3                   3                     0                      61m
 ----
 +
-The node is removed from the custom MCP and moved back to the original MCP. It can take several minutes to update the machine counts. In this example, one node was moved from the removed `workerpool-canary` MCP to the `worker`MCP.
+When the node is removed from the custom MCP and moved back to the original MCP, it can take several minutes to update the machine counts. In this example, one node was moved from the removed `workerpool-canary` MCP to the `worker` MCP.
 
-. Optional: Delete the custom MCP:
+. Optional: Delete the custom MCP by running the following command:
 +
 [source,terminal]
 ----

modules/update-using-custom-machine-config-pools-mcp.adoc

@@ -5,11 +5,11 @@
 [id="update-using-custom-machine-config-pools-mcp_{context}"]
 = Creating machine config pools to perform a canary rollout update
 
-The first task in performing this canary rollout update is to create one or more machine config pools (MCP).
+To perform a canary rollout update, you must first create one or more custom machine config pools (MCP).
 
-. Create an MCP from a worker node.
+.Procedure
 
-.. List the worker nodes in your cluster.
+. List the worker nodes in your cluster by running the following command:
 +
 [source,terminal]
 ----
@@ -25,11 +25,11 @@ ci-ln-pwnll6b-f76d1-s8t9n-worker-b-dglj2
 ci-ln-pwnll6b-f76d1-s8t9n-worker-c-lldbm
 ----
 
-.. For the nodes you want to delay, add a custom label to the node:
+. For each node that you want to delay, add a custom label to the node by running the following command:
 +
 [source,terminal]
 ----
-$ oc label node <node name> node-role.kubernetes.io/<custom-label>=
+$ oc label node <node_name> node-role.kubernetes.io/<custom_label>=
 ----
 +
 For example:
@@ -46,7 +46,9 @@ $ oc label node ci-ln-0qv1yp2-f76d1-kl2tq-worker-a-j2ssz node-role.kubernetes.io
 node/ci-ln-gtrwm8t-f76d1-spbl7-worker-a-xk76k labeled
 ----
 
-.. Create the new MCP:
+. Create the new MCP:
+
+.. Create an MCP YAML file:
 +
 [source,yaml]
 ----
@@ -56,11 +58,11 @@ metadata:
   name: workerpool-canary <1>
 spec:
   machineConfigSelector:
-    matchExpressions: <2>
+    matchExpressions:
       - {
          key: machineconfiguration.openshift.io/role,
          operator: In,
-         values: [worker,workerpool-canary]
+         values: [worker,workerpool-canary] <2>
         }
   nodeSelector:
     matchLabels:
@@ -69,6 +71,8 @@ spec:
 <1> Specify a name for the MCP.
 <2> Specify the `worker` and custom MCP name.
 <3> Specify the custom label you added to the nodes that you want in this pool.
+
+.. Create the `MachineConfigPool` object by running the following command:
 +
 [source,terminal]
 ----
@@ -81,8 +85,8 @@ $ oc create -f <file_name>
 ----
 machineconfigpool.machineconfiguration.openshift.io/workerpool-canary created
 ----
-+
-.. View the list of MCPs in the cluster and their current state:
+
+. View the list of MCPs in the cluster and their current state by running the following command:
 +
 [source,terminal]
 ----
@@ -99,5 +103,3 @@ worker            rendered-worker-87ba3dec1ad78cb6aecebf7fbb476a36
 ----
 +
 The new machine config pool, `workerpool-canary`, is created and the number of nodes to which you added the custom label are shown in the machine counts. The worker MCP machine counts are reduced by the same number. It can take several minutes to update the machine counts. In this example, one node was moved from the `worker` MCP to the `workerpool-canary` MCP.
-
-

modules/update-using-custom-machine-config-pools-pause.adoc

@@ -5,11 +5,11 @@
 [id="update-using-custom-machine-config-pools-pause_{context}"]
 = Pausing the machine config pools
 
-In this canary rollout update process, after you label the nodes that you do not want to update with the rest of your {product-title} cluster and create the machine config pools (MCPs), you pause those MCPs. Pausing an MCP prevents the Machine Config Operator (MCO) from updating the nodes associated with that MCP.
+After you create your custom machine config pools (MCPs), you then pause those MCPs. Pausing an MCP prevents the Machine Config Operator (MCO) from updating the nodes associated with that MCP.
 
-To pause an MCP:
+.Procedure
 
-. Patch the MCP that you want paused:
+. Patch the MCP that you want paused by running the following command:
 +
 [source,terminal]
 ----

modules/update-using-custom-machine-config-pools-unpause.adoc

@@ -5,9 +5,9 @@
 [id="update-using-custom-machine-config-pools-unpause_{context}"]
 = Unpausing the machine config pools
 
-In this canary rollout update process, after the {product-title} update is complete, unpause your custom MCPs one-by-one. Unpausing an MCP allows the Machine Config Operator (MCO) to update the nodes associated with that MCP.
+After the {product-title} update is complete, unpause your custom machine config pools (MCP) one at a time. Unpausing an MCP allows the Machine Config Operator (MCO) to update the nodes associated with that MCP.
 
-To unpause an MCP:
+.Procedure
 
 . Patch the MCP that you want to unpause:
 +
@@ -29,15 +29,23 @@ $  oc patch mcp/workerpool-canary --patch '{"spec":{"paused":false}}' --type=mer
 ----
 machineconfigpool.machineconfiguration.openshift.io/workerpool-canary patched
 ----
+
+. Optional: Check the progress of the update by using one of the following options:
+
+.. Check the progress from the web console by clicking *Administration* -> *Cluster settings*.
+
+.. Check the progress by running the following command:
 +
-You can check the progress of the update by using the `oc get machineconfigpools` command.
+[source,terminal]
+----
+$ oc get machineconfigpools
+----
 
 . Test your applications on the updated nodes to ensure that they are working as expected.
 
-. Unpause any other paused MCPs one-by-one and verify that your applications work.
-
-[id="update-using-custom-machine-config-pools-fail_{context}"]
-== In case of application failure
+. Repeat this process for any other paused MCPs, one at a time.
 
+[NOTE]
+====
 In case of a failure, such as your applications not working on the updated nodes, you can cordon and drain the nodes in the pool, which moves the application pods to other nodes to help maintain the quality-of-service for the applications. This first MCP should be no larger than the excess capacity.
-
+====