kube-state-metrics是Kubernetes集群的“状态翻译官”，它不采集CPU、内存等运行时指标，而是监听API Server，将Deployment、Pod等资源对象的状态（如副本数、运行阶段）转化为Prometheus可抓取的结构化指标。
kube-state-metrics 不是采集 CPU、内存等运行时指标的工具，它只监听 Kubernetes API，把资源对象的状态（比如 kube_deployment_status_replicas_available、kube_pod_status_phase）翻译成 Prometheus 能抓的 HTTP 指标。部署失败，90% 是权限或网络问题，不是镜像拉不下来。
为什么 kube-state-metrics 启动后没指标？
最常见原因是 RBAC 权限缺失或错配。它需要 list 和 watch 大量资源类型，但很多教程给的 ClusterRole 里漏了 jobs、cronjobs 或 horizontalpodautoscalers —— 尤其在较新 Kubernetes 版本（v1.25+）中，batch/v1 的 jobs 已是默认版本，旧配置仍写 batch/v1beta1 就会静默失败。
- 检查日志：
kubectl logs -n，重点看是否有deploy/kube-state-metrics failed to list jobs.batch类错误 - 确认
ClusterRole中apiGroups包含["batch"]且resources明确列出["jobs", "cronjobs"] - 若用
apps/v1部署 Deployment，ClusterRole必须包含apps组，不能只留extensions（该组已在 v1.22+ 废弃）
kube-state-metrics 的 Service 怎么暴露才安全？
它本身不处理请求，只暴露 /metrics 端点供 Prometheus 主动拉取，所以 Service 类型选 ClusterIP 最合理。强行用 NodePort 或 LoadBalancer 反而增加攻击面，还可能因未设 NetworkPolicy 导致指标泄露。
- Service 的
selector必须严格匹配 Deployment 的pod labels（如app: kube-state-metrics），否则 endpoints 为空 - 确保 Prometheus 的
scrape_configs中 target 正确指向该 Service 的 DNS 名，例如kube-state-metrics.monitoring.svc.cluster.local:8080 - 如果 Prometheus 在不同 namespace，需确认 ServiceAccount 有跨 namespace 访问权限（通常不需要，DNS 可解析）
镜像和版本怎么选才不踩坑？
官方镜像已从 k8s.gcr.io 迁移到 registry.k8s.io，但国内环境直接拉取仍常超时。别硬改 image 字段，优先用镜像代理或提前导入。
- 推荐镜像：
registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.12.0（适配 Kubernetes v1.26–v1.28） - 避免用
:latest标签——它可能突然升级到不兼容新版 API 的版本 - 若集群启用了 PodSecurityPolicy 或 Pod Security Admission（PSA），需在 Deployment 中显式设置
securityContext.runAsNonRoot: true和runAsUser: 65534
真正难调的不是部署命令本身，而是确认它到底有没有拿到你关心的资源状态。比如想监控 StatefulSet，就 curl 一下它的 metrics 接口：kubectl port-forward -n monitoring svc/kube-state-metrics 8080 && curl localhost:8080/metrics | grep kube_statefulset —— 如果没输出，说明要么 RBAC 没给 statefulsets 权限，要么你的集群里真没这个资源。
