Merge pull request #19675 from kalexand-rh/BZ1781064

bug 1781064 clarifying max nodes

Author: kalexand-rh

modules/cluster-autoscaler-about.adoc

@@ -11,38 +11,43 @@ provide infrastructure management that does not rely on objects of a specific
 cloud provider. The ClusterAutoscaler has a cluster scope, and is not associated
 with a particular namespace.
 
-The ClusterAutoscaler increases the size of the cluster when there are pods
+The ClusterAutoscaler increases the size of the cluster when there are Pods
 that failed to schedule on any of the current nodes due to insufficient
 resources or when another node is necessary to meet deployment needs. The
 ClusterAutoscaler does not increase the cluster resources beyond the limits
 that you specify.
 
+[IMPORTANT]
+====
+Ensure that the `maxNodesTotal` value in the `ClusterAutoscaler` definition that you create is large enough to account for the total possible number of machines in your cluster. This value must encompass the number of control plane machines and the possible number of compute machines that you might scale to.
+====
+
 The ClusterAutoscaler decreases the size of the cluster when some nodes are
 consistently not needed for a significant period, such as when it has low
-resource use and all of its important pods can fit on other nodes.
+resource use and all of its important Pods can fit on other nodes.
 
-If the following types of pods are present on a node, the ClusterAutoscaler
+If the following types of Pods are present on a node, the ClusterAutoscaler
 will not remove the node:
 
 * Pods with restrictive PodDisruptionBudgets (PDBs).
-* Kube-system pods that do not run on the node by default.
-* Kube-system pods that do not have a PDBB or have a PDB that is too restrictive.
+* Kube-system Pods that do not run on the node by default.
+* Kube-system Pods that do not have a PDBB or have a PDB that is too restrictive.
 * Pods that are not backed by a controller object such as a Deployment,
 ReplicaSet, or StatefulSet.
 * Pods with local storage.
 * Pods that cannot be moved elsewhere because of a lack of resources,
 incompatible node selectors or affinity, matching anti-affinity, and so on.
 * Unless they also have a `"cluster-autoscaler.kubernetes.io/safe-to-evict": "true"`
-annotation, pods that have a `"cluster-autoscaler.kubernetes.io/safe-to-evict": "false"`
+annotation, Pods that have a `"cluster-autoscaler.kubernetes.io/safe-to-evict": "false"`
 annotation.
 
 If you configure the ClusterAutoscaler, additional usage restrictions apply:
 
 * Do not modify the nodes that are in autoscaled node groups directly. All nodes
 within the same node group have the same capacity and labels and run the same
-system pods.
-* Specify requests for your pods.
-* If you have to prevent pods from being deleted too quickly, configure
+system Pods.
+* Specify requests for your Pods.
+* If you have to prevent Pods from being deleted too quickly, configure
 appropriate PDBs.
 * Confirm that your cloud provider quota is large enough to support the
 maximum node pools that you configure.
@@ -56,28 +61,27 @@ number of replicas based on the current CPU load.
 If the load increases, the HPA creates new replicas, regardless of the amount
 of resources available to the cluster.
 If there are not enough resources, the ClusterAutoscaler adds resources so that
-the HPA-created pods can run.
+the HPA-created Pods can run.
 If the load decreases, the HPA stops some replicas. If this action causes some
 nodes to be underutilized or completely empty, the ClusterAutoscaler deletes
 the unnecessary nodes.
 
 
-The ClusterAutoscaler takes pod priorities into account. The Pod Priority and
-Preemption feature enables scheduling pods based on priorities if the cluster
+The ClusterAutoscaler takes Pod priorities into account. The Pod Priority and
+Preemption feature enables scheduling Pods based on priorities if the cluster
 does not have enough resources, but the ClusterAutoscaler ensures that the
-cluster has resources to run all pods. To honor the intention of both features,
+cluster has resources to run all Pods. To honor the intention of both features,
 the ClusterAutoscaler inclues a priority cutoff function. You can use this cutoff to
-schedule "best-effort" pods, which do not cause the ClusterAutoscaler to
+schedule "best-effort" Pods, which do not cause the ClusterAutoscaler to
 increase resources but instead run only when spare resources are available.
 
 Pods with priority lower than the cutoff value do not cause the cluster to scale
 up or prevent the cluster from scaling down. No new nodes are added to run the
-pods, and nodes running these pods might be deleted to free resources.
+Pods, and nodes running these Pods might be deleted to free resources.
 
 ////
 Default priority cutoff is 0. It can be changed using `--expendable-pods-priority-cutoff` flag,
 but we discourage it.
-ClusterAutoscaler also doesn't trigger scale-up if an unschedulable pod is already waiting for a lower
-priority pod preemption.
+ClusterAutoscaler also doesn't trigger scale-up if an unschedulable Pod is already waiting for a lower
+priority Pod preemption.
 ////
-

modules/cluster-autoscaler-cr.adoc

@@ -43,7 +43,7 @@ spec:
 to deploy additional nodes. Enter a 32-bit integer value. The
 `podPriorityThreshold` value is compared to the value of the `PriorityClass` that
 you assign to each pod.
-<2> Specify the maximum number of nodes to deploy.
+<2> Specify the maximum number of nodes to deploy. This value is the total number of machines that are deployed in your cluster, not just the ones that the autoscaler controls. Ensure that this value is large enough to account for all of your control plane and compute machines and the total number of replicas that you specify in your `MachineAutoscaler` resources.
 <3> Specify the minimum number of cores to deploy.
 <4> Specify the maximum number of cores to deploy.
 <5> Specify the minimum amount of memory, in GiB, per node.

modules/machine-autoscaler-cr.adoc

@@ -28,10 +28,10 @@ spec:
 which MachineSet this MachineAutoscaler scales, specify or include the name of
 the MachineSet to scale. The MachineSet name takes the following form:
 `<clusterid>-<machineset>-<aws-region-az>`
-<2> Specify the minimum number Machines of the specified type to deploy in the
-specified AWS zone. Do not set this value to `0`.
-<3> Specify the maximum number Machines of the specified type to deploy in the
-specified AWS zone.
+<2> Specify the minimum number Machines of the specified type that must remain in the
+specified AWS zone after the ClusterAutoscaler initiates cluster scaling. Do not set this value to `0`.
+<3> Specify the maximum number Machines of the specified type that the ClusterAutoscaler can deploy in the
+specified AWS zone after it initiates cluster scaling. Ensure that the `maxNodesTotal` value in the `ClusterAutoscaler` definition is large enough to allow the MachineAutoScaler to deploy this number of machines.
 <4> In this section, provide values that describe the existing MachineSet to
 scale.
 <5> The `kind` parameter value is always `MachineSet`.