What Does Kube-State-Metrics Do? Explained in 5 Minutes

If you have ever looked at Kubernetes monitoring and felt confused, you are not alone. Metrics are everywhere but not all metrics are the same. Some show how your system is performing. Others show what your system looks like right now.

That is exactly where kube-state-metrics helps.

So, what does kube state metrics do? In simple terms, it exposes the current state of Kubernetes objects as metrics. Not CPU usage. Not memory. But things like:

• how many pods are running
• whether deployments are healthy
• if containers are restarting

This distinction matters more than most people realize. Let us break it down clearly.

What Does Kube-State-Metrics Do in Kubernetes?

Kube-state-metrics translates Kubernetes objects into readable metrics. Instead of pulling performance data, it reads the Kubernetes API and exposes structured information about pods, deployments, nodes, services, persistent volumes and more.

Think of it like this:

• Kubernetes API → holds cluster state
• Kube-state-metrics → converts that state into metrics
• Prometheus → collects and stores those metrics

This makes cluster state queryable, alertable, and visualizable. Without it, you are basically blind to what your workloads are doing structurally.

What Kind of Data Does It Expose?

Kube-state-metrics focuses on object state, not resource usage. Here is what that actually means.

Example Metrics You Get

• Pod status (running, pending, failed)
• Deployment replicas (desired vs available)
• Container restarts
• Node conditions (ready, not ready)
• PVC binding status
• Job completion state

These are not performance numbers. They are truth snapshots of your cluster.

Why This Matters

Performance tells you how things behave. State tells you whether things are correct. You need both to understand what is really happening.

How Kube-State-Metrics Works (Simple Flow)

The process is simple once you understand the flow. Kube-state-metrics sits between Kubernetes and your monitoring tools and makes cluster data usable.

Step 1: Read Kubernetes API

Kube-state-metrics connects to the Kubernetes API server. It continuously watches resources like pods, deployments, and nodes. This means it always has an up-to-date view of what is happening inside your cluster.

Step 2: Convert to Metrics

The raw data from Kubernetes is not in a format that monitoring tools can easily use. Kube-state-metrics converts this data into structured, Prometheus-compatible metrics. Each object becomes a set of readable values that can be queried and tracked over time.

Step 3: Expose Endpoint

Once the metrics are created, they are exposed through an HTTP endpoint inside the cluster. This endpoint acts as a central place where all state-related metrics are available in one format.

Step 4: Prometheus Scrapes Data

Prometheus connects to this endpoint and collects the metrics at regular intervals. It stores this data and allows you to run queries, create alerts, and track changes over time.

Step 5: Visualization in Grafana

With the data stored in Prometheus, you can build dashboards using Grafana. This helps you see things like failing pods, unhealthy deployments, or missing replicas in a clear and visual way.

Kube-State-Metrics vs Metrics Server

This confusion is extremely common and it leads to wrong monitoring setups. The key difference is simple: one shows performance, the other shows actual system state.

Metrics Server

• Tracks CPU and memory usage
• Used for autoscaling (HPA)
• Focus: performance

Kube-State-Metrics

• Tracks object states
• Used for monitoring and alerting
• Focus: structure and health

Real Example

Let us say your application suddenly stops working. You check Metrics Server first:

• CPU usage looks normal
• Memory usage looks fine

At this point, it seems like nothing is wrong. But when you check kube-state-metrics:

• pods are restarting
• deployment has unavailable replicas

Now the problem becomes clear. Your application is failing at the Kubernetes level, not at the resource level.

Metrics Server shows how resources are behaving Kube-state-metrics shows whether your system is actually working. That is why relying on only one can mislead you.

Common Use Cases

This is where kube-state-metrics becomes valuable in real setups.

1. Deployment Health Monitoring

You can track:

• desired vs available replicas
• rollout failures
• stuck deployments

. Pod Stability Tracking

Monitor:

• restart counts
• crash loops
• pending pods

3. Alerting

Set alerts like:

• deployment not meeting replica count
• pods failing repeatedly
• nodes becoming unavailable

4. Capacity Planning

Understand:

• how workloads are distributed
• how often scaling issues occur

How Kube-State-Metrics Fits Into Your Setup

Kube-state-metrics does not work alone. It is part of your Kubernetes monitoring stack. Here is how it fits in:

• Kubernetes holds the current state of your cluster
• Kube-state-metrics reads that state and converts it into metrics
• Prometheus collects and stores those metrics
• Grafana helps you visualize them in dashboards

In simple terms, kube-state-metrics acts as a bridge between Kubernetes and your monitoring tools. It does not create data. It only exposes what already exists inside the cluster. This makes it easy to:

• monitor deployments
• track pod health
• create alerts based on real cluster conditions

If you are already using Prometheus, adding kube-state-metrics completes your monitoring setup.

How Kube-State-Metrics Exposes Data

Kube-state-metrics exposes data through a simple metrics endpoint. This endpoint is usually available inside your cluster and is used by Prometheus to collect data. Here is what happens step by step:

1. Kube-state-metrics watches Kubernetes resources
2. It converts object data into metrics
3. It exposes those metrics through an HTTP endpoint
4. Prometheus scrapes the endpoint at regular intervals

You do not need to interact with this endpoint directly. It works in the background. What matters is that all cluster state data becomes easy to query, alert on and visualize. This is what turns raw Kubernetes data into something you can actually use.

What You Do NOT Get from Kube-State-Metrics

Understanding its limits is important. Kube-state-metrics only shows object state, not system performance. It does NOT provide:

• CPU usage
• memory usage
• network traffic
• application logs

If you expect performance data, you will be disappointed. Kube-state-metrics shows what is happening structurally, while other tools show how the system is performing. That is why it is used alongside other monitoring tools, not as a replacement.

Common Mistakes to Avoid

Even experienced teams get this wrong.

1. Treating It Like a Performance Tool

Kube-state-metrics does not show CPU or memory usage. It only shows object state. If you use it for performance monitoring, you will miss real issues.

2. Enabling Everything by Default

Turning on all metrics creates too much data. This makes dashboards messy and queries slow. Start small. Add only what you actually need.

3. Ignoring Labels

Labels help you filter and group metrics. Without them, data becomes hard to understand. Good labels make your monitoring clear and useful.

4. Not Using It for Alerts

Collecting data is not enough. You need alerts to catch problems early. Without alerts, issues can go unnoticed for a long time.

When You Actually Need Kube-State-Metrics

You need it if:

• you run production workloads
• you care about uptime and reliability
• you want meaningful alerts
• you use Prometheus or Grafana

You might not need it if:

• your setup is very small
• you only care about basic resource usage

Conclusion

Kube-state-metrics does one thing extremely well. It turns Kubernetes object state into usable metrics. That single capability unlocks:

• better monitoring
• smarter alerts
• deeper visibility

If you care about understanding what your cluster is actually doing, you need it.

FAQ Section