Datadog has first-class support for kube-state-metrics. The Datadog Agent includes a built-in kubernetes_state check that scrapes kube-state-metrics and forwards its data to Datadog as Kubernetes state metrics. This guide covers two approaches: the built-in check (recommended) and a custom OpenMetrics scraper.

ℹ️
Datadog + kube-state-metrics integration requires the Datadog Agent running as a DaemonSet in your cluster. The Agent's kubernetes_state check discovers and scrapes kube-state-metrics automatically in most configurations.

Method 1 — Built-in Datadog Kubernetes State Check (Recommended)

If you install the Datadog Agent via its Helm chart, the datadog-kube-state-metrics integration is enabled by default. The Agent Helm chart also deploys kube-state-metrics as a dependency:

helm repo add datadog https://helm.datadoghq.com
helm repo update

helm install datadog-agent datadog/datadog \
  --namespace monitoring \
  --set datadog.apiKey=<YOUR_API_KEY> \
  --set datadog.site=datadoghq.com \
  --set clusterAgent.enabled=true \
  --set datadog.kubeStateMetricsEnabled=true \
  --set datadog.kubeStateMetricsCore.enabled=true

The kubeStateMetricsCore check uses a built-in KSM-compatible collector inside the Cluster Agent — no separate kube-state-metrics Deployment needed.

Method 2 — External kube-state-metrics + OpenMetrics Check

If you already run kube-state-metrics independently, configure the Datadog Agent to scrape it via the OpenMetrics check:

apiVersion: v1
kind: ConfigMap
metadata:
  name: datadog-agent-confd
  namespace: monitoring
data:
  openmetrics.yaml: |
    instances:
      - openmetrics_endpoint: http://kube-state-metrics.monitoring.svc:8080/metrics
        namespace: kubernetes_state
        metrics:
          - kube_pod_.*
          - kube_deployment_.*
          - kube_node_.*
          - kube_persistentvolumeclaim_.*
          - kube_horizontalpodautoscaler_.*
        honor_labels: true
        send_distribution_sums_as_monotonic: true

kube-state-metrics Datadog Metrics Mapping

Datadog prefixes kube-state-metrics with kubernetes_state. in its metrics namespace. Common mappings:

kube-state-metrics metricDatadog metric
kube_pod_status_phasekubernetes_state.pod.status_phase
kube_deployment_spec_replicaskubernetes_state.deployment.replicas_desired
kube_node_status_conditionkubernetes_state.node.status
kube_pod_container_status_restarts_totalkubernetes_state.container.restarts
kube_persistentvolumeclaim_status_phasekubernetes_state.persistentvolumeclaim.status
kube_horizontalpodautoscaler_status_current_replicaskubernetes_state.hpa.current_replicas

Verifying Datadog kube-state-metrics Integration

# Check the kubernetes_state check status
kubectl exec -it <datadog-agent-pod> -n monitoring -- \
  agent check kubernetes_state

# Or use the Agent status command
kubectl exec -it <datadog-agent-pod> -n monitoring -- \
  agent status | grep kubernetes_state
💡
In Datadog's Kubernetes integration, metrics scraped from kube-state-metrics appear in the Containers → Kubernetes section of the Datadog UI. The pre-built "Kubernetes Overview" dashboard uses these metrics for pod, node, and deployment health panels.

Datadog Monitors from kube-state-metrics Data

Create Datadog monitors that alert on Kubernetes object state derived from kube-state-metrics:

# Pod crash looping monitor
avg(last_15m):
  sum:kubernetes_state.container.restarts{*}.as_rate() > 0.5

# Deployment replicas mismatch
max(last_5m):
  kubernetes_state.deployment.replicas_desired{*} -
  kubernetes_state.deployment.replicas_available{*} > 0

# Node not ready
min(last_5m):
  kubernetes_state.node.status{status:schedulable} < 1

kube-state-metrics Datadog Cost Optimisation

kube-state-metrics can generate thousands of metrics in large clusters. To reduce Datadog custom metric volume: