kube-state-metrics

kube-state-metrics (KSM) is a service that listens to the Kubernetes API server and generates metrics about the state of cluster objects such as deployments, nodes and pods. Rather than monitoring the health of individual Kubernetes components, it reports on the objects inside the cluster. Metrics are exposed as plaintext on the HTTP endpoint /metrics (default port 8080) and are intended for Prometheus or compatible scrapers; the endpoint reflects the current cluster state, so deleted objects disappear from it. Design philosophy: KSM generates metrics from Kubernetes API objects without modification, so its features share the stability grade of the underlying API objects. It exposes raw, unmodified data rather than applying kubectl-style heuristics, leaving interpretation to users. Metrics based on alpha APIs are excluded from stability guarantees. Key capabilities described in the README: - Metrics documentation in the docs directory, plus custom resource state metrics (feature-frozen in favor of resource-state-metrics). - Label handling: Kubernetes label names are converted to Prometheus-compatible names (e.g. app.kubernetes.io/name becomes label_app_kubernetes_io_name), with automatic _conflictN suffixes when conversions collide. - Allow/deny lists support ECMAScript regular expressions, including lookarounds, with evaluation capped at one minute. - Self metrics on a separate telemetry host/port (default 8081), including list/watch success and error counters, HTTP request duration histograms, build info, shard ordinal/total shards, and config file hash and reload status. - Scaling guidance: roughly 250MiB memory and 0.1 cores as a general rule; low CPU limits can cause queue buildup and higher memory use. Latency figures from a 100-node scaling test are given (Perc50 ~260ms, Perc90 ~475ms, Perc99 ~907ms). - Horizontal sharding via --shard and --total-shards, using an md5 of object UID modulo total shards; automated sharding in a StatefulSet using --pod and --pod-namespace (experimental); deployment-based sharding with explicit shard indexes; and daemonset sharding for pod metrics via --node, with --track-unscheduled-pods for unassigned pods. - Resource filtering on /metrics using resources and exclude_resources query parameters, with exclude taking precedence. - Health endpoints: /healthz and /livez on the main port, /readyz on the telemetry port. Setup and usage: install via go get k8s.io/kube-state-metrics/v2, build a container with make container, and deploy with kubectl apply -f examples/standard. The kube-prometheus stack already includes KSM as a component. GKE users may need a cluster-admin binding due to strict role permissions. The README also compares KSM with metrics-server: metrics-server serves aggregated resource metrics from Kubelet via the Metrics API, while KSM generates new metrics from object state and holds a snapshot in memory. Neither exports metrics to third-party destinations itself.