kube-state-metrics:v2.2.3 镜像文档

1. 镜像概述和主要用途

镜像名称：k8s.gcr.io/kube-state-metrics/kube-state-metrics:v2.2.3
概述：该镜像包含 Kubernetes 官方工具 kube-state-metrics 的 v2.2.3 版本。kube-state-metrics 是一个无状态服务，通过监听 Kubernetes API 服务器，生成并暴露集群内对象（如 Pod、Deployment、Service 等）的状态指标，支持 Prometheus 等监控系统抓取，用于集群状态分析、性能监控和告警配置。

2. 核心功能和特性

2.1 核心功能

• Kubernetes 对象指标生成：针对集群内核心对象（Pod、Deployment、ReplicaSet、StatefulSet、DaemonSet、Service、ConfigMap、Secret、Job、CronJob 等）生成状态指标。
• 多维度指标覆盖：包含对象状态（如 Pod 运行/就绪状态）、数量统计（如 Deployment 副本数、可用副本数）、健康状态（如 Node 就绪状态）、标签/注解元数据等维度指标。
• Prometheus 兼容：指标通过 HTTP 接口暴露（默认端口 8080），格式符合 Prometheus 规范，支持直接被 Prometheus 抓取。

2.2 关键特性

• 无状态设计：不存储持久化数据，可水平扩展（通常单实例部署即可满足需求）。
• 指标过滤与定制：支持通过命令行参数过滤需要暴露的指标或对象标签（如 --metric-labels-allowlist）。
• 低资源占用：轻量级服务，对 CPU/内存资源消耗低。
• Kubernetes API 兼容性：兼容 Kubernetes 1.16+ 版本（具体以官方兼容性说明为准）。

3. 使用场景和适用范围

3.1 典型使用场景

• Kubernetes 集群监控：作为 Prometheus 监控栈的核心组件，提供集群对象状态指标。
• 性能与可用性分析：通过指标分析 Deployment 滚动更新状态、Pod 重启频率、Service endpoints 变化等。
• 告警规则配置：基于指标（如 kube_deployment_status_replicas_unavailable）配置 Prometheus Alertmanager 告警。
• 集群资源规划：结合指标（如 kube_pod_container_resource_limits）优化资源分配。

3.2 适用范围

• 环境：Kubernetes 集群（1.16+ 版本，推荐 1.18+）。
• 监控系统：需配合 Prometheus 或兼容 Prometheus 协议的监控系统（如 Thanos、VictoriaMetrics）使用。

4. 详细使用方法和配置说明

4.1 Docker 运行示例

注意：kube-state-metrics 通常在 Kubernetes 集群内部署（通过 InClusterConfig 访问 API 服务器）。以下为 Docker 单机运行示例（需手动挂载 kubeconfig）。

docker run -d \
  --name kube-state-metrics \
  -p 8080:8080 \  # 指标暴露端口  
  -p 8081:8081 \  # 健康检查/指标自身监控端口  
  -v /path/to/kubeconfig:/etc/kubeconfig:ro \  # 挂载本地 kubeconfig（集群外运行时）  
  k8s.gcr.io/kube-state-metrics/kube-state-metrics:v2.2.3 \
  --kubeconfig=/etc/kubeconfig \  # 指定 kubeconfig 路径（集群外运行必填）  
  --port=8080 \  # 指标暴露端口（默认 8080）  
  --telemetry-port=8081  # 自身监控/健康检查端口（默认 8081）  

4.2 Kubernetes 集群内部署示例

4.2.1 Deployment 配置

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 配置）  
      containers:
      - name: kube-state-metrics
        image: k8s.gcr.io/kube-state-metrics/kube-state-metrics:v2.2.3
        ports:
        - containerPort: 8080  # 指标端口  
          name: metrics
        - containerPort: 8081  # 自身监控端口  
          name: telemetry
        args:
        - --port=8080  # 指标暴露端口  
        - --telemetry-port=8081  # 自身监控端口  
        - --metric-labels-allowlist=pods=[*],deployments=[app,env]  # 允许作为指标标签的对象标签（示例）  
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 256Mi

4.2.2 配套 Kubernetes 资源配置

4.2.2.1 Service（暴露指标端口给 Prometheus）

apiVersion: v1
kind: Service
metadata:
  name: kube-state-metrics
  namespace: monitoring
  labels:
    app: kube-state-metrics
spec:
  ports:
  - name: metrics
    port: 8080
    targetPort: metrics
  - name: telemetry
    port: 8081
    targetPort: telemetry
  selector:
    app: kube-state-metrics

4.2.2.2 RBAC 权限配置（必需）

kube-state-metrics 需要访问 Kubernetes API 的权限，需配置 ServiceAccount、ClusterRole 和 ClusterRoleBinding：

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", "services", "endpoints", "namespaces", "configmaps", "secrets", "nodes"]
  verbs: ["list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
  verbs: ["list", "watch"]
- apiGroups: ["batch"]
  resources: ["jobs", "cronjobs"]
  verbs: ["list", "watch"]
- apiGroups: ["autoscaling"]
  resources: ["horizontalpodautoscalers"]
  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

4.3 环境变量说明

4.4 命令行参数说明

5. 常见问题与注意事项

• 权限不足：若启动后日志报 permission denied，需检查 RBAC 权限配置是否完整（参考 4.2.2.2 节）。
• 指标缺失：若某类对象指标未暴露，检查 --resources 或 --metric-allowlist 参数是否过滤了该资源/指标。
• Kubernetes 版本兼容：v2.2.3 兼容 Kubernetes 1.16+，低版本集群可能存在 API 不兼容问题，建议升级集群或使用对应版本的 kube-state-metrics。
• 性能优化：大规模集群（10k+ Pod）建议通过 --namespaces 或 --resources 限制监控范围，减少 API 访问压力。