kube-state-metrics Documentation:
Full Metrics List (v2)

This is the official kube-state-metrics documentation companion — covering the most important metrics exposed in kube-state-metrics v2, their labels, value semantics, and PromQL query examples. For the interactive full metrics list, see the Metrics Reference page.

Pod Metrics

kube_pod_info

The kube_pod_info metric exposes static information about each pod. It always has value 1 — it acts as an info metric where all the useful data is in the labels.

# Labels: namespace, pod, uid, node, host_ip, pod_ip, created_by_kind, created_by_name
kube_pod_info{namespace="default", pod="nginx-abc123", node="worker-1"} 1

Common use: join with resource metrics to add pod metadata. The node label lets you correlate pod state with node-exporter data.

kube_pod_status_phase

The kube_pod_status_phase metric exposes the pod phase as a label with a boolean value. Only the active phase has value 1; others are 0.

# Phases: Pending, Running, Succeeded, Failed, Unknown
kube_pod_status_phase{phase="Running"} == 1

# Count pods per phase
count by (phase) (kube_pod_status_phase == 1)

kube_pod_status_ready

Indicates whether the pod's Ready condition is true. A pod can be Running but not Ready (e.g., readiness probe failing).

kube_pod_status_ready{condition="true"} == 1

# Pods not ready
kube_pod_status_ready{condition="false"} == 1

kube_pod_labels

The kube_pod_labels metric exposes Kubernetes pod labels as Prometheus label dimensions (with label_ prefix). Requires opt-in via --metric-labels-allowlist=pods=[app,version].

# kube_pod_labels metric with label_app exposed
kube_pod_labels{label_app="nginx", namespace="production"} 1

# Join with phase metric using label_replace
kube_pod_status_phase * on(pod, namespace) group_left(label_app)
  kube_pod_labels

kube_pod_owner

The kube_pod_owner metric exposes the owning controller of each pod — ReplicaSet, DaemonSet, StatefulSet, or Job.

# Find pods owned by DaemonSets
kube_pod_owner{owner_kind="DaemonSet"}

# Label: owner_kind, owner_name, owner_is_controller

kube_pod_created & kube_pod_start_time

Two time-based metrics for pod lifecycle analysis:

# Pod age in minutes
(time() - kube_pod_created) / 60

# Time since pod started running
(time() - kube_pod_start_time) / 60

kube_pod_container_status_restarts_total

Tracks container restart counts — critical for detecting crash-looping containers.

# Containers with more than 5 restarts
kube_pod_container_status_restarts_total > 5

# Rate of restarts (crash looping detection)
increase(kube_pod_container_status_restarts_total[15m]) > 0

Node Metrics

kube_node_labels

The kube_node_labels metric exposes Kubernetes node labels as metric dimensions. Requires --metric-labels-allowlist=nodes=[node-role.kubernetes.io/control-plane,topology.kubernetes.io/zone].

# Nodes by availability zone
kube_node_labels{label_topology_kubernetes_io_zone!=""}

kube_node_status_condition

Exposes node conditions — Ready, DiskPressure, MemoryPressure, PIDPressure, NetworkUnavailable.

# Nodes not ready
kube_node_status_condition{condition="Ready",status="true"} == 0

# Nodes under memory pressure
kube_node_status_condition{condition="MemoryPressure",status="true"} == 1

kube_node_spec_taint

Exposes node taints — useful for detecting scheduling restrictions and maintenance windows.

kube_node_spec_taint{effect="NoSchedule"}
# Labels: node, key, value, effect

Deployment Metrics

# Deployment availability ratio
kube_deployment_status_replicas_available / kube_deployment_spec_replicas

# Deployments not fully available
kube_deployment_spec_replicas != kube_deployment_status_replicas_available

PersistentVolumeClaim Metrics

# All PVCs not Bound
kube_persistentvolumeclaim_status_phase{phase!="Bound"} == 1

# PVC to pod mapping — the kube_pod_spec_volumes_persistentvolumeclaims_info metric
kube_pod_spec_volumes_persistentvolumeclaims_info{persistentvolumeclaim="my-pvc"}

Custom Resource State Metrics

kube-state-metrics v2 supports custom CRD metrics via the CustomResourceStateMetrics feature. This allows you to expose metrics from your own Kubernetes custom resources without writing any Go code.

kind: CustomResourceStateMetrics
spec:
  resources:
    - groupVersionKind:
        group: mycompany.io
        version: v1
        kind: MyApp
      metrics:
        - name: myapp_ready
          each:
            type: Gauge
            gauge:
              path: [status, readyReplicas]

This generates kube_customresource_myapp_ready{namespace="...",name="..."}. See the Custom Resources docs for full syntax reference.

Labels & Annotations Allow-lists

By default, kube-state-metrics omits Kubernetes labels from all metrics to prevent high cardinality. Enable specific labels with:

--metric-labels-allowlist=\
  pods=[app,version,environment],\
  deployments=[app,team],\
  nodes=[topology.kubernetes.io/zone]

After enabling, the kube_pod_labels metric will include label_app, label_version, and label_environment dimensions.