Kube State Metrics Install: Step-by-Step Guide

Most Kubernetes monitoring setups do not fail because tools are missing. They fail because the wrong metrics are installed, or configured poorly.

That is why kube-state-metrics install matters more than it seems.

Kube-State-Metrics gives you visibility into the actual state of your cluster: pods, deployments, nodes, and more. But many setups fail not because the tool is complex, but because the installation is rushed, misconfigured, or blindly copied. This guide keeps it simple. You will learn:

• exactly how to install Kube-State-Metrics
• when to use Helm vs manual setup
• what to configure (and what to ignore)
• how to avoid common mistakes

What Is Kube-State-Metrics (And Why You Need It)

Before installing anything, it helps to understand what you are actually adding. Kube-State-Metrics is a service that:

• reads data from the Kubernetes API
• converts it into metrics
• exposes those metrics for tools like Prometheus

Unlike resource metrics (CPU, memory), this focuses on object state. For example:

• Is a pod stuck?
• Are replicas available?
• Is a node ready?

These are the signals that help you understand what is happening structurally inside your cluster. Without it, your monitoring is incomplete.

When You Should Install Kube-State-Metrics

Not every cluster needs everything. But you should install it if:

• you use Prometheus for monitoring
• you need visibility into deployments or workloads
• you want meaningful alerts (not just CPU spikes)

Skip it only if:

• your setup is extremely small
• or you are not using any monitoring stack yet

For most real environments, it is essential.

Kube-State-Metrics Install Options (Choose the Right One)

There are two main ways to install it:

1. Helm Installation (Recommended)

• fastest
• easier to maintain
• production-friendly

2. Manual YAML Deployment

• more control
• useful for learning or custom setups
• slightly more effort

If you want a clean and scalable setup, Helm is usually the better choice.

Method 1: Install Kube-State-Metrics Using Helm

This is the simplest and most reliable way to install Kube-State-Metrics, especially if you want something clean, repeatable, and easy to maintain later. Helm handles most of the setup for you, including:

• deployment configuration
• RBAC permissions
• service exposure

So you do not have to wire everything manually.

Step 1: Add Helm Repository

First, add the official Prometheus community Helm repository:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

This gives you access to the maintained kube-state-metrics chart.

Step 2: Install the Chart

Now install Kube-State-Metrics into your cluster:

helm install kube-state-metrics prometheus-community/kube-state-metrics

By default, this will:

• create a new deployment
• set up required permissions (RBAC)
• expose a service endpoint for metrics

If you are working in a specific namespace, you can add:

--namespace monitoring --create-namespace

This helps keep your monitoring stack organized instead of mixing it with application workloads.

Step 3: Verify Installation

Once installed, do not assume it is working, verify it. Check if the pod is running:

kubectl get pods -l app.kubernetes.io/name=kube-state-metrics

You should see at least one pod in Running state. If it is not running:

• check pod logs
• confirm RBAC permissions
• verify namespace

Step 4: Confirm the Service Endpoint

Next, make sure the metrics service is available:

kubectl get svc kube-state-metrics

This service exposes the /metrics endpoint that Prometheus will scrape.

Step 5: (Optional but Important) Customize Your Setup

The default installation works, but it is not always optimal. You may want to adjust:

• resources monitored (limit noise)
• labels exposed (control cardinality)
• namespace scope (focus on relevant workloads)

These changes are usually done through Helm values.

If you want a deeper understanding of how to customize this properly, exploring a dedicated kube-state-metrics Helm chart configuration guide will help you avoid messy setups later.

Method 2: Manual Installation (YAML-Based)

If you want full control over what gets deployed, the manual (YAML-based) method is a solid option.

Step 1: Apply Deployment Files

Run the official manifests:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/kube-state-metrics/main/examples/standard/

This command creates all the required components, including:

• Service Account → allows the app to interact with the cluster
• RBAC Roles & Bindings → defines what it can access
• Deployment → runs the kube-state-metrics pod
• Service → exposes the metrics endpoint

Everything is applied in one go, so you do not need to configure each piece manually.

Step 2: Confirm Deployment

Check if the deployment is created and available:

kubectl get deployment kube-state-metrics

You want to see the deployment exists and desired and available replicas match. If something looks off, describe the deployment:

kubectl describe deployment kube-state-metrics

This helps identify issues like image pull errors or permission problems.

Step 3: Check Service Endpoint

Now verify the service:

kubectl get svc kube-state-metrics

This service exposes the /metrics endpoint that Prometheus will scrape. If needed, you can test it locally:

kubectl port-forward svc/kube-state-metrics 8080:8080

Then open:

http://localhost:8080/metrics

If you see raw metrics data, your setup is working correctly.

How Kube-State-Metrics Works After Installation

Once installed, the flow is straightforward:

Step 1: Read Kubernetes API

Kube-State-Metrics connects to the Kubernetes API server and continuously watches cluster objects. This includes resources like pods, deployments, nodes, and more.

It does not generate data on its own. It simply reads the current state of your cluster exactly as Kubernetes sees it.

Step 2: Convert to Metrics

The raw object data is not directly useful for monitoring. So Kube-State-Metrics converts that information into structured metrics.

These metrics follow Prometheus format, making them easy to query, filter, and use in dashboards or alerts.

Step 3: Expose Metrics Endpoint

Once the metrics are generated, they are exposed through an HTTP endpoint. This endpoint is usually available via a Kubernetes service inside your cluster.

Think of it as a simple data source, any monitoring tool that understands Prometheus metrics can access it.

Step 4: Prometheus Scrapes Data

Prometheus periodically connects to the metrics endpoint and pulls the data. It stores this data over time so you can run queries and track changes.

Without Prometheus (or a similar tool), the metrics are not stored anywhere, which means you lose their real value.

Step 5: Visualization and Alerts

Once the data is in Prometheus, you can visualize it using tools like Grafana. This helps you turn raw metrics into dashboards that actually make sense.

You can also create alert rules based on these metrics, such as detecting failed pods or unavailable replicas. Kube-State-Metrics itself does not analyze anything, it simply provides clean, structured data for other tools to use.

Basic Configuration You Should Not Ignore

A default install works, but not always well. Here are the key things to pay attention to:

1. Resource Scope

Limit which resources are monitored. This avoids unnecessary data collection and improves performance.

2. Labels Management

Too many labels increase metric cardinality. Start simple:

• namespace
• app
• environment

Add more only when needed.

3. Namespace Control

In large clusters, restrict monitoring to specific namespaces. This keeps queries faster and dashboards cleaner.

4. Security (RBAC)

Make sure permissions are minimal and scoped. Avoid giving broader access than necessary.

Common Mistakes to Avoid

This is where most setups go wrong.

1. Installing Without a Monitoring Stack

Kube-State-Metrics does nothing on its own. Without Prometheus:

• metrics are not collected
• data is not stored
• nothing is visualized

2. Collecting Everything by Default

More metrics ≠ better monitoring. It usually means:

• slower queries
• cluttered dashboards
• confusion

3. Ignoring Metric Usage

If you are not using a metric in:

• dashboards
• alerts

You probably do not need it.

4. Skipping Verification

Many users install and assume it works. Always check:

• pod status
• service endpoint
• Prometheus targets

5. Overcomplicating Early Setup

Start minimal. Then expand based on real needs, not assumptions.

How to Validate Your Installation Properly

A working pod is not enough. Here is how to confirm everything is actually functional:

1. Check Metrics Endpoint

kubectl port-forward svc/kube-state-metrics 8080:8080

Open:

http://localhost:8080/metrics

You should see raw metrics data.

2. Verify in Prometheus

Look for targets: kube-state-metrics should be UP

3. Test a Simple Query

Example:

kube_pod_status_phase

If it returns data, your setup is working.

When to Customize Your Setup

Default installation is fine for:

• small clusters
• learning environments

But customization makes sense when:

• you run production workloads
• you need specific alerts
• you want optimized dashboards

Do not customize blindly. Let your use case drive decisions.

A Practical Setup Approach (Simple Framework)

If you want a clean setup, follow this:

Step 1: Start Small

Enable only core resources like pods, deployments, and nodes. This gives you immediate visibility without overwhelming your system.

Step 2: Connect Prometheus

Make sure metrics are actually being scraped and stored. Without this step, your setup has no real value.

Step 3: Build Essential Alerts

Focus on real problems:

• unavailable replicas
• failed pods
• node readiness

Step 4: Expand Gradually

Add more metrics only when you need deeper insight. Avoid collecting data “just in case.”

Conclusion

Installing Kube-State-Metrics is simple. Setting it up correctly is where the real value lies.

Start with a clean installation. Keep your scope focused. Validate everything. Then expand based on actual needs.

That is how you turn raw metrics into meaningful visibility.

FAQ Section