Container Service for Kubernetes:Use Horizontal Pod Autoscaling (HPA)

Before you begin

To use the HPA feature effectively, review the official Kubernetes documentation on Horizontal Pod Autoscaling to learn about its basic principles, algorithms, and configurable scaling behaviors.

In addition, Container Service for Kubernetes (ACK) provides various solutions for Workload Scaling (application-layer elasticity) and Node Scaling (resource-layer elasticity). Before proceeding, read Auto scaling overview for the use cases and limitations of different solutions.

Prerequisites

• An ACK managed cluster or an ACK dedicated cluster is created. For more information, see Create a cluster.

• To use kubectl commands for HPA, you must connect to your Kubernetes cluster with kubectl. For more information, see Connect to an ACK cluster using kubectl.

Create an HPA-enabled application in the console

ACK integrates the HPA feature, allowing you to create HPA-enabled applications in the ACK console. You can create an HPA when creating a new application, or enable it for an existing one. Create only one HPA per Workload to avoid conflicting scaling policies and ensure predictable behavior.

Create an HPA-enabled application by using kubectl

You can also manually create an HPA from a manifest and bind it to the Deployment object you want to scale. This lets you configure automatic Pod scaling by using kubectl commands. Create only one HPA per Workload to avoid conflicting scaling policies and ensure predictable behavior. The following steps use an HPA-enabled Nginx application as an example.

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

   Important

   To implement HPA, you must set the resource requests for your Pods. Otherwise, HPA will not function. Use the Resource Profile feature to analyze historical resource usage data and get recommendations for configuring container Requests and Limits. For more information, see Resource profile.

   Sample YAML

   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 the actual <image_name:tags>.
           ports:
           - containerPort: 80
           resources:
             requests:         # You must set requests. Otherwise, HPA cannot perform calculations and the metric is displayed as 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.

   The scaleTargetRef field specifies the object to which this HPA is bound. In this example, it is bound to the Deployment named nginx. The HPA will trigger scaling when the average CPU utilization across 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 to which the deployment can be scaled in. This must be an integer greater than or equal to 1.
     maxReplicas: 10  # The maximum number of replicas to which the deployment can be scaled out. This must be greater than minReplicas.
     metrics:
     - type: Resource
       resource:
         name: cpu
         target:
           type: Utilization
           averageUtilization: 50 # The target average utilization of the resource. This is the ratio of the average resource usage to the requested resource amount.
                  

   Kubernetes earlier than 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
                  

   To scale on both CPU and memory, add both resources under the metrics field instead of creating two separate HPAs. Scaling triggers as soon as any of the specified metrics reaches its threshold.

   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

   While the HPA is deploying, running kubectl describe hpa <HPA_NAME> (in this example, nginx-hpa) may show warning messages. 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. Wait for the HPA to be created successfully and for the Pods to meet the scaling condition (in this example, when the CPU utilization of the Nginx Pods exceeds 50%). Then, run the kubectl describe hpa <HPA_NAME> command again to check the horizontal scaling status.

   The expected output below 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 does not meet your business needs, use the behavior field to configure more granular scaling-down (scaleDown) and scaling-up (scaleUp) behaviors. For more information, see Configurable scaling behavior.

Use cases for the behavior field include:

• Scaling out rapidly during sudden traffic surges.

• Scaling out quickly and scaling in slowly in environments with frequent workload fluctuations.

• Disabling scaling in for state-sensitive applications.

• In resource-constrained or cost-sensitive scenarios, using a stabilizationWindowSeconds to limit the rate of scaling out and reduce frequent adjustments caused by brief fluctuations.

For configuration details and examples of the behavior field, see Adjust the scaling sensitivity of HPA.

FAQ

• What do I do if unknown is displayed in the current field in the HPA metrics?

• What do I do if HPA cannot collect metrics and fails to perform scaling?

• What do I do if excess pods are added by HPA during a rolling update?

• What do I do if HPA does not scale pods when the scaling threshold is reached?

• How do I configure the metric collection interval of HPA?

• Can CronHPA and HPA interact without conflicts? How do I enable CronHPA to interact with HPA?

• How do I fix the issue that excess pods are added by HPA when CPU or memory usage rapidly increases?

• What do I do if HPA scales out an application while the metric value in the audit log is lower than the threshold?

• Can HPA control the order in which pods are scaled in?

• What does the unit of the utilization metric collected by HPA mean?

• What do I do if unknown is displayed in the TARGETS column after I run the kubectl get hpa command?

• How do I find the metrics that are supported by HPA?

• How do I configure horizontal autoscaling after I customize the format of NGINX Ingress logs?

• How to obtain the Prometheus data request URL?

• How do I query the sls_ingress_qps metric from the command line?

• How to use the console to manage the VPA installed using kubectl?

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

Related documents

Related tasks

• To learn how to implement HPA based on metrics from Alibaba Cloud components when your Kubernetes cluster supports External Metrics, see Horizontally scale pods with Alibaba Cloud metrics.

• To learn how to convert Alibaba Cloud Prometheus metrics into HPA-compatible metrics to implement HPA, see Horizontal pod autoscaling based on Prometheus metrics.

• For issues encountered while using HPA, you can first refer to the Node autoscaling FAQ for troubleshooting.

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

Other Workload Scaling solutions

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

• If your application's resource usage is cyclical but difficult to define with rules, you can use the Advanced Horizontal Pod Autoscaler (AHPA). It automatically identifies business cycles from historical metrics to scale Pods. For more information, see Predictive scaling (AHPA).

• To automatically set resource requests and limits for your Pods based on their resource usage, ensuring they receive sufficient computing resources, see Use Vertical Pod Autoscaling (VPA).

• To flexibly customize scaling policies and scale Pods based on Kubernetes events such as message queues, scheduled tasks, or custom metrics, see Event-driven autoscaling.

Combined solutions

You can combine HPA with node auto-scaling, which allows the cluster to automatically add nodes when its resources are insufficient. For more information, see Enable node autoscaling.