kube-state-metrics: Open Source Monitoring & Observability

What is kube-state-metrics?

kube-state-metrics is an Apache-2.0 add-on agent for Kubernetes that listens to the Kubernetes API server and exposes metrics about the state of cluster objects, built for platform teams and operators who run Prometheus-based monitoring.

What it is

kube-state-metrics (KSM) is a service written in Go that generates metrics from Kubernetes API objects without modification. It listens to the Kubernetes API server and produces metrics describing the state of the objects inside a cluster, such as deployments, nodes, and pods. It is deliberately not focused on the health of the individual Kubernetes components themselves. Because the metrics are derived from API objects unmodified, the features it provides carry the same grade of stability as the Kubernetes API objects they describe.

The concrete problem it solves is turning raw cluster state into a scrapeable, machine-readable signal. It replaces hand-rolled scripts and ad-hoc exporters that query the API and format results for monitoring. The metrics are served as plaintext on the HTTP endpoint /metrics on the listening port, default 8080, and are designed to be consumed either by Prometheus itself or by any scraper compatible with a Prometheus client endpoint. Because the exposed data reflects the current state of the cluster, objects that are deleted stop appearing on /metrics. That raw, unmodified output is intentional: users receive all the data they require and apply their own heuristics, which is why values may differ from kubectl, since kubectl applies heuristics to display comprehensible messages.

Key capabilities

Exposes cluster object state as Prometheus-format plaintext metrics on the /metrics endpoint, default port 8080, viewable directly in a browser.
Supports Custom Resource State Metrics, so state can be generated for resources beyond the built-in Kubernetes kinds.
Provides ECMAScript regular expression support for allow and deny lists, alongside resource filtering, to control which resources are exposed.
Handles conflict resolution in label names, avoiding collisions when metric labels are assembled from API objects.
Emits kube-state-metrics self metrics for observing the exporter itself.
Scales through horizontal sharding, automated sharding, deployment sharding, and daemonset sharding for pod metrics.
Documents container image builds and deployment under a limited privileges environment.

Who uses it and how

Platform and operations teams running Prometheus in a Kubernetes cluster, deploying KSM as a Kubernetes Deployment and scraping /metrics from port 8080.
Teams that install it through the Helm Chart listed in the README rather than managing manifests by hand.
Operators in restricted environments who deploy it under the limited privileges configuration described in the README.
Large clusters where a single instance is insufficient and horizontal or automated sharding, or daemonset sharding for pod metrics, splits the scrape load.
Users who need metrics about their own custom resources and enable Custom Resource State Metrics to cover those objects.

Getting started

The README documents installation through the Helm Chart, alongside building and running the container image, Kubernetes Deployment instructions, and a limited privileges environment configuration.

How it compares

The README devotes a dedicated section to comparing kube-state-metrics with metrics-server, which places it among the Kubernetes monitoring exporters rather than resource-usage tooling. No list of paid products that it replaces is provided, so it should be read as one component in an open monitoring stack that also names Prometheus and Prometheus-compatible scrapers.

When to use it — and when not to

A self-hoster must run the agent against the cluster API server, grant it the appropriate access, expose port 8080 to a Prometheus-compatible scraper, and accept operating that pipeline themselves. It is the wrong choice for anyone expecting output that matches kubectl exactly, since KSM deliberately exposes unmodified API data and leaves heuristic interpretation to the user. Note also that the README is generated from a template at ./README.md.tpl and regenerated with make generate-template, so the published documentation should be read with that generation step in mind.

project readme (upstream, from github) — read inline

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.

Versioning
Metrics Documentation
Kube-state-metrics self metrics
kube-state-metrics vs. metrics-server
Scaling kube-state-metrics
Setup
- Building the Docker container
Usage

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 an older version in order to have full support for all resources. Be aware, that the maintainers will only support the latest release. Older versions might be supported by interested users of the community.

kube-state-metrics	Kubernetes client-go Version
v2.16.0	v1.32
v2.17.0	v1.33
v2.18.0	v1.34
v2.19.0	v1.35
v2.20.0	v1.36
main	v1.36

Resource group version compatibility

Resources in Kubernetes can evolve, i.e., the group version for a resource may change from alpha to beta and finally GA in different Kubernetes versions. For now, kube-state-metrics will only use the oldest API available in the latest release.

Container Image

The latest container image can be found at:

registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.20.0 (arch: amd64, arm, arm64, ppc64le and s390x)
Multi-architecture images

Metrics Documentation

Any resources and metrics based on alpha Kubernetes APIs are excluded from any stability guarantee, which may be changed at any given release.

See the docs directory for more information on the exposed metrics.

Custom Resource State Metrics

[!NOTE] custom-resource-state is feature-frozen in favor of resource-state-metrics. Once resource-state-metrics is stable, custom-resource-state will be deprecated.

Conflict resolution in label names

The *_labels family of metrics exposes Kubernetes labels as Prometheus labels. As Kubernetes is more liberal than Prometheus in terms of allowed characters in label names, we automatically convert unsupported characters to underscores. For example, app.kubernetes.io/name becomes label_app_kubernetes_io_name.

This conversion can create conflicts when multiple Kubernetes labels like foo-bar and foo_bar would be converted to the same Prometheus label label_foo_bar.

Kube-state-metrics automatically adds a suffix _conflictN to resolve this conflict, so it converts the above labels to label_foo_bar_conflict1 and label_foo_bar_conflict2.

If you'd like to have more control over how this conflict is resolved, you might want to consider addressing this issue on a different level of the stack, e.g. by standardizing Kubernetes labels using an Admission Webhook that ensures that there are no possible conflicts.

ECMAScript regular expression support for allow and deny lists

Starting from #2616, kube-state-metrics supports ECMAScript's regexp for allow and deny lists. This was incorporated as a workaround for the limitations of the regexp package in Go, which does not support lookarounds due to their non-linear time complexity. Please note that while lookarounds are now supported for allow and deny lists, regular expressions' evaluation time is capped at a minute to prevent performance issues.

Kube-state-metrics self metrics

kube-state-metrics exposes its own general process metrics under --telemetry-host and --telemetry-port (default 8081).

kube-state-metrics also exposes list and watch success and error metrics. These can be used to calculate the error rate of list or watch resources. If you encounter those errors in the metrics, it is most likely a configuration or perm

Frequently asked questions

Is kube-state-metrics free to use?

kube-state-metrics is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does kube-state-metrics do?

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

What is kube-state-metrics written in?

kube-state-metrics is primarily written in Go. Its source is publicly available at https://github.com/kubernetes/kube-state-metrics, and it has 6,204 GitHub stars.