Kubernetes HPA: Auto-Scaling Pods Under Load

Manually adjusting replica counts during traffic spikes is both slow and error-prone. Kubernetes Horizontal Pod Autoscaler (HPA) automatically scales Pod count up or down based on CPU usage, memory consumption, or custom metrics. This guide covers HPA configuration from scratch, Metrics Server setup, and production best practices.

How Does HPA Work?

HPA queries Pod metrics from the Metrics API at regular intervals (default 15 seconds). It compares the current metric value against the target and calculates the required replica count. The formula is straightforward:

Metrics Server Setup

HPA requires Metrics Server to be installed in the cluster. Metrics Server collects CPU and memory metrics from kubelets and exposes them via the Metrics API.

# Install Metrics Server
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

# Verify installation
kubectl get deployment metrics-server -n kube-system

# Check node and pod metrics
kubectl top nodes
kubectl top pods

CPU-Based HPA Configuration

The most common HPA scenario is scaling based on CPU usage. In the following example, Pod count increases when average CPU exceeds 60% and decreases when it drops.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-app
  minReplicas: 2
  maxReplicas: 20
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 60

Scaling with Memory and Multiple Metrics

You can add memory usage as a target alongside CPU. When multiple metrics are defined, HPA selects the highest replica count.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-app
  minReplicas: 2
  maxReplicas: 30
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 60
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 75
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
      - type: Percent
        value: 10
        periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 30
      policies:
      - type: Percent
        value: 50
        periodSeconds: 60

The behavior section controls scaling speed. scaleDown.stabilizationWindowSeconds: 300 preserves the highest replica count from the last 5 minutes, preventing premature scale-downs. scaleUp is configured more aggressively for faster response.

HPA Best Practices

• Set Accurate Resource Requests CPU and memory request values should reflect your application's consumption under normal load. Too-low requests cause unnecessary scaling; too-high requests cause insufficient scaling.
• Use Scale Down Stabilization The default 300-second stabilization window works well for most scenarios. It prevents unnecessary scale-downs during brief traffic dips.
• Define Readiness Probes Newly created Pods shouldn't receive traffic before they're ready. Without readiness probes, HPA considers new Pods immediately active, increasing response times.
• Don't Use HPA and VPA on the Same Metric If Vertical Pod Autoscaler (VPA) and HPA target the same metric (CPU), they'll conflict. Use VPA for memory only and HPA for CPU, or consider Multidimensional Pod Autoscaler.

For Kubernetes fundamentals, check our Introduction to Kubernetes guide. For application deployment, see our Helm Chart guide. For monitoring infrastructure, read our Prometheus + Grafana guide. The Kubernetes HPA documentation and Metrics Server project are valuable additional resources.

Frequently Asked Questions

Conclusion

Kubernetes HPA automatically responds to traffic fluctuations, ensuring both performance and cost efficiency. Install Metrics Server, set accurate resource requests, use scale-down stabilization, and define readiness probes. When custom metrics are needed, extend HPA with Prometheus Adapter or KEDA.