Horizontal Pod Autoscaler

You set a Deployment to 3 replicas and call it a day. Traffic doubles during peak hours. Your 3 replicas are throttled. Requests queue up. An HPA would have scaled to 6 replicas automatically and then scaled back down when traffic normalized, saving cost outside peak hours.

The HPA watches a Deployment (or StatefulSet or ReplicaSet) and adjusts the replica count to maintain a target metric value. The most common target is CPU utilization: “keep average CPU usage across all Pods below 60%.”

Prerequisites: resource requests and metrics-server

HPA requires two things:

1. Resource requests on the container: the HPA calculates utilization as a percentage of the request, not of the node’s total CPU. Without a CPU request, the HPA has no baseline.
2. metrics-server: the source of CPU and memory metrics.

kubectl top pods

If this command works, metrics-server is running.

Creating an HPA

First, create a Deployment with resource requests:

nano hpa-deploy.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hpa-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hpa-demo
  template:
    metadata:
      labels:
        app: hpa-demo
    spec:
      containers:
        - name: app
          image: busybox:1.36
          command: ['sh', '-c', 'sleep 3600']
          resources:
            requests:
              cpu: '100m'
            limits:
              cpu: '500m'

kubectl apply -f hpa-deploy.yaml

Now create the HPA targeting 50% CPU utilization:

kubectl autoscale deployment hpa-demo --cpu-percent=50 --min=1 --max=5

Or equivalently, as a YAML manifest:

nano hpa.yaml

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: hpa-demo
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: hpa-demo
  minReplicas: 1
  maxReplicas: 5
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 50

Observing the HPA

kubectl get hpa

The output shows the current and target metrics, the current replica count, and the min/max bounds:

NAME       REFERENCE             TARGETS   MINPODS   MAXPODS   REPLICAS
hpa-demo   Deployment/hpa-demo   5%/50%    1         5         1

5%/50% means current CPU is 5%, target is 50%. The single replica is well within capacity, so no scaling occurs.

kubectl describe hpa hpa-demo

Look at the Events section and the Conditions section. AbleToScale: True and ScalingActive: True confirm the HPA is functioning. The conditions also show the reason for any recent scaling decisions.

How the HPA calculates replicas

The formula: desiredReplicas = ceil(currentUtilization / targetUtilization).

If the target is 50% of a 100m request (= 50m target per Pod), and the current average usage across all Pods is 200m per Pod, then ceil(200 / 50) = 4 replicas are needed.

Memory-based HPA

HPA also supports memory as a target metric:

metrics:
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 70

kubectl delete deployment hpa-demo
kubectl delete hpa hpa-demo

HPA automates replica management based on actual workload metrics. Set minReplicas to at least 2 for high-availability, size your CPU requests accurately, and watch the HPA events to understand scaling decisions. The next lesson covers the stabilization and behavior settings that control how quickly the HPA scales up and down.