Merge pull request #71679 from fmcdonal/OSDOCS-9028

OSDOCS#9028: Selecting a single AZ in a multi AZ cluster for a machinepool

Author: adellape

modules/creating-a-machine-pool-cli.adoc

@@ -18,6 +18,7 @@ You can create additional machine pools for your {product-title} (ROSA) cluster
 
 * To add a machine pool that does not use autoscaling, create the machine pool and define the instance type, compute (also known as worker) node count, and node labels:
 +
+--
 [source,terminal]
 ----
 $ rosa create machinepool --cluster=<cluster-name> \
@@ -30,7 +31,7 @@ $ rosa create machinepool --cluster=<cluster-name> \
                           --spot-max-price=0.5 \ <7>
 ifdef::openshift-rosa[]
                           --disk-size=<disk_size> <8>
-                          --availability-zone=<az> <9>
+                          --availability-zone=<availability_zone_name> <9>
                           --additional-security-group-ids <sec_group_id> <10>
 
 endif::openshift-rosa[]
@@ -41,17 +42,32 @@ endif::openshift-rosa[]
 <4> Optional: Defines the labels for the machine pool. Replace `<key>=<value>,<key>=<value>` with a comma-delimited list of key-value pairs, for example `--labels=key1=value1,key2=value2`.
 <5> Optional: Defines the taints for the machine pool. Replace `<key>=<value>:<effect>,<key>=<value>:<effect>` with a key, value, and effect for each taint, for example `--taints=key1=value1:NoSchedule,key2=value2:NoExecute`. Available effects include `NoSchedule`, `PreferNoSchedule`, and `NoExecute`.
 <6> Optional: Configures your machine pool to deploy machines as non-guaranteed AWS Spot Instances. For information, see link:https://aws.amazon.com/ec2/spot/[Amazon EC2 Spot Instances] in the AWS documentation. If you select *Use Amazon EC2 Spot Instances* for a machine pool, you cannot disable the option after the machine pool is created.
-<7> Optional: If you have opted to use Spot Instances, you can specify this argument to define a maximum hourly price for a Spot Instance. If this argument is not specified, the on-demand price is used.
-ifdef::openshift-rosa[]
-<8> Optional: Specifies the worker node disk size. The value can be in GB, GiB, TB, or TiB. Replace `<disk_size>` with a numeric value and unit, for example `--disk-size=200GiB`.
-<9> Optional: For Multi-AZ clusters, you can create a machine pool in a Single-AZ of your choice. Replace `<az>` with a Single-AZ.
-<10> Optional: For machine pools in clusters that do not have Red Hat managed VPCs, you can select additional custom security groups to use in your machine pools. You must have already created the security groups and associated them with the VPC that you selected for this cluster. You cannot add or edit security groups after you create the machine pool. For more information, see the requirements for security groups in the "Additional resources" section.
-endif::openshift-rosa[]
+<7> Optional: If you choose to use Spot Instances, you can specify this argument to define a maximum hourly price for a Spot Instance. If this argument is not specified, the on-demand price is used.
 +
 [IMPORTANT]
 ====
 Your Amazon EC2 Spot Instances might be interrupted at any time. Use Amazon EC2 Spot Instances only for workloads that can tolerate interruptions.
 ====
+ifdef::openshift-rosa[]
+<8> Optional: Specifies the worker node disk size. The value can be in GB, GiB, TB, or TiB. Replace `<disk_size>` with a numeric value and unit, for example `--disk-size=200GiB`.
+<9> Optional: For Multi-AZ clusters, you can create a machine pool in a Single-AZ of your choice. Replace `<az>` with a Single-AZ name.
++
+[NOTE]
+====
+Multi-AZ clusters retain a Multi-AZ control plane and can have worker machine pools across a Single-AZ or Multi-AZ. Machine pools distribute machines (nodes) evenly across availability zones.
+====
++
+[WARNING]
+====
+If you choose a worker machine pool with a Single-AZ, there is no fault tolerance for that machine pool, regardless of machine replica count. 
+For fault-tolerant worker machine pools, choosing a Multi-AZ machine pool distributes machines in multiples of 3 across availability zones. 
+
+* A Multi-AZ machine pool with three availability zones can have a machine count in multiples of 3 only, such as 3, 6, 9, and so on. 
+* A Single-AZ machine pool with one availability zone can have a machine count in multiples of 1, such as 1,2,3,4 and so on.
+====
+<10> Optional: For machine pools in clusters that do not have Red Hat managed VPCs, you can select additional custom security groups to use in your machine pools. You must have already created the security groups and associated them with the VPC that you selected for this cluster. You cannot add or edit security groups after you create the machine pool. For more information, see the requirements for security groups in the "Additional resources" section.
+endif::openshift-rosa[]
+--
 +
 The following example creates a machine pool called `mymachinepool` that uses the `m5.xlarge` instance type and has 2 compute node replicas. The example also adds 2 workload-specific labels:
 +
@@ -69,6 +85,7 @@ I: To view all machine pools, run 'rosa list machinepools -c mycluster'
 
 * To add a machine pool that uses autoscaling, create the machine pool and define the autoscaling configuration, instance type and node labels:
 +
+--
 [source,terminal]
 ----
 $ rosa create machinepool --cluster=<cluster-name> \
@@ -81,7 +98,7 @@ $ rosa create machinepool --cluster=<cluster-name> \
                           --taints=<key>=<value>:<effect>,<key>=<value>:<effect> \ <6>
                           --use-spot-instances \ <7>
                           --spot-max-price=0.5 <8>
-                          --availability-zone=<az> <9>
+                          --availability-zone=<availability_zone_name> <9>
 ----
 <1> Specifies the name of the machine pool. Replace `<machine_pool_id>` with the name of your machine pool.
 <2> Enables autoscaling in the machine pool to meet the deployment needs.
@@ -90,13 +107,14 @@ $ rosa create machinepool --cluster=<cluster-name> \
 <5> Optional: Defines the labels for the machine pool. Replace `<key>=<value>,<key>=<value>` with a comma-delimited list of key-value pairs, for example `--labels=key1=value1,key2=value2`.
 <6> Optional: Defines the taints for the machine pool. Replace `<key>=<value>:<effect>,<key>=<value>:<effect>` with a key, value, and effect for each taint, for example `--taints=key1=value1:NoSchedule,key2=value2:NoExecute`. Available effects include `NoSchedule`, `PreferNoSchedule`, and `NoExecute`.
 <7> Optional: Configures your machine pool to deploy machines as non-guaranteed AWS Spot Instances. For information, see link:https://aws.amazon.com/ec2/spot/[Amazon EC2 Spot Instances] in the AWS documentation. If you select *Use Amazon EC2 Spot Instances* for a machine pool, you cannot disable the option after the machine pool is created.
-<8> Optional: If you have opted to use Spot Instances, you can specify this argument to define a maximum hourly price for a Spot Instance. If this argument is not specified, the on-demand price is used.
-<9> Optional: For Multi-AZ clusters, you can create a machine pool in a Single-AZ of your choice. Replace `<az>` with a Single-AZ.
 +
 [IMPORTANT]
 ====
 Your Amazon EC2 Spot Instances might be interrupted at any time. Use Amazon EC2 Spot Instances only for workloads that can tolerate interruptions.
 ====
+<8> Optional: If you choose to use Spot Instances, you can specify this argument to define a maximum hourly price for a Spot Instance. If this argument is not specified, the on-demand price is used.
+<9> Optional: For Multi-AZ clusters, you can create a machine pool in a Single-AZ of your choice. Replace `<az>` with a Single-AZ name.
+--
 +
 The following example creates a machine pool called `mymachinepool` that uses the `m5.xlarge` instance type and has autoscaling enabled. The minimum compute node limit is 3 and the maximum is 6 overall. The example also adds 2 workload-specific labels:
 +

rosa_release_notes/rosa-release-notes.adoc

@@ -16,6 +16,8 @@ toc::[]
 [id="rosa-q1-2024_{context}"]
 === Q1 2024
 
+* **Availability zone update.** You can now optionally select a single availability zone (AZ) for machine pools when you have a multi-AZ cluster. For more information, see xref:../rosa_cluster_admin/rosa_nodes/rosa-managing-worker-nodes.adoc#creating_machine_pools_cli_rosa-managing-worker-nodes[Creating a machine pool using the ROSA CLI].
+
 * **ROSA CLI update.** The ROSA CLI (`rosa`) was updated to a new version. For information about what has changed in this release, see the link:https://github.com/openshift/rosa/releases/tag/v1.2.35[ROSA CLI release notes]. For more information about the ROSA CLI (`rosa`), see xref:../cli_reference/rosa_cli/rosa-get-started-cli.adoc#rosa-about_rosa-getting-started-cli[About the ROSA CLI].
 
 [id="rosa-q4-2023_{context}"]