kubernetes /kube-state-metrics
Add-on agent to generate and expose cluster-level metrics.
★ 6,238⑂ 2,207👁 76⑃ 2,062● 1,104▤ 99
kubernetesprometheusmonitoringobservabilityprometheus-exportermetricskubernetes-monitoringkubernetes-exporter
More from this author
+0
Daily
+3
Weekly
+16
Monthly
6,238
stars
2,207
forks
76
watchers
2,062
prs
1,104
issues
99
releases
README
Overview
kube-state-metrics (KSM) is a simple service that listens to the Kubernetes API
server and generates metrics about the state of the objects. (See examples in
the Metrics section below.) It is not focused on the health of the individual
Kubernetes components, but rather on the health of the various objects inside,
such as deployments, nodes and pods.
kube-state-metrics is about generating metrics from Kubernetes API objects
without modification. This ensures that features provided by kube-state-metrics
have the same grade of stability as the Kubernetes API objects themselves. In
turn, this means that kube-state-metrics in certain situations may not show the
exact same values as kubectl, as kubectl applies certain heuristics to display
comprehensible messages. kube-state-metrics exposes raw data unmodified from the
Kubernetes API, this way users have all the data they require and perform
heuristics as they see fit.
The metrics are exported on the HTTP endpoint /metrics on the listening port
(default 8080). They are served as plaintext. They are designed to be consumed
either by Prometheus itself or by a scraper that is compatible with scraping a
Prometheus client endpoint. You can also open /metrics in a browser to see
the raw metrics. Note that the metrics exposed on the /metrics endpoint
reflect the current state of the Kubernetes cluster. When Kubernetes objects
are deleted they are no longer visible on the /metrics endpoint.
[!NOTE]
This README is generated from a template. Please make your changes there and run make generate-template.
Table of Contents
Versioning
Kubernetes Version
Compatibility matrix
Resource group version compatibility
Container Image
Metrics Documentation
Custom Resource State Metrics
ECMAScript regular expression support for allow and deny lists
Conflict resolution in label names
Kube-state-metrics self metrics
kube-state-metrics vs. metrics-server
Scaling kube-state-metrics
Resource recommendation
Latency
A note on costing
Horizontal sharding
Automated sharding
Deployment sharding
Daemonset sharding for pod metrics
Resource filtering
Setup
Building the Docker container
Usage
Kubernetes Deployment
Limited privileges environment
Helm Chart
Development
Developer Contributions
Community
Versioning
Kubernetes Version
kube-state-metrics uses client-go to talk with
Kubernetes clusters. The supported Kubernetes cluster version is determined by
client-go.
All additional compatibility is only best effort, or happens to still/already be supported.
Compatibility matrix
At most, 5 kube-state-metrics and 5 kubernetes releases will be recorded below.
Generally, it is recommended to use the latest release of kube-state-metrics. If you run a very recent version of Kubernetes, you might want to use an unreleased version to have the full range of supported resources. If you run an older version of Kubernetes, you might need to run Top issues
#2261kube-state-metrics - write: broken pipe45 comments · 2023-12-08#2041Missing replacement config for VPA collector in CRM42 comments · 2023-04-05#2380Purpose of `kube_pod_status_ready{condition="unknown"}`25 comments · 2024-04-22#1485Set logging output to json format23 comments · 2021-05-20#2612kube_pod_status_reason is 0 for all reasons20 comments · 2025-02-18#2118kube_pod_completion_time is not returned for some pods19 comments · 2023-07-17#2081High Availability setup documentation request19 comments · 2023-05-24#1887Address lint reports19 comments · 2022-11-08
Latest release
v2.20.0 v2.20.0 2026-08-18v2.20.0 / 2026-08-16 Notes Custom Resource State (CRS) metrics are now feature-frozen; no new CRS features will be accepted going forward. See 3050 for details. This release builds with Go v1.26.6 This release builds with k8s.io/client-go: v0.36.3 Changelog [CHANGE] kube_pod_status_reason now emits a row only for the reason that is actually set, instead of one zero/one row per known reason for every pod by @bhope in 3089 [FEATURE] Add kube_pod_status_disruption_reason metric for pods evicted via the Eviction API by @bhope in 3088 [FEATURE] Add MutatingAdmissionPolicy a