kubernetes /kube-state-metrics

Add-on agent to generate and expose cluster-level metrics.

★ 6,238⑂ 2,207👁 76⑃ 2,062● 1,104▤ 99
下载:v2.20.0v2.20.0 ↓2.20.02026-08-18
+0
日增长
+3
周增长
+16
月增长
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

Latest release

v2.20.0 v2.20.0 2026-08-18
v2.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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON