kube-state-metrics 中 VolumeAttachment 指标详解：从指标清单到源码实现

kube-state-metrics 中 VolumeAttachment 指标详解从指标清单到源码实现【免费下载链接】kube-state-metricsAdd-on agent to generate and expose cluster-level metrics.项目地址: https://gitcode.com/GitHub_Trending/ku/kube-state-metricskube-state-metrics 通过内置的volumeattachments资源将 Kubernetesstorage.k8s.io/v1VolumeAttachment 对象转化为一组 Prometheus 指标用于监控集群中持久卷的挂载状态哪个 PV 被哪个 CSI attacher 挂载到哪个节点、是否处于已挂载状态、挂载元数据等。本文以官方指标文档 volumeattachment-metrics.md 为核心完整梳理这 6 个kube_volumeattachment_*指标的含义、标签体系与状态并结合 源码实现 与 单元测试 深入讲解每个指标的生成逻辑、启用方式CLI 参数与 RBAC以及可复现的测试样例输出。1. VolumeAttachment 指标总览VolumeAttachment 是集群级对象由 Kubernetes 存储控制面创建描述某个持久卷源通常是 PersistentVolume被挂载到某个节点上这一事实由对应的 CSI attacherspec.attacher负责实际的挂载与卸载操作。kube-state-metrics 共为 VolumeAttachment 暴露 6 个指标全部为 Gauge 类型稳定性等级均为 EXPERIMENTAL源码中对应basemetrics.ALPHA指标名类型描述标签状态kube_volumeattachment_infoGaugeVolumeAttachment 基本信息volumeattachment、attacher、nodeEXPERIMENTALkube_volumeattachment_createdGauge创建时间戳volumeattachmentEXPERIMENTALkube_volumeattachment_labelsGaugeKubernetes labels 转换为 Prometheus labels受--metric-labels-allowlist控制volumeattachment、label_VOLUMEATTACHMENT_LABELEXPERIMENTALkube_volumeattachment_spec_source_persistentvolumeGaugePersistentVolume 源引用volumeattachment、volumenameEXPERIMENTALkube_volumeattachment_status_attachedGauge是否已挂载volumeattachmentEXPERIMENTALkube_volumeattachment_status_attachment_metadataGauge挂载元数据volumeattachment、metadata_METADATA_KEYEXPERIMENTAL以下各节逐一说明并给出源码级别的证据。2. 各指标的含义与生成逻辑源码级解析所有指标的生成逻辑集中在 internal/store/volumeattachment.go 中的volumeAttachmentMetricFamilies变量每个指标由一个generator.NewFamilyGeneratorWithStability构造。逐条对应如下。2.1 kube_volumeattachment_info携带attacher和node两个标签值恒为 1用于描述哪个 attacher 把卷挂载到了哪个节点这一核心关系。从源码实现看internal/store/volumeattachment.go#L59-L76*generator.NewFamilyGeneratorWithStability( kube_volumeattachment_info, Information about volumeattachment., metric.Gauge, basemetrics.ALPHA, , wrapVolumeAttachmentFunc(func(va *storagev1.VolumeAttachment) *metric.Family { return metric.Family{ Metrics: []*metric.Metric{ { LabelKeys: []string{attacher, node}, LabelValues: []string{va.Spec.Attacher, va.Spec.NodeName}, Value: 1, }, }, } }), ),attacher取自va.Spec.Attacher如cinder.csi.openstack.orgnode取自va.Spec.NodeName。2.2 kube_volumeattachment_created输出 VolumeAttachment 的 Unix 创建时间戳。源码中对CreationTimestamp做了零值保护internal/store/volumeattachment.go#L77-L94若va.CreationTimestamp.IsZero()为真则返回空MetricFamily即不输出样本否则输出float64(va.CreationTimestamp.Unix())。2.3 kube_volumeattachment_labels将对象的 Kubernetes labels 转换为 Prometheus labelslabel_前缀但受--metric-labels-allowlist命令行参数控制——只有被允许列表命中的 label 才会被输出。该机制在 internal/store/utils.go 的createPrometheusLabelKeysValues中实现支持全通配符*仅可作为第一项与部分通配符模式匹配生成的 label 名会经过SanitizeLabelNametoSnakeCase清洗如DevicePath→metadata_device_path并对同名冲突追加_conflictN后缀mapToPrometheusLabelsinternal/store/utils.go#L85-L129。注意descVolumeAttachmentLabelsDefaultLabels定义为[]string{volumeattachment}internal/store/volumeattachment.go#L37表示该资源默认只保证输出volumeattachment基础标签其余 label 需通过 allowlist 放行。2.4 kube_volumeattachment_spec_source_persistentvolume当spec.source.persistentVolumeName非空时输出一个volumenamepersistentvolume-name标签、值为 1 的样本用于建立 VolumeAttachment 与其源 PersistentVolume 之间的关联方便在 PromQL 中与其他 PV 相关指标做 join。源码见 internal/store/volumeattachment.go#L95-L115。2.5 kube_volumeattachment_status_attached输出status.attached的布尔值true 为 1false 为 0。这是判断卷是否已实际挂载到节点的关键指标。源码中直接调用工具函数boolFloat64(va.Status.Attached)internal/store/volumeattachment.go#L116-L133boolFloat64定义于 internal/store/utils.go#L58-L63。2.6 kube_volumeattachment_status_attachment_metadata将status.attachmentMetadata键值对转换为metadata_key前缀的 Prometheus labels值恒为 1。CSI 驱动常借此回传挂载细节如块设备的DevicePath。转换复用mapToPrometheusLabels(va.Status.AttachmentMetadata, metadata)internal/store/volumeattachment.go#L134-L153。3. 公共标签 volumeattachment 的注入机制每个指标都带volumeattachmentvolumeattachment-name这一公共标签它不是在各指标内部重复编写的而是由包装函数统一注入func wrapVolumeAttachmentFunc(f func(*storagev1.VolumeAttachment) *metric.Family) func(interface{}) *metric.Family { return func(obj interface{}) *metric.Family { va : obj.(*storagev1.VolumeAttachment) metricFamily : f(va) for _, m : range metricFamily.Metrics { m.LabelKeys, m.LabelValues mergeKeyValues(descVolumeAttachmentLabelsDefaultLabels, []string{va.Name}, m.LabelKeys, m.LabelValues) } return metricFamily } }见 internal/store/volumeattachment.go#L156-L168。mergeKeyValues将基础标签对(volumeattachment, va.Name)合并到每条样本的标签键值中这解释了为什么文档表格中每个指标都含volumeattachment标签。4. 数据来源与资源注册4.1 List/Watch 数据源VolumeAttachment 的 List/Watch 通过createVolumeAttachmentListWatch建立internal/store/volumeattachment.go#L170-L179func createVolumeAttachmentListWatch(kubeClient clientset.Interface, _ string, _ string) cache.ListerWatcher { return cache.ListWatch{ ListFunc: func(opts metav1.ListOptions) (runtime.Object, error) { return kubeClient.StorageV1().VolumeAttachments().List(context.TODO(), opts) }, WatchFunc: func(opts metav1.ListOptions) (watch.Interface, error) { return kubeClient.StorageV1().VolumeAttachments().Watch(context.TODO(), opts) }, } }即直接从 Kubernetes API Server 的storage.k8s.iov1 卷挂载资源获取并持续监听变更指标反映的是 Informer 缓存中的最新状态。4.2 资源启用开关volumeattachments默认在 DefaultResources 资源集中即默认启用docs/developer/cli-arguments.md 中--resources参数的默认值列表也包含volumeattachments。若只启用部分资源例如--resourcesnodes,pods则 VolumeAttachment 指标不会暴露同时其 RBAC 也可以相应裁剪。资源到 store 的映射注册在 internal/store/builder.go#L390volumeattachments: func(b *Builder) []cache.Store { return b.buildVolumeAttachmentStores() }构建走集群级 store 路径buildClusterScopedStoresinternal/store/builder.go#L554-L556因为 VolumeAttachment 是集群级对象。4.3 所需 RBAC 权限标准部署清单 examples/standard/cluster-role.yaml 中为storage.k8s.io组的storageclasses与volumeattachments资源授予list、watch两个动词。分片部署examples/deploymentsharding/cluster-role.yaml、examples/daemonsetsharding/cluster-role.yaml、examples/autosharding/cluster-role.yaml同样包含该权限。若集群中不存在 VolumeAttachment 对象或权限被裁剪对应指标将无样本。5. 测试用例指标输出的真实样例单元测试 internal/store/volumeattachment_test.go 构造了一个贴近生产形态的 VolumeAttachment 对象可直观看到 6 个指标的输出形态。测试输入internal/store/volumeattachment_test.go#L48-L70metadata: generation: 2 name: csi-5ff16a1ad085261021e21c6cb3a6defb979a8794f25a4f90f6285664cff37224 labels: app: foobar spec: attacher: cinder.csi.openstack.org nodeName: node1 source: persistentVolumeName: pvc-44f6ff3f-ba9b-49c4-9b95-8b01c4bd4bab status: attached: true attachmentMetadata: DevicePath: /dev/sdd对应断言的 Prometheus 文本输出internal/store/volumeattachment_test.go#L71-L77kube_volumeattachment_info{attachercinder.csi.openstack.org,nodenode1,volumeattachmentcsi-5ff16a1ad085261021e21c6cb3a6defb979a8794f25a4f90f6285664cff37224} 1 kube_volumeattachment_labels{label_appfoobar,volumeattachmentcsi-5ff16a1ad085261021e21c6cb3a6defb979a8794f25a4f90f6285664cff37224} 1 kube_volumeattachment_spec_source_persistentvolume{volumeattachmentcsi-5ff16a1ad085261021e21c6cb3a6defb979a8794f25a4f90f6285664cff37224,volumenamepvc-44f6ff3f-ba9b-49c4-9b95-8b01c4bd4bab} 1 kube_volumeattachment_status_attached{volumeattachmentcsi-5ff16a1ad085261021e21c6cb3a6defb979a8794f25a4f90f6285664cff37224} 1 kube_volumeattachment_status_attachment_metadata{metadata_device_path/dev/sdd,volumeattachmentcsi-5ff16a1ad085261021e21c6cb3a6defb979a8794f25a4f90f6285664cff37224} 1几个可验证的细节kube_volumeattachment_labels输出了label_appfoobar说明该测试场景下 label 放行生效实际部署中若未配置--metric-labels-allowlist放行app该标签不会出现在输出中DevicePath经清洗后变为 snake_case 的metadata_device_pathkube_volumeattachment_created在该用例中因未设置CreationTimestamp而未产生样本与 2.2 节的零值保护逻辑一致但仍出现在# HELP/# TYPE头中。端到端测试清单 tests/manifests/volumeattachment.yaml 给出了最小 VolumeAttachment 对象attacher: attacher、nodeName: kind、source.persistentVolumeName: persistentvolume供 e2e 场景如 RBAC 校验使用。6. 实用查询思路基于上述指标与标签可构造若干典型的 PromQL 查询场景以指标语义为基础按节点统计已挂载卷数量sum(kube_volumeattachment_status_attached) by (node)配合kube_volumeattachment_info的node标签找出未挂载成功status.attached false的挂载请求kube_volumeattachment_status_attached 0通常意味着 CSI attacher 侧挂载失败或正在处理中将 VolumeAttachment 关联到 PersistentVolume 指标两指标分别携带volumenameVolumeAttachment 侧与 PV 名称标签可用于 join 分析挂载链路结合kube_volumeattachment_created与kube_volumeattachment_status_attached 0可推断长时间未完成挂载的异常对象创建时间较早且 attached 为 0。7. 小结VolumeAttachment 的 6 个指标均为 Gauge、EXPERIMENTAL 状态公共标签为volumeattachment由 internal/store/volumeattachment.go 中的wrapVolumeAttachmentFunc统一注入资源默认启用见 pkg/options/resource.go 的DefaultResources需要storage.k8s.io/volumeattachments的list/watchRBAC 权限见 examples/standard/cluster-role.yamlkube_volumeattachment_labels的输出受--metric-labels-allowlist控制kube_volumeattachment_status_attachment_metadata的键名会经 snake_case 清洗完整的指标清单见 docs/metrics/storage/volumeattachment-metrics.md存储层实现与测试分别见 internal/store/volumeattachment.go 与 internal/store/volumeattachment_test.go可作为指标行为的第一手依据。【免费下载链接】kube-state-metricsAdd-on agent to generate and expose cluster-level metrics.项目地址: https://gitcode.com/GitHub_Trending/ku/kube-state-metrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考