kube-state-metrics Ingress 指标详解kube_ingress_* 指标、Allowlist 配置与源码实现【免费下载链接】kube-state-metricsAdd-on agent to generate and expose cluster-level metrics.项目地址: https://gitcode.com/GitHub_Trending/ku/kube-state-metrics本文围绕 kube-state-metrics 暴露的 Kubernetes Ingress 指标体系展开完整覆盖kube_ingress_info、kube_ingress_path、kube_ingress_tls等 7 个kube_ingress_*指标的标签结构与稳定性状态并结合仓库中 ingress 指标实现、测试用例 与 E2E 清单 深入解析指标生成逻辑、--metric-labels-allowlist/--metric-annotations-allowlist的配置机制以及 List/Watch 订阅链路帮助读者掌握如何查询、配置与验证 Ingress 指标。Ingress 指标总览kube-state-metrics 针对networking.k8s.io/v1的 Ingress 资源暴露 7 个 Gauge 类型指标。各指标的名称、标签labels/tags与稳定性状态如下源自 官方指标文档Metric nameMetric typeDescriptionLabels/tagsStatuskube_ingress_annotationsGaugeKubernetes annotations converted to Prometheus labels controlled via --metric-annotations-allowlistingress、namespace、annotation_INGRESS_ANNOTATIONEXPERIMENTALkube_ingress_infoGauge—ingress、namespace、ingressclass未设置时为_defaultSTABLEkube_ingress_labelsGaugeKubernetes labels converted to Prometheus labels controlled via --metric-labels-allowlistingress、namespace、label_INGRESS_LABELSTABLEkube_ingress_createdGauge—ingress、namespaceSTABLEkube_ingress_metadata_resource_versionGauge—ingress、namespaceEXPERIMENTALkube_ingress_pathGauge—ingress、namespace、host、path、path_typeService Backend 时附service_name、service_portResource Backend 时附resource_api_group、resource_kind、resource_nameSTABLEkube_ingress_tlsGauge—ingress、namespace、tls_host、secretSTABLE两个要点需要提前明确namespace与ingress是所有Ingress 指标共有的基础标签由统一的包装函数注入见下文“公共标签”一节kube_ingress_labels与kube_ingress_annotations默认不暴露任何系列必须通过 allowlist 参数显式开启这与 Ingress 对象本身是否默认开启是两回事。各指标详解与取值逻辑kube_ingress_infoIngress 基本信息与 class 判定该指标恒输出1核心价值在于ingressclass标签。从 ingressMetricFamilies 的实现 看class 的判定优先级为若 Ingress 设置了注解kubernetes.io/ingress.class旧版 Ingress class 机制取其值否则取spec.ingressClassName字段两者皆无时回退为_default。注意这里注解覆盖字段的优先级——当二者同时存在时以注解为准以兼容旧式控制器配置。测试用例ingress6Spec.IngressClassName test与ingress7注解kubernetes.io/ingress.class: test分别验证了后两种情况期望输出为kube_ingress_info{namespacens6,ingressingress6,ingressclasstest} 1 kube_ingress_info{namespacens7,ingressingress7,ingressclasstest} 1对于未指定 class 的对象如ingress1输出ingressclass_default这为编写 Prometheus 告警时区分“显式指定 class”与“走默认 class”的 Ingress 提供了依据。kube_ingress_created 与 kube_ingress_metadata_resource_versionkube_ingress_createdUnix 创建时间戳取自metadata.creationTimestamp。实现上仅当时间戳非零值时才输出系列ingress.go#L121-L134测试中1501569018输出为科学计数法1.501569018e09。kube_ingress_metadata_resource_versionEXPERIMENTAL将metadata.resourceVersion转为数值。从 ingress_test.go 的用例 可以确认一个实现细节resourceVersion 为纯数字时输出对应数值123456→123456000000→0而非数字的占位值如abcdef则不产生该指标的系列。该指标通常用于配合 resourceVersion 监控对象是否发生过变更。kube_ingress_path路由规则与后端解构这是信息量最大的指标将spec.rules[].http.paths[]展平为按“host path”为粒度的系列。从 ingress.go#L147-L186 的实现看它遍历每条规则的每条路径根据后端类型输出两套不同的标签Service Backend绝大多数场景kube_ingress_path{namespacens4,ingressingress4,hostsomehost,path/somepath,path_typeExact,service_namesomeservice,service_port1234} 1Resource BackendKubernetes 内部资源后端kube_ingress_path{namespacens4,ingressingress4,hostsomehost,path/somepath2,path_type,resource_api_group,resource_kindsomekind,resource_namesomename} 1几个值得注意的行为path_type取自path.pathType为Exact、Prefix或ImplementationSpecific字段未设置时为空串service_port只取port.number若后端使用具名端口则输出0resource_api_group在未设置时输出空串仅解析rule.HTTP ! nil的规则只有 Host、没有 HTTP 路径块的规则测试用例中的somehost2不会产生任何kube_ingress_path系列。kube_ingress_tlsTLS 主机与证书 Secret遍历spec.tls[]对每个tls.hosts[]主机各输出一条系列secret标签为该 TLS 条目关联的 Secret 名称。测试用例ingress5的配置两个主机共享一个 Secret产生两条系列kube_ingress_tls{namespacens5,ingressingress5,tls_hostsomehost1,secretsomesecret} 1 kube_ingress_tls{namespacens5,ingressingress5,tls_hostsomehost2,secretsomesecret} 1该指标适合与 Secret 相关指标做 join用于排查“TLS 主机已声明但对应 Secret 缺失”一类问题kube-state-metrics 本身只报告对象声明不校验证书有效性。kube_ingress_labels 与 kube_ingress_annotationsallowlist 受控暴露这两个指标把 Ingress 自身的 Kubernetes labels / annotations 转写为 Prometheus 标签是默认关闭的allowlist 为空时返回空 Family见 ingress.go#L77-L114。开启方式与标签转换规则如下配置方式完整参数说明见 CLI 参数文档--metric-labels-allowlistingresses[app,env] --metric-annotations-allowlistingresses[ingress.kubernetes.io/rewrite-target]allowlist 采用“资源名复数 键列表”的格式ingresses即 Ingress 对应的资源名。参数帮助文本中说明了两类通配行为全通配*只能放在列表第一项表示允许该资源的所有键参数文档明确提示这样做“有严重的性能影响”部分通配如team-*可出现在列表任意位置按模式匹配键名。转换实现位于 createPrometheusLabelKeysValues精确键直接查表含通配符的项编译为正则带缓存做匹配。最终经kubeMapToPrometheusLabels将键转成合法 Prometheus 标签名——从单测期望输出可见app.k8s.io/owner被转换为标签annotation_app_k8s_io_owner点号、斜杠等替换为下划线值为注解原值kube_ingress_annotations{annotation_app_k8s_io_ownerfoo,namespacens1,ingressingress1} 1kube_ingress_labels同理前缀为label_。基数风险提示标签型指标会随每个 Ingress 的键值组合放大时间序列数量这也是该项目将kube_ingress_annotations标记为 EXPERIMENTAL 并强制 allowlist 的原因。生产环境建议只放行少量稳定键如团队标识避免使用*。公共标签namespace 与 ingress 的统一注入每个指标生成函数本身只负责业务标签如ingressclass、host、path公共的namespace、ingress标签由 wrapIngressFunc 统一合并它以descIngressLabelsDefaultLabels [namespace, ingress]为默认标签前缀通过mergeKeyValues把ingress.Namespace、ingress.Name拼接到每条系列的标签最前面。这解释了为什么所有测试期望输出中都固定以namespace...,ingress...开头。实际输出示例综合 TestIngressStore 各用例的期望输出文件为 internal/store/ingress_test.go一个带路径与 TLS 的 Ingress 采集结果大致如下含指标头部# HELP kube_ingress_created [STABLE] Unix creation timestamp # HELP kube_ingress_info [STABLE] Information about ingress. # HELP kube_ingress_path [STABLE] Ingress host, paths and backend service information. # HELP kube_ingress_tls [STABLE] Ingress TLS host and secret information. # TYPE kube_ingress_created gauge # TYPE kube_ingress_info gauge # TYPE kube_ingress_path gauge # TYPE kube_ingress_tls gauge kube_ingress_info{namespacens2,ingressingress2,ingressclass_default} 1 kube_ingress_created{namespacens2,ingressingress2} 1.501569018e09 kube_ingress_metadata_resource_version{namespacens2,ingressingress2} 123456可以看到 HELP 文本中的[STABLE]标记与指标稳定性状态一一对应kube_ingress_annotations的 HELP 则没有该标记ALPHA 状态。运行配置资源开关与命名空间过滤资源开关ingresses位于 DefaultResources 默认集合中因此--resources缺省值已包含 Ingress无需额外开启若显式指定--resources需自行带上ingresses默认值完整列表见 cli-arguments.md。命名空间过滤通过--namespace参数限定采集的命名空间。从 createIngressListWatch 实现看namespace 与 fieldSelector 会被同时注入到NetworkingV1().Ingresses(ns).List/Watch的调用中即过滤发生在 API 请求层而非本地过滤。store 构建链路Ingress 指标的注册入口是 Builder.buildIngressStoresfunc (b *Builder) buildIngressStores() []cache.Store { return b.buildStoresFunc(ingressMetricFamilies(b.allowAnnotationsList[ingresses], b.allowLabelsList[ingresses]), networkingv1.Ingress{}, createIngressListWatch, b.useAPIServerCache, b.objectLimit) }注意 allowlist 是按资源名ingresses从全局解析结果中取出的这印证了上节“--metric-labels-allowlistingresses[...]”的键名必须为复数资源名。buildStoresFunc会依据useAPIServerCache与objectLimit决定使用 API Server Watch Cache 还是直接 List/Watch并支持按对象数量上限分片采集对应 examples/ 目录 中 deployment/daemonset 分片部署方案。测试与验证仓库提供了两个层次的验证入口单元测试TestIngressStore 覆盖 7 个用例——默认 class、显式 class、注解 class、Service/Resource 双后端路径、多主机 TLS、标签/注解 allowlist、非数字 resourceVersion每个用例都断言完整的指标输出文本是核对指标行为最直接的依据E2E 测试tests/manifests/ingress.yaml 定义了一个真实清单example-ingress含/apple、/banana两条 Prefix 路径及注解ingress.kubernetes.io/rewrite-target: /E2E 框架将其 apply 到集群后对实际/metrics输出做校验见 tests/e2e 测试。阅读该清单可直观理解kube_ingress_path与kube_ingress_annotations的输出若配置--metric-annotations-allowlistingresses[ingress.kubernetes.io/rewrite-target]将得到形如kube_ingress_annotations{annotation_ingress_kubernetes_io_rewrite_target/,...} 1的系列。小结与参考查询 Ingress 拓扑时优先组合kube_ingress_infoclass 维度与kube_ingress_pathhost/path → 服务后端的映射kube_ingress_tls补充证书侧信息。标签/注解转写指标默认关闭开启时务必使用精确键或受限通配控制时间序列基数。行为细节以源码与测试为准class 判定优先级、resourceVersion 非数字不落系列、空 Host 规则不产 path 系列等均可在 internal/store/ingress.go 与 internal/store/ingress_test.go 中逐行核对。参考路径指标文档docs/metrics/service/ingress-metrics.md指标实现internal/store/ingress.go标签转换工具internal/store/utils.gostore 构建internal/store/builder.go默认资源集合pkg/options/resource.goCLI 参数docs/developer/cli-arguments.mdE2E 清单tests/manifests/ingress.yaml【免费下载链接】kube-state-metricsAdd-on agent to generate and expose cluster-level metrics.项目地址: https://gitcode.com/GitHub_Trending/ku/kube-state-metrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考