kube-state-metrics

What is kube-state-metrics?

The kube-state-metrics image provides kube-state-metrics, a Kubernetes add-on service that generates Prometheus metrics from the state of Kubernetes objects. Unlike node-level exporters (like cAdvisor), kube-state-metrics exposes high-level object state—such as deployments, pods, replicasets, nodes, and configmaps—so you can monitor the desired vs. actual state of the cluster.

This image runs a read-only agent that listens to the Kubernetes API and produces metrics in Prometheus format. It's widely used in observability stacks to power dashboards, set alerts, and track workload health over time.

The kube-state-metrics image is essential in clusters where Prometheus is used for monitoring, and is typically deployed as part of the Prometheus Operator stack or via Helm charts.

How to use this image

The kube-state-metrics image is designed to be deployed as a service inside your Kubernetes cluster.

Deploy using Helm (recommended):

<code>helm repo add prometheus-community https://prometheus-community.github.io/helm-chartshelm install kube-state-metrics prometheus-community/kube-state-metrics</code>

Manual deployment example:

<code>apiVersion: apps/v1kind: Deploymentmetadata:  name: kube-state-metricsspec:  replicas: 1  selector:    matchLabels:      app: kube-state-metrics  template:    metadata:      labels:        app: kube-state-metrics    spec:      containers:        - name: kube-state-metrics          image: registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.11.0          ports:            - containerPort: 8080</code>

Access metrics:

Once deployed, metrics are available at:

<code>arduinoCopyEdithttp://<pod-ip>:8080/metrics</code>

These metrics can be scraped by Prometheus and visualized in tools like Grafana.

Image variants

Published under registry.k8s.io/kube-state-metrics/kube-state-metrics, this image is versioned by release.

kube-state-metrics:latest

Tracks the most recent stable release.

Use for development or testing environments.

kube-state-metrics:<version>

Tagged by version (e.g. v2.11.0, v2.10.1).

Recommended for production to ensure stability and compatibility with your Prometheus setup.

There are no Alpine, OS-specific, or slim variants. The image is based on a minimal base with only the binary and required tooling.