kube-state-metrics is a Kubernetes add-on agent written in Go that listens to the Kubernetes API server and generates metrics about the state of cluster objects. Rather than monitoring the health of individual Kubernetes components, it focuses on the health and state of objects within the cluster such as deployments, nodes, and pods. The project exposes these metrics on an HTTP endpoint at /metrics on port 8080 by default, serving them as plaintext in a format compatible with Prometheus scraping.
A core design principle of kube-state-metrics is generating metrics directly from Kubernetes API objects without modification. This approach ensures that the stability grade of metrics matches that of the underlying Kubernetes API objects themselves. The service exposes raw, unmodified data from the Kubernetes API, allowing users to access complete information and apply their own heuristics for interpretation rather than relying on the simplified representations that kubectl provides. The metrics reflect the current state of the cluster, and when Kubernetes objects are deleted, they no longer appear on the metrics endpoint.
The project maintains compatibility with multiple Kubernetes versions through the client-go library. According to the compatibility matrix, recent releases support Kubernetes versions ranging from v1.32 to v1.35, with the main development branch targeting v1.36. Container images are available for multiple architectures including amd64, arm, arm64, ppc64le, and s390x. The project distinguishes itself from the metrics-server by focusing on generating new metrics from Kubernetes object state rather than serving performance metrics from nodes and pods.
The project shares contributors with other major Kubernetes ecosystem projects including thanos-io/thanos, prometheus/prometheus, and kubernetes/kubernetes.
The repository includes comprehensive documentation covering metrics, deployment options, and scaling considerations. It supports resource filtering, horizontal sharding for scaling across multiple instances, and both standard Kubernetes deployment and Helm chart installation methods. The project exposes its own telemetry metrics on a separate port, including list and watch success and error metrics that can help diagnose configuration or permission issues. It also provides build information and configuration metrics for monitoring the kube-state-metrics service itself.
kube-state-metrics handles label name conflicts that arise from differences between Kubernetes and Prometheus character set restrictions by automatically converting unsupported characters to underscores and appending conflict suffixes when necessary. The project supports ECMAScript regular expressions for allow and deny lists with evaluation time capped at one minute to prevent performance degradation. Resource recommendations suggest allocating 250MiB of memory and 0.1 cores as a baseline, with usage scaling proportionally to the number of Kubernetes objects in the cluster.
