kube-state-metrics Node 指标详解：14 个 kube_node_* 指标的含义、标签与实现原理

kube-state-metrics Node 指标详解14 个 kube_node_* 指标的含义、标签与实现原理【免费下载链接】kube-state-metricsAdd-on agent to generate and expose cluster-level metrics.项目地址: https://gitcode.com/GitHub_Trending/ku/kube-state-metricskube-state-metrics 通过 List/Watch 集群中的 Node 对象将节点的基础信息、资源容量capacity/allocatable、状态条件、污点、角色等属性转换为 Prometheus 指标。本文完整覆盖kube_node_*全部 14 个指标的名称、类型、标签与稳定性级别并结合 node.go 的源码逐指标解析其生成逻辑、单位换算和 allowlist 控制方式帮助你正确编写 PromQL 查询并理解指标背后的实现细节。一、指标总览以下表格继承自 node-metrics.md是 Node 指标的权威清单。所有指标均为 Gauge 类型Status 列表示指标的稳定性级别STABLE 表示接口承诺稳定EXPERIMENTAL 表示行为可能变化。指标名称类型描述单位标签/tags状态kube_node_annotationsGaugeKubernetes 注解转换为 Prometheus 标签由--metric-annotations-allowlist控制—node、annotation_XXXEXPERIMENTALkube_node_infoGauge集群节点的基础信息—node、kernel_version、os_image、container_runtime_version、kubelet_version、kubeproxy_version已废弃、pod_cidr、provider_id、system_uuid、internal_ipSTABLEkube_node_labelsGaugeKubernetes 标签转换为 Prometheus 标签由--metric-labels-allowlist控制—node、label_XXXSTABLEkube_node_roleGauge节点的角色—node、roleEXPERIMENTALkube_node_spec_pod_cidrsGauge节点的 Pod CIDR 列表—node、pod_cidrEXPERIMENTALkube_node_spec_unschedulableGauge节点是否可被调度新 Pod—nodeSTABLEkube_node_spec_taintGauge节点的污点—node、key、value、effectSTABLEkube_node_status_capacityGauge节点可用资源总量cpucore、memory/ephemeral_storage/hugepages_*/attachable_volumes_*byte、podsintegernode、resource、unitSTABLEkube_node_status_addressesGauge节点地址信息—node、type、addressEXPERIMENTALkube_node_status_allocatableGauge扣除系统守护进程预留后可供 Pod 使用的资源同 capacitynode、resource、unitSTABLEkube_node_status_conditionGauge节点条件状态—node、condition、statusSTABLEkube_node_createdGauge创建时间Unix 时间戳秒nodeSTABLEkube_node_deletion_timestampGauge删除时间Unix 时间戳秒nodeEXPERIMENTAL二、指标如何从 Node 对象生成所有 Node 指标由 internal/store/node.go 中的nodeMetricFamilies()统一注册该函数返回 13 个FamilyGeneratorannotations、created、deletion_timestamp、info、labels、role、spec_pod_cidrs、spec_taint、spec_unschedulable、status_allocatable、status_capacity、status_condition、status_addresses。每个生成器都通过wrapNodeFunc包装它在生成指标后为所有 metric 自动合并node节点名标签对应源码中的descNodeLabelsDefaultLabels []string{node}这解释了为什么上表中每个指标的标签都以node开头。构建入口在 internal/store/builder.go 的buildNodeStores()它把nodeMetricFamilies与按资源名nodes配置的 annotations/labels allowlist 传入集群级 store 构建流程数据源则是 internal/store/node.go 中createNodeListWatch返回的 List/Watch——直接调用kubeClient.CoreV1().Nodes().List/Watch。这意味着 Node 是集群作用域资源kube-state-metrics 需要集群范围的nodes读取/监听权限见 examples/standard/cluster-role.yaml。在启用条件上nodes属于内置可启用的资源列表之一见 pkg/options/resource.go 中的资源名集合即--resources...,nodes,...时才构建 Node store。三、逐个指标解析3.1 kube_node_info节点身份快照由createNodeInfoFamilyGenerator()生成输出单条值为 1 的 metric全部信息放在标签上kernel_version、os_image、container_runtime_version、kubelet_version取自NodeStatus.NodeInfoprovider_id取自Spec.ProviderIDpod_cidr取自Spec.PodCIDR单值字段双栈下只保留主 CIDRsystem_uuid取自Status.NodeInfo.SystemUUIDkubeproxy_version固定输出字符串deprecated——源码中直接硬编码为deprecated因为 kubernetes 已不再在该字段中填充 KubeProxy 版本internal_ip是通过遍历Status.Addresses查找InternalIP类型地址得到的。源码注释明确标注 TODO: remove internal_ip in v3, replaced by kube_node_status_addresses即该标签计划在 v3 中移除建议新查询优先使用kube_node_status_addresses。单测 internal/store/node_test.go 中的期望输出印证了完整形态kube_node_info{container_runtime_versionrkt,kernel_versionkernel,kubelet_versionkubelet,kubeproxy_versiondeprecated,node127.0.0.1,os_imageosimage,pod_cidr172.24.10.0/24,provider_idprovider://i-uniqueid,internal_ip1.2.3.4,system_uuid6a934e21-...} 13.2 kube_node_status_capacity 与 kube_node_status_allocatable资源的单位换算这两个指标由createNodeStatusCapacityFamilyGenerator()/createNodeStatusAllocatableFamilyGenerator()生成遍历Status.Capacity/Status.Allocatable的ResourceList为每种资源输出一条带resource和unit标签的 metric。源码按资源类型分别决定unit标签取值单位常量定义在 pkg/constant/resource_unit.gocpu→core值经convertValueToFloat64从 quantity 转为 float例如3500m会输出3.5memory、storage、ephemeral_storage、hugepages_*、attachable_volumes_*→bytepods→integer其余资源走 default 分支isHugePageResourceName前缀匹配hugepages-、isAttachableVolumeResourceName前缀匹配attachable-volumes-按 byte 输出isExtendedResourceName判定为扩展资源如nvidia.com/gpu且会校验其满足 quota 资源名规则的按integer输出。判定函数见 internal/store/utils.go。两者的语义差别capacity 是节点物理总量allocatable 是 kubelet 扣除系统预留后可供 Pod 调度的量。典型查询是节点资源利用率例如kube_node_status_allocatable{resourcecpu}作为分母与 kubelet/node-exporter 的用量指标配合。3.3 kube_node_status_conditionone-hot 编码的条件状态这是实践中最常用的节点指标之一。createNodeStatusConditionFamilyGenerator()对Status.Conditions中的每个条件调用addConditionMetrics()internal/store/utils.go对true|false|unknown三种status各生成一条 metric实际状态对应值为 1、其余为 0。因此判断节点是否 Ready 的正确写法不是 1单条匹配而是kube_node_status_condition{conditionReady, statustrue} 1源码注释特别说明这是“all-in-one”设计第三方组件如 node-problem-detector会报告自定义条件Kubernetes 未来也可能新增核心条件因此实现上不硬编码条件枚举而是把condition作为标签全量透传。3.4 kube_node_spec_taint 与 kube_node_spec_unschedulabletaint遍历Spec.Taints每个污点输出一条key/value/effect标签、值为 1 的 metric。无污点时该指标族为空。unschedulable直接取Spec.Unschedulable布尔值经boolFloat64转为 1/0单标签 metric。单测中Unschedulable: true的节点输出kube_node_spec_unschedulable{node...} 1。3.5 kube_node_role从标签提取角色createNodeRoleFamilyGenerator()遍历节点标签只保留前缀为node-role.kubernetes.io/的键并把去掉前缀后的部分作为role标签值如master、worker每个角色一条值为 1 的 metric。没有角色标签的节点不产生任何序列。该指标为 EXPERIMENTAL 级别。3.6 kube_node_spec_pod_cidrs面向双栈的 CIDR 列表createNodeSpecPodCIDRFamilyGenerator()遍历Spec.PodCIDRs复数字段每个 CIDR 一条pod_cidr标签序列。源码注释解释其存在意义一个节点每个 IP 族一个 Pod CIDR而kube_node_info的pod_cidr标签只暴露主 CIDR双栈节点的第二 CIDR 只有在这里可见。3.7 kube_node_status_addresses遍历Status.Addresses每个地址输出一条type/address标签、值为 1 的 metrictype取值如InternalIP、ExternalIP、Hostname等。它同时是kube_node_info{internal_ip...}标签的替代方案状态为 EXPERIMENTAL。3.8 kube_node_created 与 kube_node_deletion_timestampkube_node_created取CreationTimestamp的 Unix 秒值仅当时间非零时输出。适合计算节点年龄time() - kube_node_created。kube_node_deletion_timestamp取DeletionTimestamp仅当字段非 nil 且非零值时输出——即只有正在删除处于 terminating 状态的节点才产生该序列。3.9 kube_node_labels 与 kube_node_annotationsallowlist 门控这两个指标默认不暴露。createNodeLabelsGenerator()和createNodeAnnotationsGenerator()在入口处检查 allowlist若对应资源的允许列表为空直接返回空的 metric family否则通过createPrometheusLabelKeysValues(label/annotation, ...)把白名单内的键值对转换为label_XXX/annotation_XXX前缀的 Prometheus 标签。允许列表由两个命令行参数控制定义见 pkg/options/options.go完整参数说明见 cli-arguments.md--metric-annotations-allowlist按资源复数形式指定要暴露的注解键例如nodes[kubernetes.io/team]每个资源可提供单个*允许全部注解但官方警告这有严重的性能影响且通配*仅在列表第一项时生效--metric-labels-allowlist同理控制标签例如nodes[k8s-label-1,app]。四、PromQL 实战示例基于上述指标几个常见查询# 节点可调度状态 kube_node_spec_unschedulable 0 # CPU 可分配总量核 kube_node_status_allocatable{resourcecpu, unitcore} # 内存容量字节 kube_node_status_capacity{resourcememory, unitbyte} # 节点 Ready 且可调度 kube_node_status_condition{conditionReady, statustrue} 1 and on(node) kube_node_spec_unschedulable 0 # 节点年龄秒 time() - kube_node_created # 节点角色 kube_node_role{rolemaster}五、小结Node 指标族的实现集中在 internal/store/node.go行为由 internal/store/node_test.go 的单测逐一锁定含“未设置字段被跳过”的边界情况。阅读源码时注意三点其一资源类指标必须结合resourceunit双标签解释数值其二condition 类指标是 one-hot 编码查询时要固定status标签其三labels/annotations 指标默认关闭必须显式配置 allowlist 才会出现在/metrics端点上。【免费下载链接】kube-state-metricsAdd-on agent to generate and expose cluster-level metrics.项目地址: https://gitcode.com/GitHub_Trending/ku/kube-state-metrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考