From 3f1e655a0eb44d6c0c993714c62f2d9e0156ba34 Mon Sep 17 00:00:00 2001 From: Michael Burke Date: Thu, 4 Jun 2026 16:35:03 -0400 Subject: [PATCH] OSDOCS CQA NODES-9: Autoscaling and Miscellaneous III --- modules/nodes-pods-autoscaling-about.adoc | 3 +- ...s-pods-autoscaling-best-practices-hpa.adoc | 3 +- ...pods-autoscaling-creating-cpu-percent.adoc | 22 ++++--- ...ods-autoscaling-creating-cpu-specific.adoc | 51 ++++++++------- .../nodes-pods-autoscaling-creating-cpu.adoc | 5 +- ...s-autoscaling-creating-memory-percent.adoc | 62 ++++++++++--------- ...-autoscaling-creating-memory-specific.adoc | 58 +++++++++-------- ...autoscaling-creating-web-console-edit.adoc | 5 +- ...toscaling-creating-web-console-remove.adoc | 3 +- ...pods-autoscaling-creating-web-console.adoc | 7 ++- modules/nodes-pods-autoscaling-policies.adoc | 54 +++++++++------- ...s-autoscaling-requests-and-limits-hpa.adoc | 7 +-- .../nodes-pods-autoscaling-status-about.adoc | 8 +-- ...nodes-pods-autoscaling-status-viewing.adoc | 17 ++--- .../nodes-pods-autoscaling-workflow-hpa.adoc | 3 +- nodes/pods/nodes-pods-autoscaling.adoc | 23 +++---- 16 files changed, 180 insertions(+), 151 deletions(-) diff --git a/modules/nodes-pods-autoscaling-about.adoc b/modules/nodes-pods-autoscaling-about.adoc index be35016dd6e1..23032d28472f 100644 --- a/modules/nodes-pods-autoscaling-about.adoc +++ b/modules/nodes-pods-autoscaling-about.adoc @@ -6,7 +6,8 @@ [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, and the CPU usage or memory usage your pods should target. +[role="_abstract"] +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. diff --git a/modules/nodes-pods-autoscaling-best-practices-hpa.adoc b/modules/nodes-pods-autoscaling-best-practices-hpa.adoc index 147c5e1cb8af..a74d23bdd9ce 100644 --- a/modules/nodes-pods-autoscaling-best-practices-hpa.adoc +++ b/modules/nodes-pods-autoscaling-best-practices-hpa.adoc @@ -6,7 +6,8 @@ [id="nodes-pods-autoscaling-best-practices-hpa_{context}"] = Best practices -For optimal performance, configure resource requests for all pods. To prevent frequent replica fluctuations, configure the cooldown period. +[role="_abstract"] +You can help ensure optimal performance in your cluster by configuring resource requests for all pods. Additionally, you can prevent frequent replica fluctuations by configuring the cooldown period. 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. diff --git a/modules/nodes-pods-autoscaling-creating-cpu-percent.adoc b/modules/nodes-pods-autoscaling-creating-cpu-percent.adoc index 0bb0c90bc912..9c00440becff 100644 --- a/modules/nodes-pods-autoscaling-creating-cpu-percent.adoc +++ b/modules/nodes-pods-autoscaling-creating-cpu-percent.adoc @@ -6,7 +6,8 @@ [id="nodes-pods-autoscaling-creating-cpu-percent_{context}"] = Creating a horizontal pod autoscaler for a percent of CPU use -Using the {product-title} CLI, you can create a horizontal pod autoscaler (HPA) to automatically scale an existing object based on percent of CPU use. The HPA scales the pods associated with that object to maintain the CPU use that you specify. +[role="_abstract"] +You can use the {product-title} CLI to create a horizontal pod autoscaler (HPA) that automatically scales an existing object based on percent of CPU use. The HPA scales the pods associated with that object to maintain the CPU use that you specify. When autoscaling for a percent of CPU use, you can use the `oc autoscale` command to specify the minimum and maximum number of pods that you want to run at any given time and the average CPU use your pods should target. If you do not specify a minimum, the pods are given default values from the {product-title} server. @@ -25,16 +26,19 @@ include::snippets/nodes-pods-autoscaling-creating-cpu-prereqs.adoc[] + [source,terminal] ---- -$ oc autoscale / \// <1> - --min \// <2> - --max \// <3> - --cpu-percent= <4> +$ oc autoscale / \ + --min \ + --max \ + --cpu-percent= ---- +where: + -<1> Specify the type and name of the object to autoscale. The object must exist and be a `Deployment`, `DeploymentConfig`/`dc`, `ReplicaSet`/`rs`, `ReplicationController`/`rc`, or `StatefulSet`. -<2> Optional: Specify the minimum number of replicas when scaling down. -<3> Specify the maximum number of replicas when scaling up. -<4> Specify the target average CPU use over all the pods, represented as a percent of requested CPU. If not specified or negative, a default autoscaling policy is used. +-- +`/`:: Specifies the type and name of the object to autoscale. The object must exist and be a `Deployment`, `DeploymentConfig`/`dc`, `ReplicaSet`/`rs`, `ReplicationController`/`rc`, or `StatefulSet`. +`min`:: Specifies the minimum number of replicas when scaling down. Replace `` with the minimum number of replicas. This parameter is optional. +`max`:: Specifies the maximum number of replicas when scaling up. Replace `` with the maximum number of replicas. +`cpu-percent`:: Specifies the target average CPU use over all the pods, represented as a percent of requested CPU. Replace `` with requested percentage. If not specified or negative, a default autoscaling policy is used. +-- + For example, the following command 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 will increase to 7: + diff --git a/modules/nodes-pods-autoscaling-creating-cpu-specific.adoc b/modules/nodes-pods-autoscaling-creating-cpu-specific.adoc index 745baef116f2..ab16184c8fb0 100644 --- a/modules/nodes-pods-autoscaling-creating-cpu-specific.adoc +++ b/modules/nodes-pods-autoscaling-creating-cpu-specific.adoc @@ -6,7 +6,8 @@ [id="nodes-pods-autoscaling-creating-cpu-specific_{context}"] = Creating a horizontal pod autoscaler for a specific CPU value -Using the {product-title} CLI, you can create a horizontal pod autoscaler (HPA) to automatically scale an existing object based on a specific CPU value by creating a `HorizontalPodAutoscaler` object with the target CPU and pod limits. The HPA scales the pods associated with that object to maintain the CPU use that you specify. +[role="_abstract"] +You can use the {product-title} CLI to create a horizontal pod autoscaler (HPA) that automatically scales an existing object based on a specific CPU value by creating a `HorizontalPodAutoscaler` object with the target CPU and pod limits. The HPA scales the pods associated with that object to maintain the CPU use that you specify. [NOTE] ==== @@ -23,40 +24,44 @@ include::snippets/nodes-pods-autoscaling-creating-cpu-prereqs.adoc[] + [source,yaml,options="nowrap"] ---- -apiVersion: autoscaling/v2 <1> +apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: - name: cpu-autoscale <2> + name: cpu-autoscale namespace: default spec: scaleTargetRef: - apiVersion: apps/v1 <3> - kind: Deployment <4> - name: example <5> - minReplicas: 1 <6> - maxReplicas: 10 <7> - metrics: <8> + apiVersion: apps/v1 + kind: Deployment + name: example + minReplicas: 1 + maxReplicas: 10 + metrics: - type: Resource resource: - name: cpu <9> + name: cpu target: - type: AverageValue <10> - averageValue: 500m <11> + type: AverageValue + averageValue: 500m ---- -<1> Use the `autoscaling/v2` API. -<2> Specify a name for this horizontal pod autoscaler object. -<3> Specify the API version of the object to scale: +where: ++ +-- +`apiVersion`:: Specifies the `autoscaling/v2` API. +`metadata.name`:: Specifies a name for this horizontal pod autoscaler object. +`spec.scaleTargetRef.apiVersion`:: Specifies the API version of the object to scale: * For a `Deployment`, `ReplicaSet`, `Statefulset` object, use `apps/v1`. * For a `ReplicationController`, use `v1`. * For a `DeploymentConfig`, use `apps.openshift.io/v1`. -<4> Specify the type of object. The object must be a `Deployment`, `DeploymentConfig`/`dc`, `ReplicaSet`/`rs`, `ReplicationController`/`rc`, or `StatefulSet`. -<5> Specify the name of the object to scale. The object must exist. -<6> Specify the minimum number of replicas when scaling down. -<7> Specify the maximum number of replicas when scaling up. -<8> Use the `metrics` parameter for memory use. -<9> Specify `cpu` for CPU usage. -<10> Set to `AverageValue`. -<11> Set to `averageValue` with the targeted CPU value. +`spec.scaleTargetRef.kind`:: Specifies the type of object. The object must be a `Deployment`, `DeploymentConfig`/`dc`, `ReplicaSet`/`rs`, `ReplicationController`/`rc`, or `StatefulSet`. +`spec.scaleTargetRef.name`:: Specifies the name of the object to scale. The object must exist. +`spec.minReplicas`:: Specifies the minimum number of replicas when scaling down. +`spec.maxReplicas`:: Specifies the maximum number of replicas when scaling up. +`spec.metrics`:: Specifies the parameters to calculate the desired replica count. +`spec.metrics.resource.name`:: Specifies a name for the resource. +`spec.metrics.resource.target.type`:: Specifies the type of target, here `AverageValue` for a specific CPU value. +`spec.metrics.resource.target.averageValue`:: Specifies the targeted CPU value. +-- . Create the horizontal pod autoscaler: + diff --git a/modules/nodes-pods-autoscaling-creating-cpu.adoc b/modules/nodes-pods-autoscaling-creating-cpu.adoc index ede04941e7cd..7e03661fe50a 100644 --- a/modules/nodes-pods-autoscaling-creating-cpu.adoc +++ b/modules/nodes-pods-autoscaling-creating-cpu.adoc @@ -2,11 +2,12 @@ // // * nodes/nodes-pods-autoscaling.adoc -:_mod-docs-content-type: PROCEDURE +:_mod-docs-content-type: CONCEPT [id="nodes-pods-autoscaling-creating-cpu_{context}"] = Creating a horizontal pod autoscaler by using the CLI -Using the {product-title} CLI, you can create a horizontal pod autoscaler (HPA) to automatically scale an existing `Deployment`, `DeploymentConfig`, `ReplicaSet`, `ReplicationController`, or `StatefulSet` object. The HPA scales the pods associated with that object to maintain the CPU or memory resources that you specify. +[role="_abstract"] +By using the {product-title} CLI, you can create a horizontal pod autoscaler (HPA) to automatically scale an existing `Deployment`, `DeploymentConfig`, `ReplicaSet`, `ReplicationController`, or `StatefulSet` object. The HPA scales the pods associated with that object to maintain the CPU or memory resources that you specify. You can autoscale based on CPU or memory use by specifying a percentage of resource usage or a specific value, as described in the following sections. diff --git a/modules/nodes-pods-autoscaling-creating-memory-percent.adoc b/modules/nodes-pods-autoscaling-creating-memory-percent.adoc index 2b4163bf804b..3e8c05a95a18 100644 --- a/modules/nodes-pods-autoscaling-creating-memory-percent.adoc +++ b/modules/nodes-pods-autoscaling-creating-memory-percent.adoc @@ -7,7 +7,8 @@ = Creating a horizontal pod autoscaler object for a percent of memory use -Using the {product-title} CLI, you can create a horizontal pod autoscaler (HPA) to automatically scale an existing object based on a percent of memory use. The HPA scales the pods associated with that object to maintain the memory use that you specify. +[role="_abstract"] +You can use the {product-title} CLI to create a horizontal pod autoscaler (HPA) that automatically scales an existing object based on a percent of memory use. The HPA scales the pods associated with that object to maintain the memory use that you specify. [NOTE] ==== @@ -26,26 +27,26 @@ include::snippets/nodes-pods-autoscaling-creating-cpu-prereqs.adoc[] + [source,yaml,options="nowrap"] ---- -apiVersion: autoscaling/v2 <1> +apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: - name: memory-autoscale <2> + name: memory-autoscale namespace: default spec: scaleTargetRef: - apiVersion: apps/v1 <3> - kind: Deployment <4> - name: example <5> - minReplicas: 1 <6> - maxReplicas: 10 <7> - metrics: <8> + apiVersion: apps/v1 + kind: Deployment + name: example + minReplicas: 1 + maxReplicas: 10 + metrics: - type: Resource resource: - name: memory <9> + name: memory target: - type: Utilization <10> - averageUtilization: 50 <11> - behavior: <12> + type: Utilization + averageUtilization: 50 + behavior: scaleUp: stabilizationWindowSeconds: 180 policies: @@ -57,23 +58,26 @@ spec: periodSeconds: 120 selectPolicy: Max ---- -<1> Use the `autoscaling/v2` API. -<2> Specify a name for this horizontal pod autoscaler object. -<3> Specify the API version of the object to scale: -* For a ReplicationController, use `v1`. -* For a DeploymentConfig, use `apps.openshift.io/v1`. -* For a Deployment, ReplicaSet, Statefulset object, use `apps/v1`. -<4> Specify the type of object. The object must be a `Deployment`, `DeploymentConfig`, -`ReplicaSet`, `ReplicationController`, or `StatefulSet`. -<5> Specify the name of the object to scale. The object must exist. -<6> Specify the minimum number of replicas when scaling down. -<7> Specify the maximum number of replicas when scaling up. -<8> Use the `metrics` parameter for memory usage. -<9> Specify `memory` for memory usage. -<10> Set to `Utilization`. -<11> Specify `averageUtilization` and a target average memory usage over all the pods, +where: ++ +-- +`apiVersion`:: Specifies the `autoscaling/v2` API. +`metadata.name`:: Specifies a name for this horizontal pod autoscaler object. +`spec.scaleTargetRef.apiVersion`:: Specifies the API version of the object to scale: +* For a `Deployment`, `ReplicaSet`, `Statefulset` object, use `apps/v1`. +* For a `ReplicationController`, use `v1`. +* For a `DeploymentConfig`, use `apps.openshift.io/v1`. +`spec.scaleTargetRef.kind`:: Specifies the type of object. The object must be a `Deployment`, `DeploymentConfig`/`dc`, `ReplicaSet`/`rs`, `ReplicationController`/`rc`, or `StatefulSet`. +`spec.scaleTargetRef.name`:: Specifies the name of the object to scale. The object must exist. +`spec.minReplicas`:: Specifies the minimum number of replicas when scaling down. +`spec.maxReplicas`:: Specifies the maximum number of replicas when scaling up. +`spec.metrics`:: Specifies the parameters to calculate the desired replica count. +`spec.metrics.resource.name`:: Specifies a name for the resource. +`spec.metrics.resource.target.type`:: Specifies the type of target, here `Utilization` for a percentage value. +`spec.metrics.resource.target.averageUtilization`:: Specifies the targeted average memory usage 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. +`spec.behavior`:: Optional: Specifies a scaling policy to control the rate of scaling up or down. +-- . Create the horizontal pod autoscaler by using a command similar to the following: + diff --git a/modules/nodes-pods-autoscaling-creating-memory-specific.adoc b/modules/nodes-pods-autoscaling-creating-memory-specific.adoc index 4c63910b7d3b..8d51a4b14984 100644 --- a/modules/nodes-pods-autoscaling-creating-memory-specific.adoc +++ b/modules/nodes-pods-autoscaling-creating-memory-specific.adoc @@ -7,7 +7,8 @@ = Creating a horizontal pod autoscaler object for specific memory use -Using the {product-title} CLI, you can create a horizontal pod autoscaler (HPA) to automatically scale an existing object. The HPA scales the pods associated with that object to maintain the average memory use that you specify. +[role="_abstract"] +You can use the {product-title} CLI to create a horizontal pod autoscaler (HPA) that automatically scales an existing object. The HPA scales the pods associated with that object to maintain the average memory use that you specify. [NOTE] ==== @@ -26,26 +27,26 @@ include::snippets/nodes-pods-autoscaling-creating-cpu-prereqs.adoc[] + [source,yaml,options="nowrap"] ---- -apiVersion: autoscaling/v2 <1> +apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: - name: hpa-resource-metrics-memory <2> + name: hpa-resource-metrics-memory namespace: default spec: scaleTargetRef: - apiVersion: apps/v1 <3> - kind: Deployment <4> - name: example <5> - minReplicas: 1 <6> - maxReplicas: 10 <7> - metrics: <8> + apiVersion: apps/v1 + kind: Deployment + name: example + minReplicas: 1 + maxReplicas: 10 + metrics: - type: Resource resource: - name: memory <9> + name: memory target: - type: AverageValue <10> - averageValue: 500Mi <11> - behavior: <12> + type: AverageValue + averageValue: 500Mi + behavior: scaleDown: stabilizationWindowSeconds: 300 policies: @@ -57,22 +58,25 @@ spec: periodSeconds: 60 selectPolicy: Max ---- -<1> Use the `autoscaling/v2` API. -<2> Specify a name for this horizontal pod autoscaler object. -<3> Specify the API version of the object to scale: -* For a `Deployment`, `ReplicaSet`, or `Statefulset` object, use `apps/v1`. +where: ++ +-- +`apiVersion`:: Specifies the `autoscaling/v2` API. +`metadata.name`:: Specifies a name for this horizontal pod autoscaler object. +`spec.scaleTargetRef.apiVersion`:: Specifies the API version of the object to scale: +* For a `Deployment`, `ReplicaSet`, `Statefulset` object, use `apps/v1`. * For a `ReplicationController`, use `v1`. * For a `DeploymentConfig`, use `apps.openshift.io/v1`. -<4> Specify the type of object. The object must be a `Deployment`, `DeploymentConfig`, -`ReplicaSet`, `ReplicationController`, or `StatefulSet`. -<5> Specify the name of the object to scale. The object must exist. -<6> Specify the minimum number of replicas when scaling down. -<7> Specify the maximum number of replicas when scaling up. -<8> Use the `metrics` parameter for memory usage. -<9> Specify `memory` for memory usage. -<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. +`spec.scaleTargetRef.kind`:: Specifies the type of object. The object must be a `Deployment`, `DeploymentConfig`/`dc`, `ReplicaSet`/`rs`, `ReplicationController`/`rc`, or `StatefulSet`. +`spec.scaleTargetRef.name`:: Specifies the name of the object to scale. The object must exist. +`spec.minReplicas`:: Specifies the minimum number of replicas when scaling down. +`spec.maxReplicas`:: Specifies the maximum number of replicas when scaling up. +`spec.metrics`:: Specifies the parameters to calculate the desired replica count. Set the +`spec.metrics.resource.name`:: Specifies a name for the resource. +`spec.metrics.resource.target.type`:: Specifies the type of target, here `AverageValue` for a specific memory value. +`spec.metrics.resource.target.averageValue`:: Specifies the targeted memory value. +`spec.behavior`:: Optional: Specifies a scaling policy to control the rate of scaling up or down. +-- . Create the horizontal pod autoscaler by using a command similar to the following: + diff --git a/modules/nodes-pods-autoscaling-creating-web-console-edit.adoc b/modules/nodes-pods-autoscaling-creating-web-console-edit.adoc index 0369ced9ea4a..3443e16122ad 100644 --- a/modules/nodes-pods-autoscaling-creating-web-console-edit.adoc +++ b/modules/nodes-pods-autoscaling-creating-web-console-edit.adoc @@ -6,7 +6,8 @@ [id="nodes-pods-autoscaling-creating-web-console-edit_{context}"] = Editing a horizontal pod autoscaler by using the web console -From the web console, you can modify a horizontal pod autoscaler (HPA) that specifies the minimum and maximum number of pods you want to run on a `Deployment` or `DeploymentConfig` object. You can also define the amount of CPU or memory usage that your pods should target. +[role="_abstract"] +You can use the web console to modify a horizontal pod autoscaler (HPA) that specifies the minimum and maximum number of pods you want to run on a `Deployment` or `DeploymentConfig` object. You can also define the amount of CPU or memory usage that your pods should target. .Procedure @@ -15,7 +16,7 @@ From the web console, you can modify a horizontal pod autoscaler (HPA) that spec . From the *Actions* drop-down list, select *Edit HorizontalPodAutoscaler* to open the *Edit Horizontal Pod Autoscaler* form. . From the *Edit Horizontal Pod Autoscaler* form, edit the minimum and maximum pod limits and the CPU and memory usage, and click *Save*. - ++ [NOTE] ==== While creating or editing the horizontal pod autoscaler in the web console, you can switch from *Form view* to *YAML view*. diff --git a/modules/nodes-pods-autoscaling-creating-web-console-remove.adoc b/modules/nodes-pods-autoscaling-creating-web-console-remove.adoc index 1378f0ac80e2..e96673ce5cfb 100644 --- a/modules/nodes-pods-autoscaling-creating-web-console-remove.adoc +++ b/modules/nodes-pods-autoscaling-creating-web-console-remove.adoc @@ -6,7 +6,8 @@ [id="nodes-pods-autoscaling-creating-web-console-remove_{context}"] = Removing a horizontal pod autoscaler by using the web console -You can remove a horizontal pod autoscaler (HPA) in the web console. +[role="_abstract"] +You can use the web console to remove a horizontal pod autoscaler (HPA). .Procedure diff --git a/modules/nodes-pods-autoscaling-creating-web-console.adoc b/modules/nodes-pods-autoscaling-creating-web-console.adoc index 6a0cb38216f7..671ba63c22b0 100644 --- a/modules/nodes-pods-autoscaling-creating-web-console.adoc +++ b/modules/nodes-pods-autoscaling-creating-web-console.adoc @@ -6,16 +6,17 @@ [id="nodes-pods-autoscaling-creating-web-console_{context}"] = Creating a horizontal pod autoscaler by using the web console -From the web console, you can create a horizontal pod autoscaler (HPA) that specifies the minimum and maximum number of pods you want to run on a `Deployment` or `DeploymentConfig` object. You can also define the amount of CPU or memory usage that your pods should target. +[role="_abstract"] +You can use the web console to create a horizontal pod autoscaler (HPA) that specifies the minimum and maximum number of pods you want to run on a `Deployment` or `DeploymentConfig` object. You can also define the amount of CPU or memory usage that your pods should target. [NOTE] ==== An HPA cannot be added to deployments that are part of an Operator-backed service, Knative service, or Helm chart. ==== -.Procedure +The following procedure creates an HPA in the web console. -To create an HPA in the web console: +.Procedure . In the *Topology* view, click the node to reveal the side pane. diff --git a/modules/nodes-pods-autoscaling-policies.adoc b/modules/nodes-pods-autoscaling-policies.adoc index 11b72b182541..148a5fe5437e 100644 --- a/modules/nodes-pods-autoscaling-policies.adoc +++ b/modules/nodes-pods-autoscaling-policies.adoc @@ -6,7 +6,12 @@ [id="nodes-pods-autoscaling-policies_{context}"] = Scaling policies -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. +[role="_abstract"] +To control how the {product-title} horizontal pod autoscaler (HPA) scales pods you can define a _scaling policy_ to restrict the rate at which scaling occurs and a _stabilization window_ to restrict the fluctuation of replicas count when the metrics used for scaling keep fluctuating. + +A scaling policy restricts 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. 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. + +Use the `autoscaling/v2` API to add _scaling policies_ to a horizontal pod autoscaler. .Sample HPA object with a scaling policy [source, yaml] @@ -18,39 +23,42 @@ metadata: namespace: default spec: behavior: - scaleDown: <1> - policies: <2> - - type: Pods <3> - value: 4 <4> - periodSeconds: 60 <5> + scaleDown: + policies: + - type: Pods + value: 4 + periodSeconds: 60 - type: Percent - value: 10 <6> + value: 10 periodSeconds: 60 - selectPolicy: Min <7> - stabilizationWindowSeconds: 300 <8> - scaleUp: <9> + selectPolicy: Min + stabilizationWindowSeconds: 300 + scaleUp: policies: - type: Pods - value: 5 <10> + value: 5 periodSeconds: 70 - type: Percent - value: 12 <11> + value: 12 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> 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 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%. +where: + +`spec.behavior.scaleDown`:: Specifies a policy for scaling down. +`spec.behavior.scaleDown.policies`:: Specifies the parameters for the scaling policy. Set the following values: +* `type`. Specifies whether the policy scales by a specific number of pods or a percentage of pods during each iteration. The default value is `pods`. +* `value`. Specifies the amount of scaling, either the number of pods or percentage of pods, during each iteration. The default value for scaling down by percentage is 100%. There is no default value for scaling down by number of pods. +* `periodSeconds`. Specifies the length of a scaling iteration. The default value is `15` seconds. +`spec.behavior.scaleDown.selectPolicy`:: Specifies 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`. +`spec.behavior.scaleDown.stabilizationWindowSeconds`:: Specifies the time period the HPA reviews the required states. The default value is `0`. +`spec.behavior.scaleUp`:: Specifies a policy for scaling up. +`spec.behavior.scaleUp.policies`:: Specifies the parameters for the scaling policy. Set the following values: +* `type`. Specifies whether the policy scales by a specific number of pods or a percentage of pods during each iteration. +* `value`. Specifies the amount of scaling, either the number of pods or percentage of pods, during each iteration. The default value for scaling up by percentage is 100%. The default value for scaling up the number of pods is 4%. +* `periodSeconds`. Specifies the length of a scaling iteration. .Example policy for scaling down [source,yaml] diff --git a/modules/nodes-pods-autoscaling-requests-and-limits-hpa.adoc b/modules/nodes-pods-autoscaling-requests-and-limits-hpa.adoc index 6d3779a13a14..0438d3843105 100644 --- a/modules/nodes-pods-autoscaling-requests-and-limits-hpa.adoc +++ b/modules/nodes-pods-autoscaling-requests-and-limits-hpa.adoc @@ -6,13 +6,12 @@ [id="nodes-pods-autoscaling-requests-and-limits-hpa_{context}"] = About requests and limits +[role="_abstract"] +To use resource metrics, you must specify the resource requests, such as CPU and memory, in a pod specification. The HPA uses this specification to determine the resource utilization and then scales the target up or down. + The scheduler uses the resource request that you specify for containers in a pod, to decide which node to place the pod on. The kubelet enforces the resource limit that you specify for a container to ensure that the container is not allowed to use more than the specified limit. The kubelet also reserves the request amount of that system resource specifically for that container to use. -.How to use resource metrics? - -In the pod specifications, you must specify the resource requests, such as CPU and memory. The HPA uses this specification to determine the resource utilization and then scales the target up or down. - For example, the HPA object uses the following metric source: [source,yaml] diff --git a/modules/nodes-pods-autoscaling-status-about.adoc b/modules/nodes-pods-autoscaling-status-about.adoc index 0aeac5621243..efc159543167 100644 --- a/modules/nodes-pods-autoscaling-status-about.adoc +++ b/modules/nodes-pods-autoscaling-status-about.adoc @@ -7,9 +7,8 @@ = Understanding horizontal pod autoscaler status conditions by using the CLI -You can use the status conditions set to determine -whether or not the horizontal pod autoscaler (HPA) is able to scale and whether or not it is currently restricted -in any way. +[role="_abstract"] +You can review the horizontal pod autoscaler (HPA) status conditions set to determine if the HPA is able to scale or if it is currently restricted in any way. The HPA status conditions are available with the `v2` version of the autoscaling API. @@ -55,7 +54,8 @@ Conditions: <1> ScalingLimited False DesiredWithinRange the desired replica count is within the acceptable range Events: ---- -<1> The horizontal pod autoscaler status messages. ++ +The horizontal pod autoscaler status messages appear in the `Conditions` stanza. // The above output and bullets from https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#appendix-horizontal-pod-autoscaler-status-conditions diff --git a/modules/nodes-pods-autoscaling-status-viewing.adoc b/modules/nodes-pods-autoscaling-status-viewing.adoc index b8b7c1eda146..253ffb8658b1 100644 --- a/modules/nodes-pods-autoscaling-status-viewing.adoc +++ b/modules/nodes-pods-autoscaling-status-viewing.adoc @@ -7,6 +7,7 @@ = Viewing horizontal pod autoscaler status conditions by using the CLI +[role="_abstract"] You can view the status conditions set on a pod by the horizontal pod autoscaler (HPA). [NOTE] @@ -25,7 +26,8 @@ configured, the output appears similar to the following, with `Cpu` and `Memory` $ oc describe PodMetrics openshift-kube-scheduler-ip-10-0-135-131.ec2.internal ---- -.Example output +The output appears similar to the following example: + [source,terminal] ---- Name: openshift-kube-scheduler-ip-10-0-135-131.ec2.internal @@ -52,23 +54,22 @@ Events: .Procedure -To view the status conditions on a pod, use the following command with the name of the pod: - +* To view the status conditions on a pod, use the following command with the name of the pod: ++ [source,terminal] ---- $ oc describe hpa ---- - ++ For example: - ++ [source,terminal] ---- $ oc describe hpa cm-test ---- - ++ The conditions appear in the `Conditions` field in the output. - -.Example output ++ [source,terminal] ---- Name: cm-test diff --git a/modules/nodes-pods-autoscaling-workflow-hpa.adoc b/modules/nodes-pods-autoscaling-workflow-hpa.adoc index 0e9159c4f67e..030d0ef3cd68 100644 --- a/modules/nodes-pods-autoscaling-workflow-hpa.adoc +++ b/modules/nodes-pods-autoscaling-workflow-hpa.adoc @@ -6,7 +6,8 @@ [id="nodes-pods-autoscaling-workflow-hpa_{context}"] = How does the HPA work? -The horizontal pod autoscaler (HPA) extends the concept of pod auto-scaling. The HPA lets you create and manage a group of load-balanced nodes. The HPA automatically increases or decreases the number of pods when a given CPU or memory threshold is crossed. +[role="_abstract"] +By using the horizontal pod autoscaler (HPA) you can create and manage a group of load-balanced nodes. The HPA automatically increases or decreases the number of pods when a given CPU or memory threshold is crossed. .High level workflow of the HPA image::HPAflow.png[workflow] diff --git a/nodes/pods/nodes-pods-autoscaling.adoc b/nodes/pods/nodes-pods-autoscaling.adoc index 84d4c66a74d8..674b2c588a52 100644 --- a/nodes/pods/nodes-pods-autoscaling.adoc +++ b/nodes/pods/nodes-pods-autoscaling.adoc @@ -6,19 +6,17 @@ include::_attributes/common-attributes.adoc[] toc::[] -As a developer, you can use a horizontal pod autoscaler (HPA) to -specify how {product-title} should automatically increase or decrease the scale of -a replication controller or deployment configuration, based on metrics collected -from the pods that belong to that replication controller or deployment -configuration. You can create an HPA for any deployment, deployment config, replica set, replication controller, or stateful set. +[role="_abstract"] +As a developer, you can use a horizontal pod autoscaler (HPA) to specify how {product-title} should automatically increase or decrease the scale of a replication controller or deployment configuration, based on metrics collected from the pods that belong to that replication controller or deployment configuration. -For information on scaling pods based on custom metrics, see xref:../../nodes/cma/nodes-cma-autoscaling-custom.adoc#nodes-cma-autoscaling-custom[Automatically scaling pods based on custom metrics]. +You can create an HPA for any deployment, deployment config, replica set, replication controller, or stateful set. +For information on scaling pods based on custom metrics, see "Automatically scaling pods based on custom metrics". [NOTE] ==== It is recommended to use a `Deployment` object or `ReplicaSet` object unless you need a specific feature or behavior provided by other objects. For more information on -these objects, see xref:../../applications/deployments/what-deployments-are.adoc#what-deployments-are[Understanding deployments]. +these objects, see "Understanding deployments". ==== // The following include statements pull in the module files that comprise @@ -34,11 +32,6 @@ include::modules/nodes-pods-autoscaling-requests-and-limits-hpa.adoc[leveloffset include::modules/nodes-pods-autoscaling-best-practices-hpa.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources -* xref:../../nodes/pods/nodes-pods-using.adoc#nodes-pods-understanding-requests-limits_nodes-pods-using-ssy[Understanding resource requests and limits] -* xref:../../nodes/pods/nodes-pods-autoscaling.adoc#nodes-pods-autoscaling-policies_nodes-pods-autoscaling[Scaling policies] - include::modules/nodes-pods-autoscaling-policies.adoc[leveloffset=+2] include::modules/nodes-pods-autoscaling-creating-web-console.adoc[leveloffset=+1] @@ -63,8 +56,12 @@ include::modules/nodes-pods-autoscaling-status-about.adoc[leveloffset=+1] include::modules/nodes-pods-autoscaling-status-viewing.adoc[leveloffset=+2] - [role="_additional-resources"] +[id="additional-resources_{context}"] == Additional resources +* xref:../../nodes/cma/nodes-cma-autoscaling-custom.adoc#nodes-cma-autoscaling-custom[Automatically scaling pods based on custom metrics] +* xref:../../applications/deployments/what-deployments-are.adoc#what-deployments-are[Understanding deployments] +* xref:../../nodes/pods/nodes-pods-using.adoc#nodes-pods-understanding-requests-limits_nodes-pods-using-ssy[Understanding resource requests and limits] +* xref:../../nodes/pods/nodes-pods-autoscaling.adoc#nodes-pods-autoscaling-policies_nodes-pods-autoscaling[Scaling policies] * xref:../../applications/deployments/what-deployments-are.adoc#what-deployments-are[Understanding deployments and deployment configs] * link:https://cloud.redhat.com/blog/horizontal-pod-autoscaling-of-quarkus-application-based-on-memory-utilization[Horizontal Pod Autoscaling of Quarkus Application Based on Memory Utilization]