Install Metrics Server On Kubernetes: A Step-by-Step Guide

Oct 23, 2025 by Jhon Lennon 59 views

Let's dive into how to install Metrics Server on Kubernetes! Guys, if you're managing a Kubernetes cluster, you know how crucial it is to monitor your resources. The Metrics Server is a fantastic, scalable, cluster-wide aggregator of resource usage data. It collects resource consumption metrics from Kubelets and exposes them in the Kubernetes API server through the Resource Metrics API. This allows tools like kubectl top, Horizontal Pod Autoscaler (HPA), and other monitoring solutions to access this data. So, let's get this set up, shall we?

Prerequisites

Before we get started, make sure you have the following:

A running Kubernetes cluster: This guide assumes you already have a Kubernetes cluster up and running. It could be on-premises, on a cloud provider (like GKE, EKS, or AKS), or even a local cluster using Minikube or Kind.
kubectl installed and configured: You need kubectl, the Kubernetes command-line tool, installed and configured to communicate with your cluster. Verify this by running kubectl get nodes and ensuring it returns your nodes.
Basic understanding of Kubernetes concepts: Familiarity with Pods, Deployments, Services, and Namespaces will be helpful.

With those prerequisites out of the way, let's jump into the installation steps.

Step 1: Deploy the Metrics Server

The simplest way to deploy the Metrics Server is by using the pre-built manifest files provided by the Kubernetes community. These manifest files contain all the necessary Kubernetes resources (Deployments, Services, RBAC configurations, etc.) to get the Metrics Server running. You can download and apply these manifests directly from the official Metrics Server GitHub repository or use a direct link for convenience. This method ensures you're using a known, working configuration. Downloading from the official source ensures you get the latest version with all security patches and feature updates. Let's walk through the process. First, download the manifest file:

kubectl apply -k github.com/kubernetes-sigs/metrics-server/config/deploy?ref=release-0.6

This command applies the Kubernetes manifests directly from the specified Git repository path. It’s a convenient way to deploy applications without needing to download and store the YAML files locally. The kubectl apply -k command is particularly useful for applying Kubernetes manifests organized as Kustomize packages.

After running the command, Kubernetes will start deploying the Metrics Server to your cluster. This involves creating the necessary Pods, Services, and other resources defined in the manifest files. Now, let's verify that the Metrics Server is running correctly.

Step 2: Verify the Deployment

After applying the manifest, it's essential to verify that the Metrics Server has been deployed correctly and is running without issues. You can do this by checking the status of the deployed Pods and examining the logs for any errors. Using kubectl, you can easily retrieve this information. To start, let's check the status of the Pods in the kube-system namespace, where the Metrics Server is typically deployed:

kubectl get pods -n kube-system

This command lists all the Pods running in the kube-system namespace. Look for a Pod with a name starting with metrics-server. The status of this Pod should be Running. If the status is anything other than Running (e.g., Pending, Error, CrashLoopBackOff), there may be an issue with the deployment.

If the Pod is not running, you can get more details by describing the Pod:

kubectl describe pod <metrics-server-pod-name> -n kube-system

Replace <metrics-server-pod-name> with the actual name of the Metrics Server Pod. The describe command provides detailed information about the Pod, including events, resource requests, and any issues encountered during deployment. Pay close attention to the Events section, which often contains error messages or warnings that can help diagnose problems.

Another useful way to diagnose issues is by examining the logs of the Metrics Server Pod:

kubectl logs <metrics-server-pod-name> -n kube-system

Again, replace <metrics-server-pod-name> with the actual name of the Metrics Server Pod. The logs command displays the logs generated by the Metrics Server. Look for any error messages or warnings that could indicate a problem. Common issues include incorrect RBAC configurations, inability to connect to the Kubelet, or problems with certificate validation.

Once you've verified that the Metrics Server is running, you can proceed to the next step: checking if the metrics are accessible.

Step 3: Check Metrics API

Now that the Metrics Server is deployed and running, let's ensure that the metrics are being properly exposed through the Kubernetes API. This is crucial for other tools and components, like kubectl top and the Horizontal Pod Autoscaler (HPA), to access the resource usage data. The simplest way to check this is by using the kubectl top command. First, try running kubectl top node to see the resource usage of your cluster's nodes:

kubectl top node

This command should display the CPU and memory usage of each node in your cluster. If the Metrics Server is working correctly, you should see a table with the node names, CPU usage, and memory usage. If you encounter an error message like error: metrics not available yet, it indicates that the Metrics Server is not yet providing metrics or that there is a problem with the API aggregation.

Similarly, you can check the resource usage of your Pods using the following command:

kubectl top pod -n <namespace>

Replace <namespace> with the namespace where your Pods are running. This command displays the CPU and memory usage of each Pod in the specified namespace. If you see the resource usage data, it confirms that the Metrics Server is working correctly and that the metrics are accessible through the Kubernetes API.

If kubectl top commands are not working, there might be an issue with API aggregation. You can check the status of the API service by running:

kubectl get apiservice v1beta1.metrics.k8s.io -o yaml

This command retrieves the YAML definition of the apiservice for the Metrics Server. Look for the status field in the output. If the status indicates an error or if the available condition is False, there may be a problem with the API aggregation. Ensure that the apiservice is properly configured and that there are no errors reported in the status.

Troubleshooting API aggregation issues might involve checking the Metrics Server logs for any related error messages and ensuring that the necessary RBAC permissions are in place. Also, verify that the Kubernetes API server is correctly configured to aggregate the metrics from the Metrics Server.

Step 4: Addressing Common Issues

While installing the Metrics Server is generally straightforward, you might encounter some common issues. Let's address a few of these to help you troubleshoot effectively. One common problem is the x509: certificate signed by unknown authority error. This error typically occurs when the Metrics Server is unable to validate the Kubelet's serving certificate. To resolve this, you can add the --kubelet-insecure-tls flag to the Metrics Server deployment. This flag tells the Metrics Server to skip the certificate validation. However, this is not recommended for production environments as it reduces security. A more secure approach is to properly configure the Kubelet certificates.

To add the --kubelet-insecure-tls flag, you need to edit the Metrics Server deployment. First, get the deployment:

kubectl get deployment metrics-server -n kube-system -o yaml > metrics-server-deployment.yaml

This command retrieves the YAML definition of the Metrics Server deployment and saves it to a file named metrics-server-deployment.yaml. Next, edit the metrics-server-deployment.yaml file and add the --kubelet-insecure-tls flag to the args section of the metrics-server container:

    spec:
      containers:
      - args:
        - --cert-dir=/tmp
        - --secure-port=4443
        - --kubelet-insecure-tls
        image: k8s.gcr.io/metrics-server/metrics-server:v0.6.1
        name: metrics-server

Save the changes and apply the updated deployment:

kubectl apply -f metrics-server-deployment.yaml

This command applies the updated deployment to your cluster. Kubernetes will update the Metrics Server Pod with the new configuration. After the Pod restarts, the --kubelet-insecure-tls flag will be in effect, and the certificate validation error should be resolved.

Another common issue is related to RBAC permissions. The Metrics Server requires specific RBAC permissions to access the necessary resources in the cluster. If you encounter errors related to unauthorized access, ensure that the necessary RBAC roles and role bindings are in place. The manifest files provided by the Kubernetes community typically include these RBAC configurations, but it's worth verifying that they are correctly applied.

Step 5: Monitoring Metrics Server

Once the Metrics Server is up and running, it's important to monitor its health and performance. This ensures that it continues to provide accurate and timely metrics data. Kubernetes provides several ways to monitor the Metrics Server, including checking the Pod status, examining the logs, and setting up monitoring tools.

As mentioned earlier, you can check the status of the Metrics Server Pod using the kubectl get pods command:

kubectl get pods -n kube-system

Ensure that the Metrics Server Pod is in the Running state and that there are no recent restarts. Frequent restarts could indicate a problem with the Metrics Server.

Examining the logs of the Metrics Server Pod can also provide valuable insights into its health and performance:

kubectl logs <metrics-server-pod-name> -n kube-system

Look for any error messages or warnings that could indicate a problem. Pay attention to messages related to connectivity issues, certificate validation, or resource usage.

For more comprehensive monitoring, you can integrate the Metrics Server with monitoring tools like Prometheus. Prometheus can scrape metrics from the Metrics Server and store them in a time-series database. This allows you to visualize the metrics using tools like Grafana and set up alerts based on predefined thresholds.

To configure Prometheus to scrape metrics from the Metrics Server, you need to define a scrape configuration in your Prometheus configuration file. This configuration specifies the target endpoint for the Metrics Server and any necessary authentication or authorization settings.

Here's an example of a Prometheus scrape configuration:

scrape_configs:
  - job_name: 'kubernetes-metrics-server'
    kubernetes_sd_configs:
      - role: service
    relabel_configs:
      - source_labels: [__meta_kubernetes_service_name]
        regex: 'metrics-server'
        action: keep
      - source_labels: [__meta_kubernetes_service_namespace]
        action: replace
        target_label: namespace

This configuration tells Prometheus to discover the Metrics Server Service using Kubernetes service discovery and scrape metrics from it. After configuring Prometheus, you can create Grafana dashboards to visualize the Metrics Server metrics. This provides a comprehensive view of the Metrics Server's health and performance, allowing you to identify and address any issues proactively.

Conclusion

Alright, guys! You've successfully installed and configured the Metrics Server on your Kubernetes cluster. With the Metrics Server running, you can now leverage tools like kubectl top and the Horizontal Pod Autoscaler (HPA) to monitor and scale your applications effectively. You've also learned how to troubleshoot common issues and monitor the Metrics Server's health and performance.

Remember, monitoring is crucial for maintaining a healthy and efficient Kubernetes cluster. The Metrics Server is a valuable tool in your monitoring arsenal, providing the necessary resource usage data for informed decision-making. Keep exploring and expanding your Kubernetes knowledge, and you'll become a Kubernetes pro in no time!