OSDOCS-11160 OSDOCS-11610 Late-breaking PM feedback re. maxSurge and maxUnavailable parameters

Author: laubai

modules/rosa-hcp-upgrade-options.adoc

@@ -6,24 +6,21 @@ In OpenShift, upgrading means provisioning a new component with updated software
 
 You can control the impact of upgrades to your workload by controlling which parts of the cluster are upgraded, for example:
 
-Upgrade only the hosted control plane:: This does not impact your worker nodes.
+Upgrade only the hosted control plane:: This initiates upgrade of the hosted control plane. It does not impact your worker nodes.
 
-Upgrade nodes in a single machine pool:: This initiates a rolling replacement of nodes in the specified machine pool, and temporarily impacts the worker nodes on that machine pool. This does not impact nodes on other machine pools in the cluster.
+Upgrade nodes in a machine pool:: This initiates a rolling replacement of nodes in the specified machine pool, and temporarily impacts the worker nodes on that machine pool. You can also upgrade multiple machine pools concurrently.
 
-Upgrade nodes in multiple machine pools simultaneously:: This initiates a rolling replacement of nodes in the specified machine pools, and temporarily impacts the worker nodes on those machine pools. You can run this type of upgrade as a single command, or as multiple commands.
+[IMPORTANT]
+====
+You cannot upgrade the hosted control plane at the same time as any machine pool upgrade.
+====
 
-Upgrade the whole cluster in sequence:: This initiates upgrade of the hosted control plane, followed by a rolling replacement of nodes in the specified machine pools. These upgrades occur in sequence because the hosted control plane and the machine pools cannot be upgraded at the same time. When an upgrade of the hosted control plane is in progress, nodes in the machine pools cannot be upgraded. When upgrade is in progress for nodes in the machine pools, the hosted control plane cannot be upgraded.
-+
 [IMPORTANT]
 ====
 To maintain compatibility between nodes in the cluster, nodes in machine pools cannot use a newer version than the hosted control plane. This means that the hosted control plane should always be upgraded to a given version before any machine pools are upgraded to the same version.
 ====
 
-The time required to upgrade the hosted control plane varies depending on your workload configuration.
-
-The time required to upgrade a machine pool varies according to the number of worker nodes in the machine pool (`--replicas` or `--max-replicas`).
-
-You can further control the time required for an upgrade, and the impact of an upgrade to your workload, by editing the `--max-surge` and `--max-unavailable` values for each machine pool. These options control the number of nodes that can be upgraded simultaneously, and whether an upgrade provisions excess nodes or makes some existing nodes unavailable or both, for example:
+You can further control the time required for a machine pool upgrade, and the impact of an upgrade to your workload, by editing the `--max-surge` and `--max-unavailable` values for each machine pool. These options control the number of nodes that can be upgraded simultaneously on a machine pool, and whether an upgrade provisions excess nodes or makes some existing nodes unavailable or both, for example:
 
 * **To prioritize high workload availability**, you can provision excess nodes instead of making existing nodes unavailable by setting a higher value for `--max-surge` and setting `--max-unavailable` to `0`.
 * **To prioritize lower infrastructure costs**, you can make some existing nodes unavailable and avoid provisioning excess nodes by setting a higher value for `--max-unavailable` and setting `--max-surge` to `0`.

modules/rosa-hcp-upgrading-cli-machinepool.adoc

@@ -10,7 +10,7 @@
 ifeval::["{context}" != "rosa-hcp-upgrading-whole-cluster"]
 = Upgrading machine pools with the ROSA CLI
 
-You can manually upgrade one or more machine pools in a {hcp-title} cluster by using the ROSA CLI. This method schedules the specified machine pools for an upgrade if a more recent version is available, either immediately, or at a specified future time.
+You can manually upgrade one or more machine pools in a {hcp-title} cluster by using the ROSA CLI. This method schedules the specified machine pool for an upgrade if a more recent version is available, either immediately, or at a specified future time.
 
 [NOTE]
 ====
@@ -27,7 +27,7 @@ endif::[]
 ifeval::["{context}" == "rosa-hcp-upgrading-whole-cluster"]
 = Upgrading machine pools
 
-When your hosted control plane upgrade is complete, you can upgrade one or more machine pools simultaneously.
+When your hosted control plane upgrade is complete, you can upgrade one or more machine pools.
 endif::[]
 //END WHOLE CLUSTER condition
 
@@ -85,7 +85,7 @@ Do not upgrade your machine pool to a version higher than your control plane. If
 +
 [source,terminal]
 ----
-$ rosa describe machinepool --cluster=<cluster_name_or_id> <machine_pool_name> 
+$ rosa describe machinepool --cluster=<cluster_name_or_id> <machinepool_name> 
 ----
 +
 .Example output
@@ -102,32 +102,32 @@ Management upgrade:
 +
 In the example, these settings allow the machine pool to provision one excess node (`max-surge` of 20% of `replicas`) and to have up to one node unavailable (`max-unavailable` of 20% of `replicas`) during an upgrade. This machine pool can therefore upgrade two nodes at a time, by provisioning one new node in excess of the replica count, and by making one node unavailable and replacing it. Node upgrades may be delayed by up to 30 minutes (`node-drain-grace-period` of 30 minutes) if necessary to protect workloads that have a pod disruption budget.
 
-. Upgrade one or more of your machine pools by running the following command:
+. Upgrade a machine pool by running the following command:
 +
 [source,terminal]
 ----
-$ rosa upgrade machinepool -c <cluster_name> <first_machine_pool_id> <second_machine_pool_id> [--schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm>] --version <version_number>
+$ rosa upgrade machinepool -c <cluster_name> <machinepool_name> [--schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm>] --version <version_number>
 ----
 +
-Multiple machine pools can be upgraded simultaneously. You can schedule machine pool upgrades individually or schedule multiple upgrades in a single command.
+You can upgrade multiple machine pools concurrently by running this command for each machine pool you want to upgrade.
 
-** To schedule the immediate upgrade of a specific machine pool on your cluster, run the following command:
+** To schedule the immediate upgrade of a machine pool:
 +
 [source,terminal]
 ----
-$ rosa upgrade machinepool -c <cluster_name> <your_machine_pool_id> --version <version_number>
+$ rosa upgrade machinepool -c <cluster_name> <machinepool_name> --version <version_number>
 ----
 +
-Your machine pool is scheduled for immediate upgrade, which initiates a rolling replacement of all nodes in the specified machine pool.
+The machine pool is scheduled for immediate upgrade, which initiates a rolling replacement of all nodes in the specified machine pool.
 
-** To schedule an upgrade of multiple machine pools to start at a future date, run the following command:
+** To schedule an upgrade to start at a future time:
 +
 [source,terminal]
 ----
-$ rosa upgrade machinepool -c <cluster_name> <first_machine_pool_id> <second_machine_pool_id> --schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm> --version <version_number>
+$ rosa upgrade machinepool -c <cluster_name> <machinepool_name> --schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm> --version <version_number>
 ----
 +
-Your machine pools are scheduled to begin an upgrade at the specified time and date in Coordinated Universal Time (UTC). This will initiate a rolling replacement of all nodes in the specified machine pools, beginning at the specified time.
+The machine pool is scheduled to begin an upgrade at the specified time and date in Coordinated Universal Time (UTC). This will initiate a rolling replacement of all nodes in the specified machine pool, beginning at the specified time.
 
 .Troubleshooting
 * Sometimes a scheduled upgrade does not initiate. See link:https://access.redhat.com/solutions/6648291[Upgrade maintenance canceled] for more information.

modules/rosa-hcp-upgrading-cli-tutorial.adoc

@@ -28,7 +28,7 @@ $ rosa describe cluster --cluster=<cluster_name_or_id> <1>
 <1> Replace `<cluster_name_or_id>` with the cluster name or the cluster ID.
 
 . List the versions that you can upgrade your control plane and machine pools to by running the following commands:
-+
+
 .. For the control plane versions, run the following command:
 +
 [source,terminal]
@@ -47,7 +47,7 @@ VERSION  NOTES
 4.14.7
 4.14.6
 ----
-+
+
 .. For the machine pool versions, run the following command:
 +
 [source,terminal]
@@ -65,8 +65,6 @@ VERSION  NOTES
 4.14.5   recommended
 4.14.4
 4.14.3
-4.14.2
-4.14.1
 ----
 +
 [NOTE]
@@ -75,6 +73,7 @@ The latest available update for machine pools is limited to the current current
 ====
 
 . Upgrade your cluster with one of the following options:
+
 ** Upgrade the cluster's hosted control plane by running the following command:
 +
 [source,terminal]
@@ -88,19 +87,10 @@ Your hosted control plane is now scheduled for an upgrade.
 +
 [source,terminal]
 ----
-$ rosa upgrade machinepool -c <cluster_name> <your_machine_pool_id> [--schedule-date=XX --schedule-time=XX] [--version <version_number>]
+$ rosa upgrade machinepool -c <cluster_name> <machinepool_name> [--schedule-date=XX --schedule-time=XX] [--version <version_number>]
 ----
 +
 Your machine pool is now scheduled for an upgrade.
-//
-// ** Upgrade both the hosted control plane and all attached machine pools by running the following command:
-// +
-// [source,terminal]
-// ----
-// $ rosa upgrade cluster -c <cluster_name> [--schedule-date=XX --schedule-time=XX] [--version <version_number>]
-// ----
-// +
-// Your hosted control plane and machine pools are now scheduled for an upgrade.
 
 .Troubleshooting
 * Sometimes a scheduled upgrade does not initiate. See link:https://access.redhat.com/solutions/6648291[Upgrade maintenance cancelled] for more information.

modules/rosa-upgrade-cluster-cli.adoc

@@ -113,7 +113,7 @@ $ rosa delete upgrade --cluster=<cluster_name> | <cluster_id>
 [id="rosa-upgrade-machinepool_{context}"]
 == upgrade machinepool
 
-Upgrades a specific machine pool configured on a cluster.
+Upgrades a specific machine pool configured on a {hcp-title} cluster.
 
 [NOTE]
 ====