Kubernetes HPA: Horizontal Pod Autoscaler Setup & Tuning Guide

HPA vs KEDA vs VPA Comparison

Basic CPU-Based HPA

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: myapp-hpa
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  minReplicas: 2
  maxReplicas: 20
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70   # Scale when CPU > 70% of requests

CPU + Memory Multi-Metric HPA

spec:
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: AverageValue
        averageValue: 512Mi   # Scale when avg memory > 512Mi/pod

With multiple metrics, HPA takes the maximum recommendation from all metrics — if CPU wants 8 replicas and memory wants 12, HPA scales to 12.

Stabilization Window & Scale Behavior

The stabilization window prevents flapping during traffic spikes. For scale-down, the default is 300 seconds (5 minutes). For scale-up, the default is 0 (immediate). Customize with the behavior block.

spec:
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 60   # React to sustained load, not spikes
      policies:
      - type: Percent
        value: 50           # Max 50% increase per period
        periodSeconds: 60
    scaleDown:
      stabilizationWindowSeconds: 300  # Wait 5 min before scaling down
      policies:
      - type: Pods
        value: 2            # Remove at most 2 pods per minute
        periodSeconds: 60

KEDA: Event-Driven Autoscaling

KEDA adds a ScaledObject CRD that wraps HPA with external event source scalers. It can scale to zero — perfect for queue workers with no messages.

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: queue-worker-scaler
spec:
  scaleTargetRef:
    name: queue-worker
  minReplicaCount: 0    # Scale to zero when idle
  maxReplicaCount: 50
  triggers:
  - type: aws-sqs-queue
    metadata:
      queueURL: https://sqs.us-east-1.amazonaws.com/123/myqueue
      queueLength: "5"      # Scale up when queue depth > 5
      awsRegion: us-east-1
  - type: prometheus
    metadata:
      serverAddress: http://prometheus:9090
      metricName: http_requests_total
      threshold: "100"      # 100 req/sec per replica

Debugging HPA

# Check HPA status
kubectl get hpa -n production
# NAME         REFERENCE            TARGETS   MINPODS   MAXPODS   REPLICAS
# myapp-hpa    Deployment/myapp     72%/70%   2         20        8

# Detailed status including conditions
kubectl describe hpa myapp-hpa -n production

# Common issues:
# - AbleToScale: False → metrics not available (install metrics-server)
# - ScalingActive: False → zero pods or paused
# - DesiredReplicas not changing → stabilization window active

# Install metrics server (if missing)
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml