kube-state-metrics IngressClass 指标详解：kube_ingressclass_* 的标签体系、白名单配置与源码实现
发布时间：2026/9/17 4:39:51 作者：尧图编辑部 阅读量：1,286
kube-state-metrics IngressClass 指标详解kube_ingressclass_* 的标签体系、白名单配置与源码实现【免费下载链接】kube-state-metricsAdd-on agent to generate and expose cluster-level metrics.项目地址: https://gitcode.com/GitHub_Trending/ku/kube-state-metrics本文以 kube-state-metrics 的 IngressClass 指标文档为主体系统讲解kube_ingressclass_info、kube_ingressclass_created、kube_ingressclass_labels与kube_ingressclass_annotations这 4 个 Gauge 指标的标签结构、默认行为与启用方式并结合 internal/store/ingressclass.go 的源码实现、internal/store/builder.go 的资源构建流程以及 internal/store/ingressclass_test.go 的真实测试输出帮助你既会配置、又懂原理并能验证这些指标在 Prometheus 中的实际表现。指标总览IngressClass 是 Kubernetesnetworking.k8s.io/v1API 组下的集群级cluster-scoped资源用于声明某类 Ingress 由哪个控制器实现。kube-state-metrics 将其对象状态转换为 4 个 Gauge 指标当前文档中全部标记为EXPERIMENTAL状态与源码中使用的basemetrics.ALPHA稳定性等级一致见 internal/store/ingressclass.go。Metric nameMetric typeDescriptionLabels/tagsStatuskube_ingressclass_annotationsGaugeKubernetes annotations converted to Prometheus labels controlled via --metric-annotations-allowlistingressclassingressclass-nameannotation_INGRESSCLASS_ANNOTATIONINGRESSCLASS_ANNOTATIONEXPERIMENTALkube_ingressclass_infoGaugeingressclassingressclass-namecontrolleringress-controller-nameEXPERIMENTALkube_ingressclass_labelsGaugeKubernetes labels converted to Prometheus labels controlled via --metric-labels-allowlistingressclassingressclass-namelabel_INGRESSCLASS_LABELINGRESSCLASS_LABELEXPERIMENTALkube_ingressclass_createdGaugeingressclassingressclass-nameEXPERIMENTAL需要特别说明的一点所有 IngressClass 指标都强制携带ingressclass标签值为 IngressClass 对象名。这并非可选项而是源码中的硬编码默认标签descIngressClassLabelsDefaultLabels []string{ingressclass}internal/store/ingressclass.go由wrapIngressClassFunc在生成任何指标前统一注入见下文源码小节。逐指标解析kube_ingressclass_infoIngressClass 基本信息该指标的核心价值在于暴露spec.controller字段——IngressClass 的必填字段指明处理该类的 Ingress 控制器名称如ingressclass.kubernetes.io生态中的具体控制器标识。从源码看internal/store/ingressclass.go*generator.NewFamilyGeneratorWithStability( kube_ingressclass_info, Information about ingressclass., metric.Gauge, basemetrics.ALPHA, , wrapIngressClassFunc(func(s *networkingv1.IngressClass) *metric.Family { m : metric.Metric{ LabelKeys: []string{controller}, LabelValues: []string{s.Spec.Controller}, Value: 1, } return metric.Family{Metrics: []*metric.Metric{m}} }), ),每个 IngressClass 对象产生一条值恒为1的样本标签为ingressclass对象名controllerspec.controller。典型输出如下取自 internal/store/ingressclass_test.go 的测试断言# HELP kube_ingressclass_info Information about ingressclass. # TYPE kube_ingressclass_info gauge kube_ingressclass_info{ingressclasstest_ingressclass-info,controllercontroller} 1配合仓库中的示例清单 tests/manifests/ingressclass.yamlcontroller: example-ingress/controller可以推断出实际集群中该指标会形如kube_ingressclass_info{ingressclassexample-ingressclass,controllerexample-ingress/controller} 1。在 PromQL 中可用count by (controller) (kube_ingressclass_info)统计各 Ingress 控制器被多少个 IngressClass 引用。kube_ingressclass_created创建时间戳值域为 Unix 创建时间戳秒用于计算 IngressClass 的年龄age。源码实现internal/store/ingressclass.go有一个防御性分支ms : []*metric.Metric{} if !s.CreationTimestamp.IsZero() { ms append(ms, metric.Metric{ Value: float64(s.CreationTimestamp.Unix()), }) }即当metadata.creationTimestamp为零值时不产生样本避免输出0这种误导性的时间戳。测试用例internal/store/ingressclass_test.go中1501569018被渲染为kube_ingressclass_created{ingressclasstest_kube_ingressclass-created} 1.501569018e09kube_ingressclass_labels 与 kube_ingressclass_annotations受控的对象标签/注解透传指标这两个指标的作用是把 IngressClass 对象自身的 Kubernetes labels / annotations 转换成 Prometheus 标签从而支持按业务元数据如环境、团队切分查询。它们共用同一套生成逻辑前缀分别为label_和annotation_internal/store/ingressclass.go// annotations 分支labels 分支结构相同前缀为 label wrapIngressClassFunc(func(s *networkingv1.IngressClass) *metric.Family { if len(allowAnnotationsList) 0 { return metric.Family{} // 白名单为空时不暴露任何样本 } annotationKeys, annotationValues : createPrometheusLabelKeysValues(annotation, s.Annotations, allowAnnotationsList) return metric.Family{ Metrics: []*metric.Metric{ { LabelKeys: annotationKeys, LabelValues: annotationValues, Value: 1, }, }, } }),由此得到三条关键行为约定默认不暴露--metric-labels-allowlist/--metric-annotations-allowlist未配置对应资源条目时len(allowList) 0指标家族为空Prometheus 端完全看不到这两条指标。这是防止标签基数cardinality爆炸的默认安全策略。配置后只透传白名单内的键键名会做 Prometheus 标签合法化转换如ingressclass.kubernetes.io/is-default-class→annotation_ingressclass_kubernetes_io_is_default_class。ingressclass名称标签始终保留即使白名单只放行部分键。测试中的实际效果internal/store/ingressclass_test.go白名单仅包含ingressclass.kubernetes.io/is-default-class对象同时带有 labelfoobar时输出只有注解样本、且未被放行的 label 不会出现# HELP kube_ingressclass_annotations Kubernetes annotations converted to Prometheus labels. # TYPE kube_ingressclass_annotations gauge kube_ingressclass_annotations{ingressclasstest_ingressclass-labels,annotation_ingressclass_kubernetes_io_is_default_classtrue} 1构建链路从资源名到 Store理解这些指标如何被点亮需要看 internal/store/builder.go 中的两处注册// 资源名 → Store 构建函数的分发表第 363 行附近 ingressclasses: func(b *Builder) []cache.Store { return b.buildIngressClassStores() }, // 第 578-579 行 func (b *Builder) buildIngressClassStores() []cache.Store { return b.buildClusterScopedStores( ingressClassMetricFamilies(b.allowAnnotationsList[ingressclasses], b.allowLabelsList[ingressclasses]), networkingv1.IngressClass{}, createIngressClassListWatch, b.useAPIServerCache, b.objectLimit) }从中可以确认几个实现事实启用的资源名是复数形式ingressclasses即--resourcesingressclasses或通过资源发现自动启用才会构建该 Store白名单按资源名复数形式键入allowAnnotationsList[ingressclasses]/allowLabelsList[ingressclasses]与 CLI 参数的plural form要求一致IngressClass 走cluster-scoped构建路径buildClusterScopedStores因此没有 namespace 过滤与 namespace 标签这与指标表中不出现namespace标签相吻合List/Watch 由 createIngressClassListWatch 实现直接调用kubeClient.NetworkingV1().IngressClasses()的List与Watch并支持useAPIServerCacheAPI Server 缓存与objectLimit对象数量限制这两个运行时选项。白名单参数详解--metric-labels-allowlist / --metric-annotations-allowlist这两个 CLI 参数是 IngressClass 标签类指标的唯一开关完整定义见 docs/developer/cli-arguments.md。对 IngressClass 的典型用法参数值中资源名用复数形式# 只放行指定的注解键以 IngressClass 常见的默认类注解为例 --metric-annotations-allowlistingressclasses[ingressclass.kubernetes.io/is-default-class] # 放行指定的 label 键多个资源用逗号分隔 --metric-labels-allowlistingressclasses[app,environment],namespaces[kubernetes.io/team]参数语义要点与 docs/developer/cli-arguments.md 的参数说明一致默认不暴露labels/annotations 指标每个资源可以用单个*放行任意键但官方明确提示这有严重的性能影响severe performance implications全通配*只有作为列表第一个条目时才生效出现在其他位置的*会被忽略资源名本身也可以用*表示全部资源。通配匹配的底层实现位于 internal/store/utils.go 的createPrometheusLabelKeysValues精确键走 map 直接命中无需正则含部分通配符partial wildcard的条目会被expandWildcard展开为正则表达式*→.*其余字面量经QuoteMeta转义并通过cachedCompileAllowListPattern做编译结果缓存避免每次对象事件都重复编译通配符数量超过上限options.MaxPartialWildcardsPerLabel的条目会被直接拒绝并记录告警fail-closed防止*key*这类过度通配的条目被截断后错误匹配。从源码结构看这意味着白名单配置在安全与性能之间有明确的工程约束精确键最便宜部分通配次之全通配则因基数风险被刻意限制。实测验证路径仓库提供了一条可本地复现的验证链路单元测试 internal/store/ingressclass_test.goTestIngressClassStore覆盖了info、created、annotations含白名单放行与未放行键的对比三类断言是核对输入对象 → 输出指标文本最直接的依据示例对象 tests/manifests/ingressclass.yaml定义了带ingressclass.kubernetes.io/is-default-class: true注解、controller: example-ingress/controller的 IngressClass与测试数据形态一致运行期验证在启用ingressclasses资源并配置白名单后抓取/metrics应能看到上表 4 个指标家族且labels/annotations家族仅在白名单非空时出现。小结与适用边界IngressClass 的 4 个指标当前均为 EXPERIMENTAL/ALPHA标签集可能随版本演进变化用于生产告警或 SLO 时应以当前仓库的 docs/metrics/service/ingressclass-metrics.md 与源码为准kube_ingressclass_info与kube_ingressclass_created零配置即可用kube_ingressclass_labels/kube_ingressclass_annotations必须通过--metric-labels-allowlist/--metric-annotations-allowlist以ingressclasses[...]形式显式放行IngressClass 是集群级资源指标不含 namespace 维度且受--use-apiserver-cache、对象限制等运行时选项影响具体语义可参考 docs/developer/cli-arguments.md 与 internal/store/builder.go。【免费下载链接】kube-state-metricsAdd-on agent to generate and expose cluster-level metrics.项目地址: https://gitcode.com/GitHub_Trending/ku/kube-state-metrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 