How to Configure Kubernetes Horizontal Pod Autoscaler with Cpu and Memory Metrics Using the Metrics Server

ByAkensai

Learning how to configure Kubernetes Horizontal Pod Autoscaler with CPU and Memory Metrics using the Metrics Server is one of the most practical skills for running production workloads. When traffic spikes, your application needs to scale up automatically. When traffic drops, it should scale back down to save resources. The Horizontal Pod Autoscaler (HPA) handles this automatically. It watches resource metrics and adjusts your pod count in real time. Without it, you’re either over-provisioning and wasting money, or under-provisioning and risking downtime. This tutorial walks you through installing the Metrics Server, creating a deployment, and configuring HPA rules for both CPU and memory. By the end, you’ll have a fully working autoscaler running in your cluster.

Prerequisites for Configuring Kubernetes Horizontal Pod Autoscaler

Before you start, make sure your environment is ready. Missing a requirement will cause failures later.

Required tools and access:

  • A running Kubernetes cluster (v1.23 or later recommended)
  • kubectl installed and configured with cluster access
  • Cluster admin permissions
  • Basic familiarity with Kubernetes deployments and YAML files

Estimated time: 30–45 minutes

You’ll also need the Metrics Server deployed in your cluster. Many managed Kubernetes services like GKE or EKS include it by default. On bare-metal or local clusters like Minikube or Kind, you’ll need to install it manually. We cover that in Step 1.

Check if the Metrics Server is already running with this command:

kubectl get deployment metrics-server -n kube-system

If you see a running deployment, skip Step 1 and move to Step 2. If you get an error or no output, follow every step below.

You should also confirm that your cluster supports the autoscaling/v2 API. Run:

kubectl api-versions | grep autoscaling

You need to see autoscaling/v2 in the output. This API supports both CPU and memory metrics in a single HPA resource.

Installing the Metrics Server and Configuring Kubernetes HPA

Related tutorial: How to Identify and Fix Slow MySQL Queries Using the Slow Query Log, Explain Analyze, and Performance Schema on Ubuntu Server

Now you’ll install the Metrics Server, create a sample deployment, and set up the Horizontal Pod Autoscaler step by step.

Step 1: Install the Metrics Server

Download and apply the official Metrics Server manifest. This is the standard installation method from the Kubernetes Metrics Server GitHub repository.

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

If you’re running Minikube or a cluster with self-signed certificates, the Metrics Server may fail to start. You need to add the --kubelet-insecure-tls flag. Edit the deployment:

kubectl edit deployment metrics-server -n kube-system

Find the args section under the container spec. Add this line:

- --kubelet-insecure-tls

Save and exit. Wait about 60 seconds, then verify the Metrics Server is running:

kubectl get pods -n kube-system | grep metrics-server

You should see a pod with a Running status.

Step 2: Verify metrics are available

Confirm that node and pod metrics are being collected:

kubectl top nodes
kubectl top pods --all-namespaces

Both commands should return resource usage data. If they return errors, the Metrics Server isn’t ready yet. Wait another minute and try again.

Step 3: Create a test deployment

You need a workload to autoscale. Create a simple NGINX deployment with resource requests defined. Resource requests are required for HPA to work.

kubectl create deployment hpa-demo --image=nginx --replicas=1
kubectl set resources deployment hpa-demo --requests=cpu=100m,memory=128Mi --limits=cpu=500m,memory=256Mi

Verify the deployment is running:

kubectl get deployment hpa-demo

Step 4: Create the HPA manifest with CPU and memory metrics

Create a file named hpa-demo.yaml with the following content. This uses the autoscaling/v2 API to define both CPU and memory targets.

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

This configuration scales up when CPU usage exceeds 50% or memory usage exceeds 70% of the requested amount. It allows between 1 and 10 replicas.

Apply the manifest:

kubectl apply -f hpa-demo.yaml

Step 5: Verify the HPA is working

Check the HPA status:

kubectl get hpa hpa-demo

You should see output showing current and target utilization values. It may take a minute or two for the metrics to populate.

Step 6: Simulate load to test autoscaling

Open a separate terminal and run a load generator to push CPU usage up:

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

Watch the HPA respond in real time:

kubectl get hpa hpa-demo --watch

You should see the replica count increase as CPU utilization climbs. Stop the load generator when you’re done:

kubectl delete pod load-generator

The HPA will scale back down after a cooldown period. The default scale-down stabilization window is 5 minutes.

Troubleshooting Common Kubernetes Autoscaler Problems

Even with the correct setup, a few issues come up regularly.

HPA shows “unknown” for metrics

This usually means the Metrics Server isn’t ready or resource requests aren’t set on the deployment. Run kubectl top pods to check. If that fails, restart the Metrics Server pod.

Pods aren’t scaling up

Check the HPA events for clues:

kubectl describe hpa hpa-demo

Look at the Events section at the bottom. Missing resource requests are the most common cause. Make sure your deployment has requests defined for both CPU and memory.

Metrics Server crashes on startup

This often happens on clusters with self-signed TLS certificates. Add the --kubelet-insecure-tls argument as described in Step 1. You can also check the official Kubernetes HPA documentation for additional configuration options.

Scale-down is too slow

By default, Kubernetes waits 5 minutes before scaling down. You can adjust this with the behavior field in your HPA spec. Add a custom scale-down policy to reduce the stabilization window if needed.

Conclusion

You now know how to configure Kubernetes Horizontal Pod Autoscaler with CPU and Memory Metrics using the Metrics Server from start to finish. You installed the Metrics Server, created a deployment with proper resource requests, and defined an HPA that reacts to both CPU and memory pressure. This setup keeps your application available during traffic spikes without manual intervention. From here, you can explore custom metrics using Prometheus and the custom metrics API for even more granular autoscaling control. You can also look into Vertical Pod Autoscaler (VPA) if you want Kubernetes to automatically adjust resource requests over time. Both tools work well alongside the HPA for a complete resource management strategy.

Similar Posts