The kube-state-metrics Helm chart is the recommended installation method for production Kubernetes clusters. Maintained by the prometheus-community, it handles RBAC, ServiceAccount, Service, and Deployment configuration in one command — with a rich set of customisable values for resource limits, sharding, and label allowlists.

Prerequisites

Step 1 — Add the Helm Repository

The kube-state-metrics Helm chart is published in the prometheus-community repository:

helm repo add prometheus-community \
  https://prometheus-community.github.io/helm-charts
helm repo update

Step 2 — Install kube-state-metrics

A minimal install into the monitoring namespace:

helm install kube-state-metrics \
  prometheus-community/kube-state-metrics \
  --namespace monitoring \
  --create-namespace
ℹ️
The chart name kube-state-metrics becomes the Helm release name. The resulting Kubernetes resources (Deployment, Service, RBAC) are prefixed with this name.

Step 3 — Verify the Deployment

# Check rollout status
kubectl rollout status deployment/kube-state-metrics -n monitoring

# Confirm the pod is running
kubectl get pods -n monitoring -l app.kubernetes.io/name=kube-state-metrics

# Port-forward and check metrics
kubectl port-forward svc/kube-state-metrics 8080:8080 -n monitoring &
curl http://localhost:8080/metrics | grep kube_deployment_

Production Helm Values

For production use, override the default values. Create a ksm-values.yaml:

replicaCount: 2
autosharding:
  enabled: true          # Auto-assigns shards via StatefulSet ordinal
resources:
  requests:
    cpu: 50m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi
metricLabelsAllowlist:
  - pods=[app,version,environment]
  - deployments=[app,team]
collectors:             # Only enable what you need
  - pods
  - deployments
  - nodes
  - daemonsets
  - statefulsets
  - persistentvolumeclaims
  - horizontalpodautoscalers
  - jobs
selfMonitor:
  enabled: true         # Exposes KSM's own Prometheus metrics

Install with your custom values:

helm install kube-state-metrics \
  prometheus-community/kube-state-metrics \
  --namespace monitoring \
  --create-namespace \
  --values ksm-values.yaml

Key Helm Chart Values Reference

ParameterDefaultDescription
replicaCount1Pod replicas. Set ≥2 for HA.
autosharding.enabledfalseHorizontal metric sharding across replicas.
metricLabelsAllowlist[]K8s label keys to include as metric dimensions.
collectorsallResource types to enable collectors for.
namespaces""Namespace filter (empty = all namespaces).
selfMonitor.enabledfalseExpose KSM's own internal metrics.
networkPolicy.enabledfalseCreate a NetworkPolicy for pod access.
podSecurityContextrestrictedPod-level security context defaults.

Namespace-Scoped Installation

To restrict kube-state-metrics to specific namespaces (useful for multi-tenant clusters), use a Role instead of ClusterRole:

helm install kube-state-metrics \
  prometheus-community/kube-state-metrics \
  --namespace monitoring \
  --set namespaces="production\,staging" \
  --set rbac.useClusterRole=false

Upgrading the Helm Chart

helm repo update
helm upgrade kube-state-metrics \
  prometheus-community/kube-state-metrics \
  --namespace monitoring \
  --reuse-values
⚠️
Always check the kube-state-metrics compatibility matrix before upgrading. A new KSM minor version may add new metrics or remove deprecated ones — update your Prometheus alert rules accordingly.

Uninstalling

helm uninstall kube-state-metrics -n monitoring

Alternative: kubectl Direct Install

If Helm is not available, you can deploy kube-state-metrics directly with kubectl. The latest release manifest is published on the GitHub repository:

kubectl apply -f \
  https://github.com/kubernetes/kube-state-metrics/releases/latest/download/kube-state-metrics.yaml

This is suitable for development and testing. For production, the kube-state-metrics Helm chart provides much better configurability and lifecycle management.