dbscale/kube-state-metrics

kube-state-metrics 镜像文档

镜像概述

本镜像为 k8s.gcr.io/kube-state-metrics/kube-state-metrics 的克隆版本，功能与原镜像完全一致。它是一个用于收集Kubernetes集群对象状态指标的组件，通过监听Kubernetes API服务器，提取集群中各类资源对象（如Pod、Deployment、StatefulSet、Service、ConfigMap等）的状态信息，并将这些指标以Prometheus兼容的格式暴露，供监控系统（如Prometheus、Grafana）采集和分析，帮助用户实时掌握集群运行状态。

核心功能与特性

核心功能

• 指标收集：采集Kubernetes集群中多种核心对象的状态指标，包括但不限于：

  • 工作负载资源：Pod、Deployment、StatefulSet、DaemonSet、Job、CronJob
  • 服务发现资源：Service、Ingress、Endpoint
  • 配置资源：ConfigMap、Secret
  • 存储资源：PersistentVolume、PersistentVolumeClaim
  • 节点资源：Node

• 指标暴露：通过HTTP接口（默认端口8080）以Prometheus文本格式暴露指标，支持监控系统直接拉取。

特性

• 轻量级：组件本身资源占用低，适合在集群中作为基础监控组件部署。
• 可配置：支持通过命令行参数或配置文件自定义指标集合、过滤命名空间、设置标签等。
• 与Prometheus生态兼容：原生支持Prometheus的指标格式，可直接集成到Prometheus监控流水线中。
• 无状态：不存储持久化数据，仅依赖Kubernetes API获取实时状态，便于水平扩展。

使用场景与适用范围

适用场景

• Kubernetes集群监控：作为基础监控组件，为集群运维提供核心对象的状态指标，如Pod运行状态、Deployment副本数、Service endpoints健康状态等。
• 性能分析与故障排查：结合Prometheus和Grafana，构建集群状态仪表盘，实时分析资源使用情况、识别异常状态（如Pod重启、Deployment扩缩容失败等）。
• 告警规则配置：基于采集的指标配置告警规则（如Pod长时间未就绪、PV可用空间不足等），实现主动运维。

适用范围

• 所有Kubernetes集群环境（包括自建集群、云厂商托管集群等）。
• 需要对Kubernetes对象状态进行精细化监控的场景。
• 已采用Prometheus作为监控系统的技术栈。

使用方法与配置说明

基本使用（Docker Run）

前提条件

• 容器需能够访问Kubernetes API服务器（可通过挂载kubeconfig文件或使用集群内ServiceAccount）。
• 需具备访问Kubernetes对象的权限（建议使用RBAC配置最小权限）。

示例命令

bash
docker run -d \
  --name kube-state-metrics \
  -p 8080:8080 \
  -v /path/to/kubeconfig:/etc/kubeconfig \
  --env KUBECONFIG=/etc/kubeconfig \
  your-registry/kube-state-metrics:latest

核心配置参数

kube-state-metrics支持通过命令行参数自定义行为，常用参数如下：

带参数示例

bash
docker run -d \
  --name kube-state-metrics \
  -p 8080:8080 \
  -v /path/to/kubeconfig:/etc/kubeconfig \
  your-registry/kube-state-metrics:latest \
  --port=8080 \
  --namespace=default,kube-system \
  --metric-labels-allowlist=pods:app,deployments:env \
  --resources=pods,deployments,services

Docker Compose 配置示例

yaml
version: '3'
services:
  kube-state-metrics:
    image: your-registry/kube-state-metrics:latest
    container_name: kube-state-metrics
    ports:
      - "8080:8080"
      - "8081:8081"
    volumes:
      - /path/to/kubeconfig:/etc/kubeconfig
    command:
      - --port=8080
      - --telemetry-port=8081
      - --namespace=default
      - --kubeconfig=/etc/kubeconfig
    restart: always

指标验证

启动容器后，可通过访问 http://<容器IP>:8080/metrics 验证指标是否正常暴露，例如：

bash
curl http://localhost:8080/metrics | grep kube_pod_status_phase

预期输出类似：

kube_pod_status_phase{namespace="default",phase="Running",pod="example-pod"} 1
kube_pod_status_phase{namespace="default",phase="Pending",pod="another-pod"} 1

注意事项

• 权限配置：在Kubernetes集群内部署时，需为kube-state-metrics配置RBAC权限，确保其能够读取集群对象信息（建议使用官方提供的RBAC配置文件）。
• 版本兼容性：需确保镜像版本与Kubernetes集群版本兼容（参考官方文档的版本兼容性矩阵）。
• 资源限制：根据集群规模合理配置CPU和内存资源限制，避免影响集群性能。