如何使用promtool对Kubernetes PrometheusRule清单执行单元测试

当你用promtool test rules测试Kubernetes格式的PrometheusRule清单时，报错是因为promtool仅支持原生Prometheus规则格式（顶层为groups数组），而K8s的PrometheusRule包含apiVersion、kind等额外字段，导致解析失败。这里有两种实用解决办法：

方法1：用yq提取规则核心内容 #

Kubernetes PrometheusRule的实际告警规则都嵌套在spec.groups节点下，我们可以用yq（YAML处理工具）直接提取这部分内容，生成符合promtool要求的纯规则文件：

• 安装yq（通过系统包管理器或官方渠道下载均可）
• 执行提取命令：

  # yq v4版本
  yq e '.spec.groups' my-alert.yaml > pure-alert.yaml
  
  # 如果是yq v3版本，使用这条命令
  yq r my-alert.yaml spec.groups > pure-alert.yaml
  

• 修改你的alert-test.yaml，将引用的my-alert.yaml替换成生成的pure-alert.yaml
• 正常执行测试：promtool test rules alert-test.yaml

方法2：写脚本自动完成提取+测试 #

如果需要频繁测试，可以写个简单的shell脚本，省去手动提取的重复步骤：

#!/bin/bash

# 临时文件存储提取后的纯规则
TEMP_FILE="temp-alert-rules.yaml"

# 提取K8s PrometheusRule中的规则部分
yq e '.spec.groups' my-alert.yaml > $TEMP_FILE

# 执行测试（如果alert-test.yaml的rule_files字段指向临时文件，直接运行即可）
promtool test rules alert-test.yaml

# 清理临时文件
rm $TEMP_FILE

注意：如果你的alert-test.yaml通过rule_files引用规则，要确保里面的路径指向临时文件，也可以在脚本里动态替换alert-test.yaml中的引用内容。

原理说明 #

promtool的test rules子命令设计时只适配原生Prometheus规则文件——这种文件顶层只有groups数组，没有K8s资源清单的额外字段。而Kubernetes的PrometheusRule CRD是遵循K8s资源格式的包装结构，promtool无法识别这些非规则字段，因此会抛出反序列化错误。通过提取spec.groups，我们得到了promtool能解析的纯规则内容，自然就能正常测试了。

内容的提问来源于stack exchange，提问作者Erich Shan