kube-state-metrics — Kubernetes Cluster State Metrics Exporter

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