Prometheus Operator 终极故障排查指南：7个常见问题与解决方案

【免费下载链接】prometheus-operator 项目地址: https://gitcode.com/gh_mirrors/pro/prometheus-operator

监控 Kubernetes 集群时，Prometheus Operator 是最强大的工具之一，但遇到问题时往往令人头疼。本文将深入分析 Prometheus Operator 的常见故障场景，并提供实用的排查方法和解决方案，帮助你快速恢复监控系统。🚀

1. CRD 应用失败：metadata.annotations 过长错误

当更新 CRD 时，可能会遇到 metadata.annotations: Too long 错误：

The CustomResourceDefinition "prometheuses.monitoring.coreos.com" is invalid: 
metadata.annotations: Too long: must have at most 262144 bytes

解决方案：使用服务器端应用

kubectl apply --server-side --force-conflicts -f $MANIFESTS

2. ServiceMonitor 配置问题排查

ServiceMonitor 是最常见的故障点之一。检查 ServiceMonitor 是否被 Prometheus 正确识别：

kubectl -n monitoring get secret prometheus-k8s -ojson | \
  jq -r '.data["prometheus.yaml.gz"]' | base64 -d | gunzip | \
  grep "your-service-monitor"

3. 端口配置错误：名称 vs 数字

正确配置（使用端口名称）：

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
spec:
  endpoints:
  - port: web  # 使用端口名称

错误配置（使用端口数字）：

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
spec:
  endpoints:
  - port: "8080"  # 错误：应该使用端口名称

4. RBAC 权限问题（特别是在 GKE）

在 GKE 上创建 ClusterRole 时可能遇到权限错误，需要先为当前用户授予 cluster-admin 权限：

# 获取当前 Google 身份
gcloud info | grep Account

# 授予 cluster-admin 权限
kubectl create clusterrolebinding myname-cluster-admin-binding \
  --clusterrole=cluster-admin --user=myname@example.org

5. kubelet 指标 403 禁止访问错误

当 Prometheus 无法获取 kubelet 指标时，需要检查 webhook 配置：

# 更新 kubelet 服务配置
KUBEADM_SYSTEMD_CONF=/etc/systemd/system/kubelet.service.d/10-kubeadm.conf
sed -e "/cadvisor-port=0/d" -i "$KUBEADM_SYSTEMD_CONF"
sed -e "s/--authorization-mode=Webhook/--authentication-token-webhook=true --authorization-mode=Webhook/" -i "$KUBEADM_SYSTEMD_CONF"
systemctl daemon-reload
systemctl restart kubelet

6. Pod 陷入终止循环

如果 Prometheus 或 Alertmanager Pod 不断重启并陷入终止循环，通常表明多个 Operator 实例在管理同一资源：

kubectl get pods --all-namespaces | grep 'prom.*operator'

检查各 Operator 日志，确认是否有多个实例在管理相同的资源。

7. 日志分析与调试技巧

查看 Operator 日志是排查问题的关键：

# 查看 Operator 日志
kubectl logs -n monitoring deployment/prometheus-operator

# 查看 Prometheus 配置
kubectl exec -n monitoring prometheus-k8s-0 -c prometheus -- cat /etc/prometheus/prometheus.yml

# 检查配置重新加载器日志
kubectl logs -n monitoring deployment/prometheus-operator -c config-reloader

总结

Prometheus Operator 故障排查需要系统性的方法。通过本文介绍的 7 个常见问题场景和解决方案，你应该能够快速诊断和解决大多数监控问题。记住关键步骤：检查日志、验证配置、确认权限、排除多 Operator 冲突。

更多详细配置示例可在 example/user-guides/getting-started/ 目录中找到，而完整的故障排除文档位于 Documentation/troubleshooting.md。

保持监控系统健康运行，让你的 Kubernetes 集群始终处于可控状态！✅

【免费下载链接】prometheus-operator 项目地址: https://gitcode.com/gh_mirrors/pro/prometheus-operator