Need new section to address horizontal-pod-autoscaler-downscale-stabilization parameter

Author: mburke5678

modules/nodes-pods-autoscaling-creating-memory.adoc

@@ -95,6 +95,17 @@ spec:
       target:
         type: AverageValue <10>
         averageValue: 500Mi <11>
+  behavior: <12>
+    scaleDown:
+      stabilizationWindowSeconds: 300
+      policies:
+      - type: Pods
+        value: 4
+        periodSeconds: 60
+      - type: Percent
+        value: 10
+        periodSeconds: 60
+      selectPolicy: Max
 ----
 <1> Use the `autoscaling/v2beta2` API.
 <2> Specify a name for this horizontal pod autoscaler object.
@@ -109,6 +120,7 @@ spec:
 <9> Specify `memory` for memory utilization.
 <10> Set the type to `AverageValue`.
 <11> Specify `averageValue` and a specific memory value.
+<12> Optional: Specify a scaling policy to control the rate of scaling up or down.
 
 ** To scale for a percentage, create a `HorizontalPodAutoscaler` object similar to the following:
 +
@@ -133,6 +145,17 @@ spec:
       target:
         type: Utilization <10>
         averageUtilization: 50 <11>
+  behavior: <12>
+    scaleUp:
+      stabilizationWindowSeconds: 180
+      policies:
+      - type: Pods
+        value: 6
+        periodSeconds: 120
+      - type: Percent
+        value: 10
+        periodSeconds: 120
+      selectPolicy: Max
 ----
 <1> Use the `autoscaling/v2beta2` API.
 <2> Specify a name for this horizontal pod autoscaler object.
@@ -148,6 +171,7 @@ spec:
 <10> Set to `Utilization`.
 <11> Specify `averageUtilization` and a target average memory utilization over all the Pods, 
 represented as a percent of requested memory. The target pods must have memory requests configured.
+<12> Optional: Specify a scaling policy to control the rate of scaling up or down.
 
 . Create the horizontal pod autoscaler:
 +

modules/nodes-pods-autoscaling-policies.adoc

@@ -0,0 +1,106 @@
+// Module included in the following assemblies:
+//
+// * nodes/nodes-pods-autoscaling.adoc
+
+[id="nodes-pods-autoscaling-policies_{context}"]
+= Scaling policies
+
+The `autoscaling/v2beta2` 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. 
+
+.Sample HPA object with a scaling policy
+[source, yaml]
+----
+apiVersion: autoscaling/v2beta2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: hpa-resource-metrics-memory
+  namespace: default
+spec:
+  behavior:
+    scaleDown: <1>
+      policies: <2>
+      - type: Pods <3>
+        value: 4 <4>
+        periodSeconds: 60 <5>
+      - type: Percent
+        value: 10 <6>
+        periodSeconds: 60
+      selectPolicy: Min <7>
+      stabilizationWindowSeconds: 300 <8>
+    scaleUp: <9>
+      policies:
+      - type: Pods
+        value: 5 <10>
+        periodSeconds: 70
+      - type: Percent
+        value: 12 <11>
+        periodSeconds: 80
+      selectPolicy: Max
+      stabilizationWindowSeconds: 0
+...
+----
+<1> Specifies the direction for the scaling policy, either `scaleDown` or `scaleUp`. This example creates a policy for scaling down.
+<2> Defines the scaling policy. 
+<3> Determines if the policy scales by a specific number of pods or a percentage of pods during each iteration. The default value is `pods`.
+<4> Determines 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`.
+<9> This example creates a policy for scaling up.
+<10> The amount of scaling up by the number of pods. The default value for scaling up the number of pods is 4%.
+<11> The amount of scaling up by the percentage of pods. The default value for scaling up by percentage is 100%.
+
+.Example policy for scaling down
+[source,yaml]
+----
+apiVersion: autoscaling/v2beta2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: hpa-resource-metrics-memory
+  namespace: default
+spec:
+...
+  minReplicas: 20
+...
+  behavior:
+    scaleDown:
+      stabilizationWindowSeconds: 300
+      policies:
+      - type: Pods
+        value: 4
+        periodSeconds: 30
+      - type: Percent
+        value: 10
+        periodSeconds: 60
+      selectPolicy: Max
+    scaleUp:
+      selectPolicy: Disabled
+----
+
+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`).
+
+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.
+
+If set, you can view the scaling policy by using the `oc edit` command:
+
+[source,terminal]
+----
+$ oc edit hpa hpa-resource-metrics-memory
+----
+
+.Example output
+[source,terminal]
+----
+apiVersion: autoscaling/v1
+kind: HorizontalPodAutoscaler
+metadata:
+  annotations:
+    autoscaling.alpha.kubernetes.io/behavior:\
+'{"ScaleUp":{"StabilizationWindowSeconds":0,"SelectPolicy":"Max","Policies":[{"Type":"Pods","Value":4,"PeriodSeconds":15},{"Type":"Percent","Value":100,"PeriodSeconds":15}]},\
+"ScaleDown":{"StabilizationWindowSeconds":300,"SelectPolicy":"Min","Policies":[{"Type":"Pods","Value":4,"PeriodSeconds":60},{"Type":"Percent","Value":10,"PeriodSeconds":60}]}}'
+...
+----
+

nodes/pods/nodes-pods-autoscaling.adoc

@@ -19,6 +19,8 @@ configuration.
 
 include::modules/nodes-pods-autoscaling-about.adoc[leveloffset=+1]
 
+include::modules/nodes-pods-autoscaling-policies.adoc[leveloffset=+2]
+
 include::modules/nodes-pods-autoscaling-creating-cpu.adoc[leveloffset=+1]
 
 include::modules/nodes-pods-autoscaling-creating-memory.adoc[leveloffset=+1]