Merge pull request #97879 from brendan-daly-red-hat/OSDOCS-15411_a

OSDOCS-15411_a#CQA updates

Author: skopacz1

modules/nodes-pods-autoscaling-about.adoc

@@ -6,30 +6,16 @@
 [id="nodes-pods-autoscaling-about_{context}"]
 = Understanding horizontal pod autoscalers
 
-You can create a horizontal pod autoscaler to specify the minimum and maximum number of pods
-you want to run, as well as the CPU utilization or memory utilization your pods should target.
-
-After you create a horizontal pod autoscaler, {product-title} begins to query the CPU and/or memory resource metrics on the pods.
-When these metrics are available, the horizontal pod autoscaler computes
-the ratio of the current metric utilization with the desired metric utilization,
-and scales up or down accordingly. The query and scaling occurs at a regular interval,
-but can take one to two minutes before metrics become available.
-
-For replication controllers, this scaling corresponds directly to the replicas
-of the replication controller. For deployment configurations, scaling corresponds
-directly to the replica count of the deployment configuration. Note that autoscaling
-applies only to the latest deployment in the `Complete` phase.
-
-{product-title} automatically accounts for resources and prevents unnecessary autoscaling
-during resource spikes, such as during start up. Pods in the `unready` state
-have `0 CPU` usage when scaling up and the autoscaler ignores the pods when scaling down.
-Pods without known metrics have `0% CPU` usage when scaling up and `100% CPU` when scaling down.
-This allows for more stability during the HPA decision. To use this feature, you must configure
-readiness checks to determine if a new pod is ready for use.
+You can create a horizontal pod autoscaler to specify the minimum and maximum number of pods you want to run, and the CPU usage or memory usage your pods should target.
+
+After you create a horizontal pod autoscaler, {product-title} begins to query the CPU, memory, or both resource metrics on the pods. When these metrics are available, the horizontal pod autoscaler computes the ratio of the current metric use with the intended metric use, and scales up or down as needed. The query and scaling occurs at a regular interval, but can take one to two minutes before metrics become available.
+
+For replication controllers, this scaling corresponds directly to the replicas of the replication controller. For deployment, scaling corresponds directly to the replica count of the deployment. Note that autoscaling applies only to the latest deployment in the `Complete` phase.
+
+{product-title} automatically accounts for resources and prevents unnecessary autoscaling during resource spikes, such as during start up. Pods in the `unready` state have `0 CPU` usage when scaling up and the autoscaler ignores the pods when scaling down. Pods without known metrics have `0% CPU` usage when scaling up and `100% CPU` when scaling down. This allows for more stability during the HPA decision. To use this feature, you must configure readiness checks to determine if a new pod is ready for use.
 
 ifdef::openshift-origin,openshift-enterprise,openshift-webscale[]
-To use horizontal pod autoscalers, your cluster administrator must have
-properly configured cluster metrics.
+To use horizontal pod autoscalers, your cluster administrator must have properly configured cluster metrics.
 endif::openshift-origin,openshift-enterprise,openshift-webscale[]
 
 == Supported metrics
@@ -43,27 +29,24 @@ The following metrics are supported by horizontal pod autoscalers:
 |Metric |Description |API version
 
 |CPU utilization
-|Number of CPU cores used. Can be used to calculate a percentage of the pod's requested CPU.
+|Number of CPU cores used. You can use this to calculate a percentage of the pod's requested CPU.
 |`autoscaling/v1`, `autoscaling/v2`
 
 |Memory utilization
-|Amount of memory used. Can be used to calculate a percentage of the pod's requested memory.
+|Amount of memory used. You can use this to calculate a percentage of the pod's requested memory.
 |`autoscaling/v2`
 |===
 
 [IMPORTANT]
 ====
-For memory-based autoscaling, memory usage must increase and decrease
-proportionally to the replica count. On average:
+For memory-based autoscaling, memory usage must increase and decrease proportionally to the replica count. On average:
 
 * An increase in replica count must lead to an overall decrease in memory
 (working set) usage per-pod.
 * A decrease in replica count must lead to an overall increase in per-pod memory
 usage.
 
-Use the {product-title} web console to check the memory behavior of your application
-and ensure that your application meets these requirements before using
-memory-based autoscaling.
+Use the {product-title} web console to check the memory behavior of your application and ensure that your application meets these requirements before using memory-based autoscaling.
 ====
 
 The following example shows autoscaling for the `hello-node` `Deployment` object. The initial deployment requires 3 pods. The HPA object increases the minimum to 5. If CPU usage on the pods reaches 75%, the pods increase to 7:

modules/nodes-pods-autoscaling-best-practices-hpa.adoc

@@ -6,14 +6,13 @@
 [id="nodes-pods-autoscaling-best-practices-hpa_{context}"]
 = Best practices
 
-.All pods must have resource requests configured
-The HPA makes a scaling decision based on the observed CPU or memory utilization values of pods in an {product-title} cluster. Utilization values are calculated as a percentage of the resource requests of each pod.
-Missing resource request values can affect the optimal performance of the HPA.
+For optimal performance, configure resource requests for all pods. To prevent frequent replica fluctuations, configure the cooldown period.
 
-.Configure the cool down period
-During horizontal pod autoscaling, there might be a rapid scaling of events without a time gap. Configure the cool down period to prevent frequent replica fluctuations.
-You can specify a cool down period by configuring the `stabilizationWindowSeconds` field. The stabilization window is used to restrict the fluctuation of replicas count when the metrics used for scaling keep fluctuating.
-The autoscaling algorithm uses this window to infer a previous desired state and avoid unwanted changes to workload scale.
+All pods must have resource requests configured::
+The HPA makes a scaling decision based on the observed CPU or memory usage values of pods in an {product-title} cluster. Utilization values are calculated as a percentage of the resource requests of each pod. Missing resource request values can affect the optimal performance of the HPA.
+
+Configure the cool down period::
+During horizontal pod autoscaling, there might be a rapid scaling of events without a time gap. Configure the cool down period to prevent frequent replica fluctuations. You can specify a cool down period by configuring the `stabilizationWindowSeconds` field. The stabilization window is used to restrict the fluctuation of replicas count when the metrics used for scaling keep fluctuating. The autoscaling algorithm uses this window to infer a previous required state and avoid unwanted changes to workload scale.
 
 For example, a stabilization window is specified for the `scaleDown` field:
 
@@ -24,4 +23,4 @@ behavior:
     stabilizationWindowSeconds: 300
 ----
 
-In the above example, all desired states for the past 5 minutes are considered. This approximates a rolling maximum, and avoids having the scaling algorithm frequently remove pods only to trigger recreating an equivalent pod just moments later.
+In the previous example, all intended states for the past 5 minutes are considered. This approximates a rolling maximum, and avoids having the scaling algorithm often remove pods only to trigger recreating an equal pod just moments later.

modules/nodes-pods-autoscaling-policies.adoc

@@ -2,10 +2,11 @@
 //
 // * nodes/nodes-pods-autoscaling.adoc
 
+:_mod-docs-content-type: CONCEPT
 [id="nodes-pods-autoscaling-policies_{context}"]
 = Scaling policies
 
-The `autoscaling/v2` API allows you to add _scaling policies_ to a horizontal pod autoscaler. A scaling policy controls how the {product-title} horizontal pod autoscaler (HPA) scales pods. Scaling policies allow you to restrict the rate that HPAs scale pods up or down by setting a specific number or specific percentage to scale in a specified period of time. You can also define a _stabilization window_, which uses previously computed desired states to control scaling if the metrics are fluctuating. You can create multiple policies for the same scaling direction, and determine which policy is used, based on the amount of change. You can also restrict the scaling by timed iterations. The HPA scales pods during an iteration, then performs scaling, as needed, in further iterations.
+Use the `autoscaling/v2` API to add _scaling policies_ to a horizontal pod autoscaler. A scaling policy controls how the {product-title} horizontal pod autoscaler (HPA) scales pods. Use scaling policies to restrict the rate that HPAs scale pods up or down by setting a specific number or specific percentage to scale in a specified period of time. You can also define a _stabilization window_, which uses previously computed required states to control scaling if the metrics are fluctuating. You can create multiple policies for the same scaling direction, and determine the policy to use, based on the amount of change. You can also restrict the scaling by timed iterations. The HPA scales pods during an iteration, then performs scaling, as needed, in further iterations.
 
 .Sample HPA object with a scaling policy
 [source, yaml]
@@ -45,8 +46,8 @@ spec:
 <4> Limits the amount of scaling, either the number of pods or percentage of pods, during each iteration. There is no default value for scaling down by number of pods.
 <5> Determines the length of a scaling iteration. The default value is `15` seconds.
 <6> The default value for scaling down by percentage is 100%.
-<7> Determines which policy to use first, if multiple policies are defined. Specify `Max` to use the policy that allows the highest amount of change, `Min` to use the policy that allows the lowest amount of change, or `Disabled` to prevent the HPA from scaling in that policy direction. The default value is `Max`.
-<8> Determines the time period the HPA should look back at desired states. The default value is `0`.
+<7> Determines the policy to use first, if multiple policies are defined. Specify `Max` to use the policy that allows the highest amount of change, `Min` to use the policy that allows the lowest amount of change, or `Disabled` to prevent the HPA from scaling in that policy direction. The default value is `Max`.
+<8> Determines the time period the HPA reviews the required states. The default value is `0`.
 <9> This example creates a policy for scaling up.
 <10> Limits the amount of scaling up by the number of pods. The default value for scaling up the number of pods is 4%.
 <11> Limits the amount of scaling up by the percentage of pods. The default value for scaling up by percentage is 100%.
@@ -80,7 +81,7 @@ spec:
 
 In this example, when the number of pods is greater than 40, the percent-based policy is used for scaling down, as that policy results in a larger change, as required by the `selectPolicy`.
 
-If there are 80 pod replicas, in the first iteration the HPA reduces the pods by 8, which is 10% of the 80 pods (based on the `type: Percent` and `value: 10` parameters), over one minute (`periodSeconds: 60`). For the next iteration, the number of pods is 72. The HPA calculates that 10% of the remaining pods is 7.2, which it rounds up to 8 and scales down 8 pods. On each subsequent iteration, the number of pods to be scaled is re-calculated based on the number of remaining pods. When the number of pods falls below 40, the pods-based policy is applied, because the pod-based number is greater than the percent-based number. The HPA reduces 4 pods at a time (`type: Pods` and `value: 4`), over 30 seconds (`periodSeconds: 30`), until there are 20 replicas remaining (`minReplicas`).
+If there are 80 pod replicas, in the first iteration the HPA reduces the pods by 8, which is 10% of the 80 pods (based on the `type: Percent` and `value: 10` parameters), over one minute (`periodSeconds: 60`). For the next iteration, the number of pods is 72. The HPA calculates that 10% of the remaining pods is 7.2, which it rounds up to 8 and scales down 8 pods. On each subsequent iteration, the number of pods to be scaled is re-calculated based on the number of remaining pods. When the number of pods falls to less than 40, the pods-based policy is applied, because the pod-based number is greater than the percent-based number. The HPA reduces 4 pods at a time (`type: Pods` and `value: 4`), over 30 seconds (`periodSeconds: 30`), until there are 20 replicas remaining (`minReplicas`).
 
 The `selectPolicy: Disabled` parameter prevents the HPA from scaling up the pods. You can manually scale up by adjusting the number of replicas in the replica set or deployment set, if needed.
 

modules/nodes-pods-vertical-autoscaler-about.adoc

@@ -6,35 +6,35 @@
 [id="nodes-pods-vertical-autoscaler-about_{context}"]
 = About the Vertical Pod Autoscaler Operator
 
-The Vertical Pod Autoscaler Operator (VPA) is implemented as an API resource and a custom resource (CR). The CR determines the actions that the VPA Operator should take with the pods associated with a specific workload object, such as a daemon set, replication controller, and so forth, in a project.
+The Vertical Pod Autoscaler Operator (VPA) is implemented as an API resource and a custom resource (CR). The CR determines the actions for the VPA to take with the pods associated with a specific workload object, such as a daemon set, replication controller, and so forth, in a project.
 
-The VPA Operator consists of three components, each of which has its own pod in the VPA namespace:
+The VPA consists of three components, each of which has its own pod in the VPA namespace:
 
 Recommender::
-The VPA recommender monitors the current and past resource consumption and, based on this data, determines the optimal CPU and memory resources for the pods in the associated workload object.
+The VPA recommender monitors the current and past resource consumption. Based on this data, the VPA recommender determines the optimal CPU and memory resources for the pods in the associated workload object.
 
 Updater::
-The VPA updater checks if the pods in the associated workload object have the correct resources. If the resources are correct, the updater takes no action. If the resources are not correct, the updater kills the pod so that they can be recreated by their controllers with the updated requests.
+The VPA updater checks if the pods in the associated workload object have the correct resources. If the resources are correct, the updater takes no action. If the resources are not correct, the updater kills the pod so that pods' controllers can re-create them with the updated requests.
 
 Admission controller::
-The VPA admission controller sets the correct resource requests on each new pod in the associated workload object, whether the pod is new or was recreated by its controller due to the VPA updater actions.
+The VPA admission controller sets the correct resource requests on each new pod in the associated workload object. This applies whether the pod is new or the controller re-created the pod due to the VPA updater actions.
 
 You can use the default recommender or use your own alternative recommender to autoscale based on your own algorithms.
 
-The default recommender automatically computes historic and current CPU and memory usage for the containers in those pods and uses this data to determine optimized resource limits and requests to ensure that these pods are operating efficiently at all times. For example, the default recommender suggests reduced resources for pods that are requesting more resources than they are using and increased resources for pods that are not requesting enough.
+The default recommender automatically computes historic and current CPU and memory usage for the containers in those pods. The default recommender uses this data to determine optimized resource limits and requests to ensure that these pods are operating efficiently at all times. For example, the default recommender suggests reduced resources for pods that are requesting more resources than they are using and increased resources for pods that are not requesting enough.
 
-The VPA then automatically deletes any pods that are out of alignment with these recommendations one at a time, so that your applications can continue to serve requests with no downtime. The workload objects then redeploy the pods with the original resource limits and requests. The VPA uses a mutating admission webhook to update the pods with optimized resource limits and requests before the pods are admitted to a node. If you do not want the VPA to delete pods, you can view the VPA resource limits and requests and manually update the pods as needed.
+The VPA then automatically deletes any pods that are out of alignment with these recommendations one at a time, so that your applications can continue to serve requests with no downtime. The workload objects then redeploy the pods with the original resource limits and requests. The VPA uses a mutating admission webhook to update the pods with optimized resource limits and requests before admitting the pods to a node. If you do not want the VPA to delete pods, you can view the VPA resource limits and requests and manually update the pods as needed.
 
 [NOTE]
 ====
-By default, workload objects must specify a minimum of two replicas in order for the VPA to automatically delete their pods. Workload objects that specify fewer replicas than this minimum are not deleted. If you manually delete these pods, when the workload object redeploys the pods, the VPA does update the new pods with its recommendations. You can change this minimum by modifying the `VerticalPodAutoscalerController` object as shown in _Changing the VPA minimum value_.
+By default, workload objects must specify a minimum of two replicas for the VPA to automatically delete their pods. Workload objects that specify fewer replicas than this minimum are not deleted. If you manually delete these pods, when the workload object redeploys the pods, the VPA updates the new pods with its recommendations. You can change this minimum by modifying the `VerticalPodAutoscalerController` object as shown in _Changing the VPA minimum value_.
 ====
 
 For example, if you have a pod that uses 50% of the CPU but only requests 10%, the VPA determines that the pod is consuming more CPU than requested and deletes the pod. The workload object, such as replica set, restarts the pods and the VPA updates the new pod with its recommended resources.
 
-For developers, you can use the VPA to help ensure your pods stay up during periods of high demand by scheduling pods onto nodes that have appropriate resources for each pod.
+For developers, you can use the VPA to help ensure that your pods active during periods of high demand by scheduling pods onto nodes that have appropriate resources for each pod.
 
-Administrators can use the VPA to better utilize cluster resources, such as preventing pods from reserving more CPU resources than needed. The VPA monitors the resources that workloads are actually using and adjusts the resource requirements so capacity is available to other workloads. The VPA also maintains the ratios between limits and requests that are specified in initial container configuration.
+Administrators can use the VPA to better use cluster resources, such as preventing pods from reserving more CPU resources than needed. The VPA monitors the resources that workloads are actually using and adjusts the resource requirements so capacity is available to other workloads. The VPA also maintains the ratios between limits and requests specified in the initial container configuration.
 
 [NOTE]
 ====