如何将K8s对象自定义标签/注解纳入Prometheus指标？（附异常排查）

核心原因 #

kube-state-metrics v2.x版本（包括你使用的v2.5.0）默认不会自动暴露所有K8s资源的自定义标签/注解，目的是避免无限制的标签导致指标集过度膨胀。必须通过启动参数显式声明允许采集的标签或注解规则。

排查与修复步骤 #

1. 确认需要添加的启动参数
   要让kube-state-metrics采集StatefulSet的自定义内容，需添加对应启动参数：

   • 允许所有自定义标签：--metric-labels-allowlist=statefulsets=[*]
   • 允许所有自定义注解：--metric-annotations-allowlist=statefulsets=[*]
   • 若只想匹配特定前缀（比如你的label_开头标签），可以精准配置：--metric-labels-allowlist=statefulsets=[label_*]

2. 检查当前kube-state-metrics配置
   执行命令查看kube-state-metrics的启动命令（假设部署在kube-system命名空间）：

   kubectl get deployment kube-state-metrics -n kube-system -o yaml | grep -A20 "command:"
   

   检查输出中是否包含上述metric-labels-allowlist或metric-annotations-allowlist参数，若无则需要添加。

3. 修改配置并重启实例
   编辑kube-state-metrics的Deployment：

   kubectl edit deployment kube-state-metrics -n kube-system
   

   在容器的command字段中加入所需参数，示例配置片段：

   spec:
     template:
       spec:
         containers:
         - args:
           - /kube-state-metrics
           - --metric-labels-allowlist=statefulsets=[*]
           - --metric-annotations-allowlist=statefulsets=[*]
           # 保留原有其他参数
           image: k8s.gcr.io/kube-state-metrics/kube-state-metrics:v2.5.0
           name: kube-state-metrics
   

   保存退出后，Deployment会自动重启Pod，等待Pod进入Running状态。

4. 验证指标采集结果
   重新执行PromQL查询：

   kube_statefulset_labels{statefulset='testing-labels'}
   

   此时应该能看到自定义标签（如label_STATEFULSET_LABEL="111"、label_network="111"）出现在指标标签中。

内容的提问来源于stack exchange，提问作者Ivan Aracki