kube-state-metrics Docker镜像文档

镜像概述和主要用途

kube-state-metrics是一个开源工具，作为Docker镜像提供，用于从Kubernetes API服务器采集各类资源对象（Pod、Deployment、StatefulSet、Service、Node、ConfigMap等）的状态指标，并将这些指标以Prometheus可抓取的格式暴露在HTTP端点上。该镜像旨在帮助用户实时监控Kubernetes集群的资源状态、运行健康度和配置信息，为Prometheus等监控系统提供数据源，支持集群状态分析、告警配置和性能优化。

核心功能和特性

核心功能

• 多资源类型支持：采集Kubernetes核心资源（Pod、Node、Service）及扩展资源（Deployment、StatefulSet、DaemonSet、Job、CronJob等）的状态指标。
• 实时指标更新：通过监听Kubernetes API的资源事件（创建、更新、删除），实时更新指标数据。
• Prometheus兼容：指标以Prometheus文本格式暴露，支持Prometheus自动发现和抓取。
• 无状态设计：镜像本身无持久化存储需求，可通过水平扩展提高可用性。

关键特性

• 轻量化：镜像体积小，资源占用低，适合在资源受限环境部署。
• 可配置性：支持通过命令行参数过滤指标（允许/禁止特定指标）、限制监控命名空间等。
• 丰富指标集：提供资源状态（如Pod运行状态、Deployment副本数）、配置信息（如标签、注解）、关系数据（如Pod与Node的关联）等多维度指标。
• 自身监控：暴露内部运行指标（如API请求 latency、指标生成耗时），便于监控工具自身健康度。

使用场景和适用范围

典型使用场景

• Kubernetes集群监控：实时监控Pod、Deployment等资源的运行状态（如就绪状态、重启次数、副本可用性）。
• 告警规则配置：基于指标（如kube_deployment_status_replicas_unavailable）配置告警，及时发现集群异常。
• 资源优化分析：通过指标（如kube_pod_container_resource_requests_cpu_cores）分析资源分配与实际使用的匹配度。
• 配置合规检查：监控ConfigMap、Secret的创建/更新状态，确保配置一致性。

适用范围

• 所有版本兼容的Kubernetes集群（需匹配kube-state-metrics版本与Kubernetes版本，具体参考官方兼容性矩阵）。
• 开发、测试、生产环境的Kubernetes集群监控需求。
• 需要通过Prometheus+Grafana构建监控面板的场景。

详细使用方法和配置说明

前置条件

• 运行环境需能访问Kubernetes API服务器（集群内部署时通过Service Account，集群外部署时需提供kubeconfig）。
• 需配置RBAC权限（ClusterRole、ClusterRoleBinding），允许kube-state-metrics访问Kubernetes API（如get、list、watch资源权限）。

基本部署示例（Kubernetes环境）

kube-state-metrics通常在Kubernetes集群内通过Deployment部署，以下是基础部署清单示例：

# kube-state-metrics-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kube-state-metrics
  namespace: monitoring
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kube-state-metrics
  template:
    metadata:
      labels:
        app: kube-state-metrics
    spec:
      serviceAccountName: kube-state-metrics  # 需提前创建带RBAC权限的ServiceAccount
      containers:
      - name: kube-state-metrics
        image: bitnami/kube-state-metrics:latest  # 或其他官方维护的镜像（如prometheuscommunity/kube-state-metrics）
        ports:
        - containerPort: 8080  # 指标暴露端口
        - containerPort: 8081  # 自身监控指标端口
        args:
        - --port=8080  # 指标端口
        - --telemetry-port=8081  # 自身监控端口
        - --namespace=default  # 可选，限制监控单个命名空间（默认监控所有）
        - --metric-allowlist=kube_pod_.*  # 可选，只暴露Pod相关指标

配套RBAC配置示例：

# kube-state-metrics-rbac.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: kube-state-metrics
  namespace: monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kube-state-metrics
rules:
- apiGroups: [""]
  resources: ["pods", "nodes", "services", "endpoints", "configmaps", "secrets"]
  verbs: ["list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "statefulsets", "daemonsets", "replicasets"]
  verbs: ["list", "watch"]
- apiGroups: ["batch"]
  resources: ["jobs", "cronjobs"]
  verbs: ["list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kube-state-metrics
subjects:
- kind: ServiceAccount
  name: kube-state-metrics
  namespace: monitoring
roleRef:
  kind: ClusterRole
  name: kube-state-metrics
  apiGroup: rbac.authorization.k8s.io

关键配置参数

kube-state-metrics通过命令行参数配置，常用参数如下：

指标访问

部署后，可通过容器的--port（默认8080）访问指标，例如：

• 集群内访问：http://<pod-ip>:8080/metrics
• 通过Service暴露：创建Service指向kube-state-metrics的8080端口，Prometheus可通过Service DNS（如kube-state-metrics.monitoring.svc:8080）抓取指标。

注意事项

• 版本兼容性：需确保kube-state-metrics版本与Kubernetes集群版本兼容（例如kube-state-metrics v2.10.0兼容Kubernetes v1.24+），具体参考官方兼容性文档。
• 权限配置：必须为kube-state-metrics配置足够的RBAC权限，否则无法正常采集指标（常见错误：API访问被拒绝）。
• 性能影响：大规模集群（如 thousands of Pods）建议配置指标过滤（--metric-allowlist），减少指标数量，降低资源占用。