Horizontal Pod Autoscaling on AWS EKS: Setup, YAML Example, and Common Mistakes

What Horizontal Pod Autoscaling is

Horizontal Pod Autoscaling is a Kubernetes controller that watches a Deployment (or StatefulSet, or ReplicaSet) and automatically adjusts the running pod replica count based on observed resource usage.

The word “horizontal” is key. It means adding or removing identical copies of your pod, not making any single pod bigger. Adding more pods is horizontal scaling. Changing the CPU or memory limits on existing pods would be vertical scaling, and that is handled by a different component (the Vertical Pod Autoscaler, which is outside the scope of this guide).

HPA in simple terms

You set a CPU target, say 70%. You set a floor (minReplicas) and a ceiling (maxReplicas). HPA does the rest. Your application gets more capacity when it needs it and stops paying for idle capacity when it does not.

How HPA works on EKS

HPA runs a continuous reconciliation loop inside the Kubernetes control plane. Every 15 seconds it runs through four steps.

Step 1: Collect metrics

HPA queries Metrics Server for current CPU and memory usage across all pods in the target Deployment.

Step 2: Calculate utilisation

HPA expresses CPU usage as a percentage of each pod’s resources.requests.cpu. If a pod requests 250m CPU and is currently using 175m, utilisation is 70%. Resource requests are the denominator in this calculation. Without them, the denominator is zero and HPA cannot compute anything.

Step 3: Calculate desired replicas

HPA uses this formula:

desiredReplicas = ceil( currentReplicas x (currentUtilisation / targetUtilisation) )

Example: 3 pods at 84% average CPU with a 70% target gives ceil(3 x (84 / 70)) = ceil(3.6) = 4. HPA scales to 4 pods.

Step 4: Update the Deployment

If the desired count is within your minReplicas and maxReplicas bounds and differs from the current count, HPA updates spec.replicas on the Deployment. Kubernetes creates or removes pods to match.

Scale-up is aggressive by default. When utilisation exceeds the target, HPA acts on the next cycle.

Scale-down is deliberately slow. After utilisation drops below the target, HPA waits 5 minutes before removing any pods. This prevents thrashing: a cycle where the HPA scales down, traffic bounces back, and it has to scale straight back up again. The 5-minute window is intentional protection, not a limitation.

When to use HPA

HPA is the right tool when your workload is stateless and receives variable traffic. Strong fits include:

• Stateless web applications. HTTP services where any pod can handle any request. HPA was built for this pattern.
• REST and gRPC API backends. Services with variable request rates across the day can scale up during peak hours and back down overnight.
• Worker services consuming queues. SQS consumers can scale on queue depth via KEDA, keeping processing latency stable under variable load.
• Services with predictable traffic patterns. Even when patterns are predictable, HPA handles the timing automatically without cron-based scaling scripts.

When HPA is the wrong tool

• Stateful workloads. Databases and stateful services often cannot add replicas without coordinating data access. Scaling a StatefulSet with HPA is possible in theory but requires careful thought about state management and is rarely the right first approach.
• Workloads with no meaningful metrics. If pods have no resource requests and you have no useful custom metrics, HPA has nothing to act on.
• Scale-to-zero requirements. HPA cannot scale below minReplicas: 1. If you need a service to run zero pods when idle, use KEDA instead.

Prerequisites

Before configuring HPA, confirm you have:

• A running EKS cluster with node groups or Fargate profiles configured
• kubectl connected to the cluster (see Deploying Containers with kubectl)
• Resource requests (resources.requests.cpu) set on every container you want to scale
• Metrics Server installed and returning data (covered next)

Install Metrics Server on EKS

HPA needs a metrics source to function. For CPU and memory-based scaling it uses Metrics Server, a lightweight cluster add-on that collects resource usage from each node’s kubelet. EKS does not ship with Metrics Server pre-installed. You have two installation options.

Option 1: EKS managed add-on (recommended)

Install Metrics Server as an EKS managed add-on through the AWS console or with eksctl:

eksctl create addon \
  --name metrics-server \
  --cluster my-cluster \
  --region us-east-1

The managed add-on path means AWS handles version compatibility and updates it alongside your cluster during version upgrades. See Upgrading EKS Clusters for how add-on management fits into that process.

Option 2: Manifest install

The standard upstream manifest works on EC2 node groups:

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

Verify Metrics Server is working

kubectl get deployment metrics-server -n kube-system

Then confirm it is collecting data:

kubectl top nodes
kubectl top pods

Example Deployment with resource requests

Before creating an HPA, your Deployment must have resource requests set. Without resources.requests.cpu, HPA cannot calculate utilisation and will show <unknown> in the TARGETS column indefinitely.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web-app
  template:
    metadata:
      labels:
        app: web-app
    spec:
      containers:
        - name: web-app
          image: nginx:latest
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: "200m"       # Required for CPU-based HPA
              memory: "256Mi"   # Required for memory-based HPA
            limits:
              cpu: "500m"
              memory: "512Mi"

requests define the baseline HPA divides against to produce a percentage. limits cap what a single pod can consume. Set both on every container in every Deployment that HPA will target.

kubectl apply -f deployment.yaml

Example HPA YAML

Use the autoscaling/v2 API. It is the current stable version and supports multiple metrics and the behavior block for tuning scale-up and scale-down speed. The older autoscaling/v1 only supports CPU and should be avoided for new configurations.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web-app-hpa
  namespace: default
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Pods
          value: 2
          periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Pods
          value: 4
          periodSeconds: 60

Key fields:

• scaleTargetRef: must match the exact name and kind of your Deployment.
• minReplicas: 2: never scale below 2 pods. Setting this to 1 means a single pod crash takes your service down while HPA scales back up. Use at least 2 in production.
• maxReplicas: 10: never scale above 10. Set this based on your actual peak load, not a guess.
• averageUtilization: 70: scale up when average CPU across all pods exceeds 70% of their request. A reasonable starting point for most stateless services.
• stabilizationWindowSeconds: 300 on scale-down: wait 5 minutes of sustained below-target usage before removing pods.
• scaleDown.policies: remove at most 2 pods per 60 seconds, keeping scale-down gradual.

kubectl apply -f hpa.yaml

How to test HPA

The most reliable way to validate HPA is to generate real CPU load and observe the response.

Step 1: Apply both manifests

kubectl apply -f deployment.yaml
kubectl apply -f hpa.yaml

Step 2: Open a watch in a second terminal

kubectl get hpa -w

Step 3: Generate load

kubectl run load-generator \
  --image=busybox:1.28 \
  --restart=Never \
  -- /bin/sh -c "while true; do wget -q -O- http://web-app; done"

Step 4: Observe scaling

You should see TARGETS climb above 70%, then REPLICAS increase as HPA responds. The first scale-up typically takes 1 to 2 minutes. If new pods stay in Pending, your cluster has no remaining node capacity. You need Cluster Autoscaler or Karpenter to handle node scaling, as described in the comparison section below.

Step 5: Stop the load and watch scale-down

kubectl delete pod load-generator

REPLICAS will decrease after the 5-minute stabilisation window passes.

How to read HPA output

kubectl get hpa

Example output:

NAME           REFERENCE              TARGETS     MINPODS   MAXPODS   REPLICAS   AGE
web-app-hpa    Deployment/web-app     45%/70%     2         10        3          8m

• TARGETS: current/target. 45%/70% means average CPU is at 45% against a target of 70%. HPA is satisfied and not scaling.
• MINPODS / MAXPODS: the bounds you configured.
• REPLICAS: how many pods are currently running.

For a full picture including recent scaling decisions and the metric values HPA used:

kubectl describe hpa web-app-hpa

This is your primary diagnostic tool when scaling is not behaving as expected.

HPA vs Cluster Autoscaler vs Karpenter vs KEDA

These four systems are commonly mentioned together on EKS. They are not alternatives to each other. They operate at different levels.

The distinction that trips people up most often: HPA and KEDA scale pods. Cluster Autoscaler and Karpenter scale nodes. If HPA adds more pods than the cluster can schedule, those pods sit Pending until nodes are added. Both layers are usually needed.

Best practices

• Start with CPU at 70%. This is a sensible default for most stateless services. Adjust once you can observe how your specific application responds under real load.
• Set minReplicas to at least 2. Ensures basic availability even if a single pod or node fails.
• Set maxReplicas to a realistic ceiling. Base this on actual peak traffic with headroom, not a round number you picked at random.
• Load test before going to production. Run a load test, watch kubectl get hpa -w, and verify that HPA scales fast enough and that nodes have capacity. See Monitoring EKS Clusters for how to observe this at scale.
• Monitor latency alongside CPU. CPU is a proxy signal. Set up latency alerting so you catch cases where CPU looks fine but users are experiencing slow responses.
• Pair HPA with a node autoscaler. HPA without Cluster Autoscaler or Karpenter only works until your current nodes are full. On EKS managed node groups, configure one or the other.
• Keep resource requests accurate. Padded or guessed requests make HPA calculations unreliable. Profile your application under realistic load to get numbers you can actually use.
• Log scaling events. HPA scaling actions appear in Kubernetes events. Forward them to your logging system (see Logging in Kubernetes on AWS) to make post-incident analysis easier.