Frequently Asked
Questions

kube-state-metrics and metrics-server serve completely different purposes and most production clusters run both.

Think of kube-state-metrics as answering "what is the desired and actual state of my Kubernetes objects?" while metrics-server answers "how much CPU and memory is my workload consuming right now?"

cAdvisor (Container Advisor) monitors resource consumption at the container level — CPU throttling, memory usage, network I/O, filesystem reads. kube-state-metrics monitors the Kubernetes API state — deployment replica counts, pod restart counts, node conditions, PVC binding status.

For complete Kubernetes observability, run kube-state-metrics + cAdvisor + Prometheus together. kube-state-metrics tells you a pod is crash-looping; cAdvisor tells you that pod is consuming 4× its memory limit.

node-exporter runs as a DaemonSet and exposes hardware and OS-level metrics for each node: CPU load, memory pressure, disk I/O, network interface statistics, systemd service health. kube-state-metrics exposes Kubernetes API objects — it knows nothing about the underlying OS.

• node-exporter: node_cpu_seconds_total, node_memory_MemAvailable_bytes, node_disk_io_time_seconds_total
• kube-state-metrics: kube_node_status_condition, kube_node_spec_taint, kube_node_labels

Production Prometheus stacks (kube-prometheus-stack) install all three: node-exporter + cAdvisor + kube-state-metrics.

No — they're complementary. kube-state-metrics is a metrics exporter: it reads the Kubernetes API and exposes state data in the Prometheus exposition format on port 8080/metrics. Prometheus is a metrics store and query engine: it scrapes kube-state-metrics, stores the data as time-series, and lets you query it with PromQL.

Without kube-state-metrics, Prometheus has no knowledge of Kubernetes object state. Without Prometheus, kube-state-metrics data is ephemeral with no historical record.

kube-state-metrics exposes metrics on port 8080 by default (--port=8080). It also exposes a self-monitoring telemetry endpoint on port 8081 (--telemetry-port=8081).

To verify: kubectl port-forward svc/kube-state-metrics 8080:8080 -n monitoring then curl http://localhost:8080/metrics.

The general rule: each kube-state-metrics minor version supports the 5 most recent Kubernetes minor versions. Always check the official compatibility matrix before upgrading.

No, k3s does not bundle kube-state-metrics. k3s ships with a minimal set of components (klipper-lb, local-path-provisioner, Traefik, CoreDNS). You need to install kube-state-metrics separately via Helm or kubectl. The standard Helm install works identically on k3s as on any other Kubernetes distribution.

There are two quick ways:

# Check the image tag on the deployment
kubectl get deploy kube-state-metrics -n monitoring \
  -o jsonpath='{.spec.template.spec.containers[0].image}'

# Or check the build info metric
curl http://localhost:8080/metrics | grep kube_state_metrics_build_info

The kube_state_metrics_build_info metric exposes the version, Go version, git commit, and build date as labels.

kube-state-metrics (KSM) is an open-source Kubernetes add-on that listens to the Kubernetes API server and generates metrics about the state of Kubernetes objects. It converts Kubernetes object data into Prometheus-compatible metrics that can be scraped, stored, and queried.

KSM exposes 200+ metrics covering Pods, Deployments, Nodes, StatefulSets, DaemonSets, Jobs, CronJobs, PersistentVolumeClaims, HPAs, Services, Namespaces, and more. It is a CNCF project maintained by the Kubernetes community.

kube-state-metrics runs as a single Deployment (or StatefulSet with autosharding for large clusters). It:

1. Connects to the Kubernetes API server via an in-cluster service account
2. Watches all configured resource types using the Watch API
3. Maintains an in-memory cache of object state
4. Exposes that state as Prometheus metrics on :8080/metrics
5. Prometheus scrapes the endpoint every 15–60 seconds
6. Grafana and alerting tools query Prometheus for dashboards and alerts

The project is hosted at github.com/kubernetes/kube-state-metrics and images are published at registry.k8s.io/kube-state-metrics/kube-state-metrics.

By default, kube-state-metrics does not expose Kubernetes object labels as metric labels (to avoid high cardinality). You opt-in using the --metric-labels-allowlist flag:

--metric-labels-allowlist=pods=[app,version,tier],\
  deployments=[app,environment]

This adds those Kubernetes labels as label_<key>=<value> dimensions on the relevant metrics — enabling queries like kube_pod_labels{label_app="nginx"}.