From a78bff64564098e9c91ac60c91caa083fda72a01 Mon Sep 17 00:00:00 2001 From: light0011 Date: Thu, 27 Nov 2025 15:55:55 +0800 Subject: [PATCH 1/3] Add AverageValue example for HPA resource metrics - Added example showing how to use AverageValue target type - Clarified that AverageValue scales based on actual consumption - Addresses issue #53447 --- .../horizontal-pod-autoscale.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md b/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md index 5cd558a3d7d11..9bff88a5b8ee7 100644 --- a/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md +++ b/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md @@ -149,6 +149,31 @@ When a `targetAverageValue` or `targetAverageUtilization` is specified, the `currentMetricValue` is computed by taking the average of the given metric across all Pods in the HorizontalPodAutoscaler's scale target. +**Example: Scaling based on raw resource values** + +You can configure the HPA to scale based on actual resource consumption without depending +on resource requests: +```yaml +type: Resource +resource: + name: cpu + target: + type: AverageValue + averageValue: 100m +--- +type: Resource +resource: + name: memory + target: + type: AverageValue + averageValue: 512Mi +``` + +With `AverageValue`, the HPA scales based on the actual measured resource consumption per +pod, independent of any resource requests configured in the pod specification. For instance, +if the average CPU usage across all pods is 200m and the target averageValue is 100m, the +HPA will scale up according to the ratio (200m / 100m = 2.0). + Before checking the tolerance and deciding on the final values, the control plane also considers whether any metrics are missing, and how many Pods are [`Ready`](/docs/concepts/workloads/pods/pod-lifecycle/#pod-conditions). From a024d2b3e07aabab9430e643aa497009dae5d5e4 Mon Sep 17 00:00:00 2001 From: light0011 Date: Mon, 1 Dec 2025 17:13:22 +0800 Subject: [PATCH 2/3] Move AverageValue example to walkthrough doc Per review feedback from @omerap12, moved the example to the walkthrough document in the 'Autoscaling on multiple metrics' section where AverageValue is first explained. - Added practical example showing CPU scaling with AverageValue - Clarified use cases for absolute value scaling - Provided context on when to use this approach vs Utilization Closes: #53447 --- .../horizontal-pod-autoscale-walkthrough.md | 24 ++++++++++++++++++ .../horizontal-pod-autoscale.md | 25 ------------------- 2 files changed, 24 insertions(+), 25 deletions(-) diff --git a/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md b/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md index c2bb630721a97..e25de77e1d3f9 100644 --- a/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md +++ b/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md @@ -280,6 +280,30 @@ setting the corresponding `target.averageValue` field instead of the `target.ave averageValue: 500Mi ``` +For example, you can configure the HPA to scale based on CPU consumption using absolute values: +```yaml +metrics: +- type: Resource + resource: + name: cpu + target: + type: AverageValue + averageValue: 100m +``` + +With this configuration, the HPA scales based on the actual measured CPU consumption per pod +(in millicores), independent of any resource requests configured in the pod specification. +If the average CPU usage across all pods is 200m and the target `averageValue` is 100m, +the HPA will scale up according to the ratio (200m / 100m = 2.0). + +This approach is particularly useful when: +- Resource requests are not defined in the pod specification +- You want to scale based on specific absolute resource thresholds rather than percentages +- You need consistent scaling behavior regardless of how resource requests are configured + +There are two other types of metrics, both of which are considered *custom metrics*: pod metrics and +object metrics... + There are two other types of metrics, both of which are considered *custom metrics*: pod metrics and object metrics. These metrics may have names which are cluster specific, and require a more advanced cluster monitoring setup. diff --git a/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md b/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md index 9bff88a5b8ee7..5cd558a3d7d11 100644 --- a/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md +++ b/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md @@ -149,31 +149,6 @@ When a `targetAverageValue` or `targetAverageUtilization` is specified, the `currentMetricValue` is computed by taking the average of the given metric across all Pods in the HorizontalPodAutoscaler's scale target. -**Example: Scaling based on raw resource values** - -You can configure the HPA to scale based on actual resource consumption without depending -on resource requests: -```yaml -type: Resource -resource: - name: cpu - target: - type: AverageValue - averageValue: 100m ---- -type: Resource -resource: - name: memory - target: - type: AverageValue - averageValue: 512Mi -``` - -With `AverageValue`, the HPA scales based on the actual measured resource consumption per -pod, independent of any resource requests configured in the pod specification. For instance, -if the average CPU usage across all pods is 200m and the target averageValue is 100m, the -HPA will scale up according to the ratio (200m / 100m = 2.0). - Before checking the tolerance and deciding on the final values, the control plane also considers whether any metrics are missing, and how many Pods are [`Ready`](/docs/concepts/workloads/pods/pod-lifecycle/#pod-conditions). From 6cc67300744f7426fa68a1a945e934aa55e4a568 Mon Sep 17 00:00:00 2001 From: light0011 Date: Mon, 1 Dec 2025 17:14:11 +0800 Subject: [PATCH 3/3] Move AverageValue example to walkthrough doc Per review feedback from @omerap12, moved the example to the walkthrough document in the 'Autoscaling on multiple metrics' section where AverageValue is first explained. - Added practical example showing CPU scaling with AverageValue - Clarified use cases for absolute value scaling - Provided context on when to use this approach vs Utilization Closes: #53447 --- .../run-application/horizontal-pod-autoscale-walkthrough.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md b/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md index e25de77e1d3f9..9605a3ea89b1d 100644 --- a/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md +++ b/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md @@ -301,9 +301,6 @@ This approach is particularly useful when: - You want to scale based on specific absolute resource thresholds rather than percentages - You need consistent scaling behavior regardless of how resource requests are configured -There are two other types of metrics, both of which are considered *custom metrics*: pod metrics and -object metrics... - There are two other types of metrics, both of which are considered *custom metrics*: pod metrics and object metrics. These metrics may have names which are cluster specific, and require a more advanced cluster monitoring setup.