HPA on k3s (CPU Autoscaling Lab)

First PublishedMay 18, 2026ByAtif Alam

This runbook exercises pod-level Horizontal Pod Autoscaler (HPA) on a k3s cluster using CPU utilization. It does not cover node autoscaling (Cluster Autoscaler / Karpenter) — single-node labs have no node pool to grow.

Conceptual background: Autoscaling on EKS. For custom metrics, continue to Prometheus Adapter HPA on k3s after Prometheus + Grafana on k3s.

Purpose and prerequisites

Confirm cluster access

1
kubectl config current-context
2
kubectl get nodes

Expected: context points at k3s; nodes Ready.

Verify metrics-server

k3s often ships metrics-server already:

1
kubectl top nodes
2
kubectl get apiservice v1beta1.metrics.k8s.io

Expected: node CPU/memory columns; APIService Available.

If metrics not available, install metrics-server for your k3s version (follow k3s or upstream metrics-server docs), then retry kubectl top nodes.

Namespace

1
kubectl create namespace hpa-demo --dry-run=client -o yaml | kubectl apply -f -
2
kubectl config set-context --current --namespace=hpa-demo

Step 1: Deploy the workload

Create hpa-demo.yaml:

1
apiVersion: apps/v1
2
kind: Deployment
3
metadata:
4
  name: hpa-demo
5
  labels:
6
    app: hpa-demo
7
spec:
8
  replicas: 1
9
  selector:
10
    matchLabels:
11
      app: hpa-demo
12
  template:
13
    metadata:
14
      labels:
15
        app: hpa-demo
16
    spec:
17
      containers:
18
        - name: stress
19
          image: registry.k8s.io/hpa-example
20
          ports:
21
            - containerPort: 80
22
          resources:
23
            requests:
24
              cpu: 200m
25
            limits:
26
              cpu: 500m
27
---
28
apiVersion: v1
29
kind: Service
30
metadata:
31
  name: hpa-demo
32
  labels:
33
    app: hpa-demo
34
spec:
35
  ports:
36
    - port: 80
37
  selector:
38
    app: hpa-demo

CPU requests are required — without them HPA shows current metrics as unknown.

Apply:

1
kubectl apply -f hpa-demo.yaml
2
kubectl rollout status deployment/hpa-demo --timeout=120s

Step 2: Apply HPA

Create hpa-demo-hpa.yaml:

1
apiVersion: autoscaling/v2
2
kind: HorizontalPodAutoscaler
3
metadata:
4
  name: hpa-demo
5
spec:
6
  scaleTargetRef:
7
    apiVersion: apps/v1
8
    kind: Deployment
9
    name: hpa-demo
10
  minReplicas: 1
11
  maxReplicas: 5
12
  metrics:
13
    - type: Resource
14
      resource:
15
        name: cpu
16
        target:
17
          type: Utilization
18
          averageUtilization: 50

1
kubectl apply -f hpa-demo-hpa.yaml
2
kubectl get hpa
3
kubectl describe hpa hpa-demo

Expected: TARGETS eventually show a percentage (not <unknown>/50%). REPLICAS may still be 1 until load arrives.

Step 3: Baseline metrics

1
kubectl top pods -l app=hpa-demo
2
watch -n2 'kubectl get hpa,pods -l app=hpa-demo'

Step 4: Generate load

In a separate terminal, run a load generator pod:

1
kubectl run -it load-generator --rm --restart=Never --image=busybox:1.36 -- /bin/sh

Inside the shell:

1
while true; do wget -q -O- http://hpa-demo; done

Alternatively from your workstation with port-forward:

1
kubectl port-forward svc/hpa-demo 8080:80
2
# another terminal: hey -z 3m -c 20 http://127.0.0.1:8080/

Expected within a few minutes:

kubectl get hpa shows rising CURRENT CPU vs TARGET.
REPLICAS increases toward maxReplicas (5).

Step 5: Optional — scale behavior

If replicas oscillate, patch stabilization (see Autoscaling on EKS — Scale behavior):

1
kubectl patch hpa hpa-demo --type=merge -p '
2
spec:
3
  behavior:
4
    scaleDown:
5
      stabilizationWindowSeconds: 120
6
'

Troubleshooting

Symptom	What to check
`current: <unknown>`	Container CPU requests missing; wait 1–2 min after apply
`unable to get metrics`	metrics-server pods, APIService `v1beta1.metrics.k8s.io`
No scale-up under load	Target too low already met, or load not reaching pods; verify Service endpoints
`kubectl top` fails	metrics-server not running on k3s
HPA unknown but pods run	NetworkPolicy blocking metrics-server scrape path — Network policies

1
kubectl describe hpa hpa-demo
2
kubectl get events --sort-by='.lastTimestamp'
3
kubectl logs -l app=hpa-demo --tail=50

Cleanup

1
kubectl delete hpa hpa-demo
2
kubectl delete deployment,svc hpa-demo
3
kubectl delete pod load-generator --ignore-not-found
4
# optional: kubectl delete namespace hpa-demo