Using Horizontal Pod Autoscaling (HPA)

Before you begin

To use HPA effectively, we recommend reading the official Kubernetes documentation on Horizontal Pod Autoscaling to understand its fundamental principles, algorithms, and configurable scaling behaviors.

Additionally, Alibaba Cloud Container Service for Kubernetes (ACK) clusters offer various workload scaling (scheduling layer elasticity) and node scaling (resource layer elasticity) solutions. Before you proceed, read Auto scaling to understand the use cases and limitations of each solution.

Prerequisites

• You have created an ACK managed cluster or an ACK dedicated cluster. For more information, see Create a Kubernetes cluster.

• If you use kubectl commands to implement HPA, you must connect to the Kubernetes cluster with kubectl. For more information, see Obtain the KubeConfig of a cluster and use kubectl to connect to the cluster.

Create an HPA application in the console

ACK is integrated with HPA, allowing you to create HPA-enabled applications from the console. You can enable HPA when you create a new application or for an existing one. We recommend creating only one HPA per workload.

Create an HPA application by using kubectl

You can also use an orchestration template to manually create an HPA and bind it to the target Deployment. We recommend creating only one HPA per workload. This example shows how to deploy an Nginx application that supports HPA.

1. Create a file named nginx.yml and copy the following content into it.

   Important

   To implement HPA, you must set request resources for the Pod. Otherwise, HPA cannot run. You can use the resource profiling feature to analyze historical resource usage data and obtain recommendations for configuring container Requests and Limits. For more information, see Resource profiling.

   YAML template

   apiVersion: apps/v1 
   kind: Deployment
   metadata:
     name: nginx
     labels:
       app: nginx
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: nginx  
     template:
       metadata:
         labels:
           app: nginx
       spec:
         containers:
         - name: nginx
           image: nginx:1.7.9 # Replace with your actual <image_name:tags>.
           ports:
           - containerPort: 80
           resources:
             requests:         # You must set requests. Otherwise, HPA cannot calculate metrics, and the status will be 'unknown'.
               cpu: 500m

2. Run the following command to create the Nginx application.

   kubectl apply -f nginx.yml

3. Create a file named hpa.yml and copy the following content into it to create the HPA.

   Use scaleTargetRef to specify the target object for the HPA. In this example, the HPA is bound to a Deployment named nginx and triggers a scaling operation when the average CPU utilization of the containers in all Pods reaches 50%.

   Kubernetes 1.24 and later

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     name: nginx-hpa
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: nginx
     minReplicas: 1  # The minimum number of replicas for the Deployment. Must be an integer greater than or equal to 1.
     maxReplicas: 10  # The maximum number of replicas for the Deployment. Must be greater than minReplicas.
     metrics:
     - type: Resource
       resource:
         name: cpu
         target:
           type: Utilization
           averageUtilization: 50 # The target average resource utilization, which is the ratio of average resource usage to the requested resource amount.
                  

   Kubernetes before 1.24

   apiVersion: autoscaling/v2beta2
   kind: HorizontalPodAutoscaler
   metadata:
     name: nginx-hpa
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: nginx
     minReplicas: 1  # Must be an integer greater than or equal to 1.
     maxReplicas: 10  # Must be greater than the minimum number of replicas.
     metrics:
     - type: Resource
       resource:
         name: cpu
         target:
           type: Utilization
           averageUtilization: 50
                  

   If you need to specify both CPU and memory metrics, you can specify both cpu and memory resource types in the metrics field instead of creating two HPAs. When the HPA detects that any of the metrics reaches the scaling threshold, it will perform a scaling operation.

   metrics:
     - type: Resource
       resource:
         name: cpu
         target:
           type: Utilization
           averageUtilization: 50
     - type: Resource
       resource:
         name: memory
         target:
           type: Utilization
           averageUtilization: 50

4. Run the following command to create the HPA.

   kubectl apply -f hpa.yml

   At this point, run the kubectl describe hpa <HPA name> command. In this example, the HPA name is nginx-hpa. The expected output is the following warning message, which indicates that the HPA is still being deployed. You can run the kubectl get hpa command to check the status of the HPA.

   Warning  FailedGetResourceMetric       2m (x6 over 4m)  horizontal-pod-autoscaler  missing request for cpu on container nginx in pod default/nginx-deployment-basic-75675f5897-mqzs7
   
   Warning  FailedComputeMetricsReplicas  2m (x6 over 4m)  horizontal-pod-autoscaler  failed to get cpu utilization: missing request for cpu on container nginx in pod default/nginx-deployment-basic-75675f5

5. After the HPA is created and the Pod meets the scaling conditions (in this example, the CPU utilization of the Nginx Pod exceeds 50%), run the kubectl describe hpa <HPA-name> command again to view the horizontal scaling status.

   The following output indicates that the HPA is running correctly.

   Type    Reason             Age   From                       Message
     ----    ------             ----  ----                       -------
     Normal  SuccessfulRescale  5m6s  horizontal-pod-autoscaler  New size: 1; reason: All metrics below target

Related operations

If the default scaling behavior cannot meet your business requirements, you can use the behavior field to configure the scale-down (scaleDown) and scale-up (scaleUp) behaviors with finer granularity. For more information, see Configurable scaling behavior.

Typical scenarios for behavior include but are not limited to:

• Rapidly scale out during sudden traffic spikes.

• Rapidly scale out but slowly scale in for workloads with frequent fluctuations.

• Disable scale-in for state-sensitive applications.

• In resource-constrained or cost-sensitive scenarios, the stabilization window stabilizationWindowSeconds limits the scale-out rate to reduce frequent adjustments caused by temporary fluctuations.

For a description and examples of the behavior configuration, see Tune HPA scaling sensitivity.

FAQ

• Why is the `current` field for HPA monitoring data displayed as `unknown`?

• What should I do if HPA scaling fails due to abnormal metric retrieval?

• Why does HPA scale out extra pods during a rolling deployment?

• Why does HPA not scale when the threshold is reached?

• How do I configure the HPA collection cycle?

• Is CronHPA compatible with HPA? How do I make it compatible?

• How do I prevent HPA from scaling out extra pods due to high CPU or memory usage during startup?

• Why does HPA scale even if the audit log values do not reach the threshold?

• Can I determine the pod scale-in order during an HPA scale-in?

• What do the units of HPA utilization metrics mean?

• What should I do if the `target` column is `unknown` after I run `kubectl get hpa`?

• How do I find the metric names supported by HPA?

• How do you adapt after customizing the NGINX Ingress log format?

• How do I obtain the Prometheus data request URL?

• How do I obtain the sls_ingress_qps metric using the command line?

• How do I manage a VPA that is installed with kubectl using the console?

• Failed to pull the alibaba-cloud-metrics-adapter image

Related documentation

Other related operations

• To implement Horizontal Pod Autoscaling based on metrics from Alibaba Cloud components by using Kubernetes External Metrics, see Horizontal Pod Autoscaling based on Nginx Ingress metrics.

• To convert metrics from Managed Service for Prometheus into HPA-compatible metrics, see Horizontal Pod autoscaling based on metrics from Managed Service for Prometheus.

• For HPA troubleshooting, see Node auto scaling FAQ.

• If you need to coordinate CronHPA and HPA, see Use CronHPA with HPA.

Other workload scaling solutions

• If your application has periodic resource usage patterns and you need to scale pods based on a schedule, see Use CronHPA for scheduled horizontal scaling.

• If your application resource usage has cyclical changes that are difficult to define by using rules, you can use AHPA to automatically identify workload patterns based on historical metrics and perform Pod auto scaling. For more information, see Auto Scaling Prediction (AHPA).

• To automatically set resource limits for pods based on their resource usage, see Use Vertical Pod Autoscaler (VPA).

• To create flexible scaling policies based on events from message queues, schedules, or custom metrics, see Event-driven autoscaling.

Combined solutions

You can use HPA with the node auto scaling feature to automatically scale cluster nodes when resources are insufficient. For more information, see Enable node auto scaling.