kube-state-metrics（简称 KSM）是一款监听 Kubernetes API Server 并将各类资源对象状态转换为 Prometheus 可识别指标的工具。它专注于暴露业务层面的元数据信息，例如 Deployment 的副本期望数量、Pod 的当前运行阶段、容器重启次数、Job 执行状态等。需要明确的是，KSM 本身不保留任何历史数据，仅提供即时指标供 Prometheus 抓取并长期存储。

官方资源参考：

• GitHub 仓库：https://github.com/kubernetes/kube-state-metrics
• 容器镜像：https://hub.docker.com/r/bitnami/kube-state-metrics
• 指标说明文档：https://github.com/kubernetes/kube-state-metrics/tree/main/docs

部署 kube-state-metrics

以下示例展示如何通过 Deployment 和 Service 将 KSM 部署到 monitoring 命名空间。注意 KSM 版本需与 Kubernetes 集群版本兼容，具体对应关系请查阅官方文档。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ksm-deploy
  namespace: monitoring
spec:
  replicas: 1
  selector:
    matchLabels:
      component: ksm
  template:
    metadata:
      labels:
        component: ksm
    spec:
      serviceAccountName: monitor
      containers:
      - name: exporter
        image: registry-vpc.cn-shanghai.aliyuncs.com/zdbl-base/kube-state-metrics:2.11.0
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: ksm-svc
  namespace: monitoring
  labels:
    component: ksm
  annotations:
    prometheus.io/scrape: "true"
spec:
  type: NodePort
  selector:
    component: ksm
  ports:
  - port: 8080
    targetPort: 8080
    nodePort: 31666

应用配置并检查运行状态：

kubectl apply -f ksm-deployment.yaml
kubectl get pods -n monitoring -l component=ksm

验证指标端点可访问后，即可配置 Prometheus 采集。

Prometheus 采集配置

在 Prometheus 配置文件中新增 job，指向 KSM 暴露的 NodePort 地址：

scrape_configs:
  - job_name: "ksm-collector"
    static_configs:
      - targets: ["192.168.100.131:31666"]

重载配置使变更生效：

curl -X POST http://127.0.0.1:9090/-/reload

Grafana 可视化配置

社区提供了多个适用于 kube-state-metrics 的 Grafana 仪表板模板，常用 ID 包括 13332、13824、14518。以 ID 13332 为例导入时，需特别注意模板底部数据源配置项，确保与当前环境保持一致。

核心指标查询参考

节点维度

指标用途	PromQL 表达式
节点 CPU 总量	kube_node_status_capacity_cpu_cores
Pod CPU 请求总量（按节点聚合）	sum(kube_pod_container_resource_requests{resource="cpu"})
Pod CPU 限制总量（按节点聚合）	sum(kube_pod_container_resource_limits{resource="cpu"}))
容器 CPU 使用率（按节点聚合）	sum(rate(container_cpu_usage_seconds_total{id="/"}[2m]))
CPU 请求占比	100 * sum(kube_pod_container_resource_requests{resource="cpu"}) / sum(kube_node_status_allocatable{resource="cpu"})
节点内存总量	kube_node_status_allocatable_memory_bytes
节点磁盘总量	sum(container_fs_limit_bytes{device=~"/dev/.*",id="/"})
节点磁盘使用量	sum(container_fs_usage_bytes{device=~"/dev/.*",id="/"})
节点状态条件	kube_node_status_condition
节点污点信息	kube_node_spec_taint

工作负载维度

资源类型	关键指标
Pod 状态	kube_pod_status_phase{phase="Running"} — 运行中 Pod 数量
	kube_pod_status_phase{phase="Pending"} — 等待中 Pod 数量
	kube_pod_status_phase{phase="Failed"} — 失败 Pod 数量
	kube_pod_container_status_restarts_total — 容器累计重启次数
容器状态	kube_pod_container_status_running — 运行中容器数
	kube_pod_container_status_waiting == 1 — 等待状态及原因
	kube_pod_container_status_terminated == 1 — 终止状态及原因
Deployment	kube_deployment_status_replicas — 期望副本数
	kube_deployment_status_replicas_available — 可用副本数
	kube_deployment_status_replicas_unavailable — 不可用副本数
	kube_deployment_spec_replicas — 目标副本数
DaemonSet	kube_daemonset_status_number_available — 可用实例数
	kube_daemonset_status_number_unavailable — 不可用实例数
	kube_daemonset_status_number_ready — Ready 实例数
	kube_daemonset_status_number_misscheduled — 错误调度实例数
	kube_daemonset_status_current_number_scheduled — 当前调度实例数
StatefulSet	kube_statefulset_status_replicas — 当前副本数
	kube_statefulset_replicas — 期望副本数
	kube_statefulset_status_replicas_updated — 已更新副本数
	kube_statefulset_status_replicas_current — 实际副本数
Job	kube_job_status_active — 运行中 Pod 数
	kube_job_status_succeeded — 成功 Pod 数
	kube_job_status_failed — 失败 Pod 数
	kube_job_complete / kube_job_failed — 完成/失败状态
CronJob	kube_cronjob_status_active — 活跃 Job 数
	kube_cronjob_spec_suspend == 1 — 是否被挂起
	kube_cronjob_next_schedule_time — 下次调度时间

存储维度

指标用途	PromQL 表达式
PV 容量	kube_persistentvolume_capacity_bytes
PV 状态	kube_persistentvolume_status_phase
PVC 请求容量	kube_persistentvolumeclaim_resource_requests_storage_bytes
PVC 状态	kube_persistentvolumeclaim_status_phase

命名空间资源统计

count(kube_pod_info) by (namespace)           # 各命名空间 Pod 数量
count(kube_pod_container_info) by (namespace) # 各命名空间容器数量
count(kube_service_info) by (namespace)       # 各命名空间 Service 数量
count(kube_secret_info) by (namespace)        # 各命名空间 Secret 数量
count(kube_configmap_info) by (namespace)     # 各命名空间 ConfigMap 数量