当前位置：首页 > news >正文

【Prometheus】kube-state-metrics 的详细说明

news 2025/7/1 20:00:25

以下是关于 kube-state-metrics 的详细说明，包括其工作原理、部署 YAML 示例以及采集的核心指标。

一、kube-state-metrics 的作用

kube-state-metrics 是一个 Kubernetes 组件，用于将 Kubernetes 集群中各种资源对象（如 Pod、Deployment、Node、Service 等）的状态转换为 Prometheus 格式的指标。
它与 kube-apiserver 交互，不监控集群的健康状态，而是专注于资源对象的配置和状态信息，例如：
• Pod 的运行状态（Pending/Running/Failed）。
• Deployment 的副本数、更新状态。
• Node 的资源请求与限制。
• PersistentVolume 的容量和状态。

二、部署 YAML 示例

以下是一个典型的 kube-state-metrics 部署配置（包含 Deployment、Service 和 ServiceMonitor）：

# kube-state-metrics-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kube-state-metrics
  namespace: monitoring
  labels:
    app.kubernetes.io/name: kube-state-metrics
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: kube-state-metrics
  template:
    metadata:
      labels:
        app.kubernetes.io/name: kube-state-metrics
    spec:
      serviceAccountName: kube-state-metrics
      containers:
      - name: kube-state-metrics
        image: registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.10.0
        ports:
        - name: http-metrics
          containerPort: 8080
        resources:
          limits:
            memory: 512Mi
            cpu: 500m
          requests:
            memory: 256Mi
            cpu: 100m
---
# kube-state-metrics-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: kube-state-metrics
  namespace: monitoring
  labels:
    app.kubernetes.io/name: kube-state-metrics
spec:
  ports:
  - name: http-metrics
    port: 8080
    targetPort: http-metrics
  selector:
    app.kubernetes.io/name: kube-state-metrics
---
# 使用 Prometheus Operator 的 ServiceMonitor
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: kube-state-metrics
  namespace: monitoring
spec:
  endpoints:
  - port: http-metrics
    interval: 30s
  selector:
    matchLabels:
      app.kubernetes.io/name: kube-state-metrics
  namespaceSelector:
    matchNames:
    - monitoring
---
# RBAC 权限
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: ["nodes", "pods", "services", "namespaces", "persistentvolumes", "persistentvolumeclaims"]
  verbs: ["list", "watch"]
- apiGroups: ["apps"]
  resources: ["daemonsets", "deployments", "statefulsets", "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
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kube-state-metrics
subjects:
- kind: ServiceAccount
  name: kube-state-metrics
  namespace: monitoring

三、工作原理

监听 Kubernetes API
kube-state-metrics 通过 Kubernetes 的 Watch 机制监听 API 服务器，实时获取资源对象的变更事件（如创建、更新、删除）。
生成指标
根据监听到的事件，生成与资源状态相关的 Prometheus 指标。例如：
• 当 Pod 状态变为 Running 时，更新 kube_pod_status_phase{phase="Running"} 指标。
• 当 Deployment 的副本数变化时，更新 kube_deployment_status_replicas 指标。
暴露 HTTP 端点
默认在 8080 端口暴露 /metrics 端点，供 Prometheus 抓取。
高可用性
支持多副本部署，避免单点故障。所有副本独立工作，指标数据最终一致。

四、核心采集指标

以下是 kube-state-metrics 生成的主要指标类别及示例：

1. Pod 相关指标

• kube_pod_status_phase{phase="Pending|Running|Succeeded|Failed|Unknown"}
Pod 当前阶段的状态。
• kube_pod_container_status_restarts_total
Pod 容器的重启次数。
• kube_pod_info{node="<node-name>", namespace="<namespace>"}
Pod 的元信息（所属节点、命名空间等）。

2. Deployment 相关指标

• kube_deployment_status_replicas{deployment="<name>"}
Deployment 的期望副本数、实际副本数、可用副本数。
• kube_deployment_spec_strategy_rollingupdate_max_unavailable
RollingUpdate 策略中最大不可用副本数。

3. Node 相关指标

• kube_node_status_allocatable{resource="cpu|memory"}
Node 的可分配资源（CPU、内存）。
• kube_node_status_capacity{resource="cpu|memory"}
Node 的总资源容量。
• kube_node_labels{label_<name>="<value>"}
Node 的标签信息。

4. Service 相关指标

• kube_service_spec_type{type="ClusterIP|NodePort|LoadBalancer"}
Service 的类型。
• kube_service_labels{service="<name>"}
Service 的标签。

5. PersistentVolume 相关指标

• kube_persistentvolume_status_phase{phase="Available|Bound|Released|Failed"}
PersistentVolume 的状态。
• kube_persistentvolume_capacity_bytes
PersistentVolume 的容量。

6. 其他资源指标

• DaemonSet: kube_daemonset_status_number_ready
• StatefulSet: kube_statefulset_replicas
• Job: kube_job_status_failed
• CronJob: kube_cronjob_next_schedule_time

五、指标应用场景

资源使用监控
通过 kube_pod_container_resource_requests 和 kube_pod_container_resource_limits 分析容器资源请求和限制的合理性。

# 查看 CPU 请求超配的 Pod
sum(kube_pod_container_resource_requests{resource="cpu"}) by (pod) > sum(kube_pod_container_resource_limits{resource="cpu"}) by (pod)

异常状态告警
当 Pod 处于 Failed 或 Pending 状态时触发告警：
```
kube_pod_status_phase{phase=~"Failed|Pending"} == 1
```

配置合规性检查
检测未设置资源限制的 Deployment：

kube_deployment_spec_replicas unless kube_deployment_spec_strategy_rollingupdate_max_unavailable

六、注意事项

RBAC 权限
确保 ServiceAccount 具有足够的权限访问目标资源（参考示例中的 ClusterRole）。
资源限制
在高规模集群中，kube-state-metrics 可能消耗较多内存，需合理设置 resources.limits。
指标过滤
使用 --metric-labels-allowlist 或 --metric-annotations-allowlist 参数控制生成的指标标签，减少数据量。
版本兼容性
确保 kube-state-metrics 版本与 Kubernetes 集群版本兼容（官方兼容性矩阵）。