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