How to Set Up Horizontal Pod Autoscaling in Kubernetes

In this tutorial, you'll learn about How to Set Up Horizontal Pod Autoscaling in Kubernetes. We cover key concepts, practical examples, and best practices.

The Problem

Your Kubernetes deployment has a fixed number of replicas. During traffic spikes, pods are overloaded and requests time out. During low traffic, you're paying for idle resources. Horizontal Pod Autoscaler (HPA) automatically adjusts the replica count based on observed CPU, memory, or custom metrics like requests per second and queue depth.

Quick Fix

1. Ensure the metrics server is running

HPA requires the Metrics Server to collect resource utilization:

kubectl get deployment metrics-server -n kube-system

If missing, install it:

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

Verify it's collecting data:

kubectl top nodes
kubectl top pods

2. Create an HPA with kubectl autoscale

kubectl autoscale deployment my-app \
  --cpu-percent=70 \
  --min=2 \
  --max=10

This scales between 2 and 10 replicas when average CPU utilization exceeds 70%.

3. Create an HPA with a YAML manifest

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

Apply with kubectl apply -f hpa.yaml.

4. Check HPA status

kubectl get hpa

Expected output:

NAME         REFERENCE           TARGETS          MINPODS   MAXPODS   REPLICAS   AGE
my-app-hpa   Deployment/my-app   45%/70%, 60%/80% 2         10        3          5m

The TARGETS column shows current utilization / target threshold.

5. Simulate load to test autoscaling

kubectl run -it load-generator --image=busybox -- /bin/sh -c "while true; do wget -q -O- http://my-app-service; done"

Watch the HPA react in real time:

kubectl get hpa -w

6. Scale based on custom metrics

metrics:
  - type: Pods
    pods:
      metric:
        name: requests_per_second
      target:
        type: AverageValue
        averageValue: "100"

Common Causes

Use kubectl describe for Detailed Diagnostics

kubectl describe pod <pod-name>
# Events:
#   Type     Reason     Age   From     Message
#   ----     ------     ----  ----     -------
#   Warning  BackOff    5m    kubelet  Back-off restarting failed container

The Events section at the bottom of kubectl describe output is the most valuable diagnostic tool. It shows a chronological log of scheduling failures, image pull errors, and container crashes.

Prevention

• Set resource requests on all containers — HPA needs them to calculate utilization
• Define sensible minReplicas for baseline traffic and maxReplicas for peak
• Use custom metrics (requests per second, queue length) for application-aware scaling
• Test autoscaling with load generators before going to production