# kube-state-metrics — Kubernetes Cluster State Metrics Exporter

> kube-state-metrics is a Kubernetes add-on that listens to the API server and generates Prometheus metrics about the state of Kubernetes objects like deployments, nodes, and pods.

## Install

Save as a script file and run:

# kube-state-metrics — Kubernetes Cluster State Metrics Exporter

## Quick Use
```bash
# Deploy with Helm
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install kube-state-metrics prometheus-community/kube-state-metrics

# Or deploy with kubectl
kubectl apply -f https://raw.githubusercontent.com/kubernetes/kube-state-metrics/main/examples/standard/cluster-role.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes/kube-state-metrics/main/examples/standard/deployment.yaml

# Verify metrics endpoint
kubectl port-forward svc/kube-state-metrics 8080:8080
curl localhost:8080/metrics | head -20
```

## Introduction
kube-state-metrics (KSM) is an official Kubernetes SIG project that generates Prometheus-format metrics from the Kubernetes API server. Unlike metrics-server which reports resource usage (CPU, memory), KSM focuses on the desired and actual state of cluster objects — answering questions like how many replicas are desired versus available, which pods are pending, and what conditions nodes are reporting.

## What kube-state-metrics Does
- Exports metrics for 20+ Kubernetes object types including pods, deployments, nodes, and jobs
- Provides counts, statuses, and conditions for cluster objects in Prometheus format
- Enables alerting on deployment rollout failures, pending pods, and node conditions
- Supports custom resource definitions (CRDs) for extending metrics to custom objects
- Generates metrics labels from Kubernetes annotations and labels for flexible querying

## Architecture Overview
KSM runs as a single-replica deployment that watches the Kubernetes API server using informers. When object state changes, KSM updates its in-memory representation and regenerates metrics on each scrape request. It exposes two HTTP endpoints: `/metrics` for its own operational metrics and `/metrics` on the main port for Kubernetes object metrics. The architecture is intentionally stateless — all data comes from the API server on each sync cycle. For large clusters, sharding can split the metric generation across multiple KSM instances by object type or namespace.

## Self-Hosting & Configuration
- Deploy via the Prometheus community Helm chart or the upstream kustomize manifests
- Configure monitored resources with `--resources` flag to limit scope
- Enable custom resource metrics with `--custom-resource-state-config` for CRDs
- Set up metric label and annotation allowlists with `--metric-labels-allowlist`
- Use autosharding in large clusters to distribute load across multiple replicas

## Key Features
- Official Kubernetes SIG Instrumentation project with strong community support
- Covers 20+ Kubernetes resource types out of the box
- Custom Resource State metrics for monitoring any CRD
- Stable metric naming following the Kubernetes instrumentation guidelines
- Horizontal sharding support for clusters with thousands of objects

## Comparison with Similar Tools
- **metrics-server** — reports real-time CPU and memory usage; KSM reports object state and counts
- **Prometheus node-exporter** — exposes host-level hardware and OS metrics, not Kubernetes object state
- **cAdvisor** — monitors container resource usage per node, complementary to KSM
- **OpenCost** — uses KSM metrics to calculate Kubernetes cost allocation
- **Kubernetes Dashboard** — provides a UI for cluster state but no Prometheus metrics export

## FAQ
**Q: Does kube-state-metrics replace metrics-server?**
A: No. They serve different purposes. metrics-server provides resource usage data for HPA and kubectl top. KSM provides object state metrics for monitoring and alerting.

**Q: How much resources does KSM consume?**
A: Resource usage scales with the number of Kubernetes objects. A cluster with a few thousand pods typically needs 100-200 MB of memory and minimal CPU.

**Q: Can I monitor custom resources with KSM?**
A: Yes. Version 2.x introduced Custom Resource State metrics, allowing you to define metric generation rules for any CRD via a configuration file.

**Q: Should I run multiple KSM replicas?**
A: For small to medium clusters, a single replica is sufficient. For large clusters (10,000+ objects), enable autosharding to distribute the metric generation load.

## Sources
- https://github.com/kubernetes/kube-state-metrics
- https://github.com/kubernetes/kube-state-metrics/tree/main/docs

---
Source: https://tokrepo.com/en/workflows/eab185c6-3cf6-11f1-9bc6-00163e2b0d79
Author: Script Depot