最完整指南：用内置Prometheus监控Voyager管理的HAProxy Pod-优快云博客

最完整指南：用内置Prometheus监控Voyager管理的HAProxy Pod

【免费下载链接】voyager 🚀 Secure L7/L4 (HAProxy) Ingress Controller for Kubernetes 项目地址: https://gitcode.com/gh_mirrors/voyager1/voyager

你是否还在为Kubernetes集群中HAProxy的监控配置而烦恼？手动配置Prometheus、编写复杂的ServiceMonitor资源、处理权限问题——这些繁琐步骤消耗了你大量宝贵的开发时间。本指南将带你通过Voyager的内置Prometheus监控功能，仅需3个核心步骤即可实现从部署到可视化的全流程监控，彻底告别复杂配置。读完本文后，你将掌握：

使用Voyager注解自动启用HAProxy指标暴露
配置Prometheus自动发现Kubernetes服务端点
验证监控数据并排查常见问题
清理测试环境的最佳实践

技术背景与架构解析

Voyager是一个基于HAProxy的Kubernetes Ingress Controller（入口控制器），它将Kubernetes的Ingress资源转换为HAProxy配置，并管理对应的HAProxy Pod生命周期。为实现对这些动态变化的HAProxy实例的有效监控，Voyager提供了两种监控方案：

内置Prometheus监控组件：通过简单注解自动配置监控
CoreOS Prometheus Operator集成：适用于需要更复杂监控策略的场景

本文聚焦于第一种方案，其核心优势在于零手动配置Prometheus Targets。Voyager Operator会自动为HAProxy Stats Service添加Prometheus发现注解，使Prometheus能够自动发现并采集指标。

mermaid

前置条件与环境准备

在开始前，请确保你的环境满足以下要求：

Kubernetes集群（v1.19+推荐，可使用Minikube快速创建）
kubectl命令行工具已配置集群访问权限
Voyager Operator已部署（参考官方安装文档）

环境隔离最佳实践：使用独立命名空间进行测试，避免影响生产环境：

kubectl create namespace demo
# 验证命名空间创建
kubectl get ns | grep demo

步骤一：部署测试服务与配置Ingress

部署后端测试服务

我们使用Nginx作为后端服务示例，执行以下命令部署并暴露服务：

# 在demo命名空间部署Nginx
kubectl run nginx --image=nginx:1.21 -n demo
# 创建Service暴露Nginx
kubectl expose deployment nginx --name=web --port=80 --target-port=80 -n demo

创建带监控注解的Ingress资源

创建ing.yaml文件，注意其中的三个关键注解：

apiVersion: voyager.appscode.com/v1
kind: Ingress
metadata:
  name: stats-ing
  namespace: demo
  annotations:
    ingress.appscode.com/type: 'NodePort'          # 指定Ingress类型
    ingress.appscode.com/stats: 'true'             # 启用HAProxy stats
    ingress.appscode.com/monitoring-agent: 'prometheus.io/builtin'  # 启用内置Prometheus监控
spec:
  rules:
  - host: voyager.appscode.test
    http:
      paths:
      - path: /
        backend:
          service:
            name: web
            port:
              number: 80

应用此配置：

kubectl apply -f ing.yaml -n demo

验证资源创建

执行以下命令验证Voyager是否正确创建了相关资源：

# 查看Pod状态（应显示2/2就绪，包含HAProxy和Sidecar容器）
kubectl get pods -n demo -l origin=voyager

# 查看Service（应包含一个普通Service和一个stats Service）
kubectl get svc -n demo | grep voyager

关键观察点：stats Service名称格式为voyager-{ingress-name}-stats，且包含以下注解：

kubectl get svc voyager-stats-ing-stats -n demo -o jsonpath='{.metadata.annotations}'

预期输出应包含Prometheus发现所需的三个注解：

prometheus.io/scrape: "true"
prometheus.io/port: "56790"
prometheus.io/path: "/voyager.appscode.com/v1/namespaces/demo/ingresses/stats-ing/metrics"

步骤二：部署并配置Prometheus Server

创建Prometheus配置ConfigMap

创建prometheus-config.yaml文件，配置Prometheus自动发现Kubernetes服务端点：

apiVersion: v1
kind: ConfigMap
metadata:
  name: prometheus-server-conf
  namespace: demo
data:
  prometheus.yml: |-
    global:
      scrape_interval: 5s  # 采集间隔，生产环境可设为15s
      evaluation_interval: 5s
    scrape_configs:
    - job_name: 'kubernetes-service-endpoints'
      kubernetes_sd_configs:
      - role: endpoints  # 使用Kubernetes服务端点发现
      relabel_configs:
      # 仅保留标记了prometheus.io/scrape=true的服务
      - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scrape]
        action: keep
        regex: true
      # 从注解获取scheme
      - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scheme]
        action: replace
        target_label: __scheme__
        regex: (https?)
      # 从注解获取metrics路径
      - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_path]
        action: replace
        target_label: __metrics_path__
        regex: (.+)
      # 从注解获取端口并替换地址
      - source_labels: [__address__, __meta_kubernetes_service_annotation_prometheus_io_port]
        action: replace
        target_label: __address__
        regex: ([^:]+)(?::\d+)?;(\d+)
        replacement: $1:$2

应用配置：

kubectl apply -f prometheus-config.yaml -n demo

部署Prometheus Server

创建prometheus-deploy.yaml文件：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: prometheus-server
  namespace: demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: prometheus-server
  template:
    metadata:
      labels:
        app: prometheus-server
    spec:
      containers:
        - name: prometheus
          image: prom/prometheus:v2.30.3  # 使用稳定版本
          args:
            - "--config.file=/etc/prometheus/prometheus.yml"
            - "--storage.tsdb.path=/prometheus/"
            - "--web.enable-lifecycle"  # 启用远程配置重载
          ports:
            - containerPort: 9090
          volumeMounts:
            - name: prometheus-config-volume
              mountPath: /etc/prometheus/
            - name: prometheus-storage-volume
              mountPath: /prometheus/
      volumes:
        - name: prometheus-config-volume
          configMap:
            name: prometheus-server-conf
        - name: prometheus-storage-volume
          emptyDir: {}  # 生产环境应替换为PersistentVolume
---
apiVersion: v1
kind: Service
metadata:
  name: prometheus-service
  namespace: demo
spec:
  type: NodePort  # 便于外部访问
  ports:
    - port: 9090
      nodePort: 30901  # 固定NodePort便于访问
  selector:
    app: prometheus-server

部署Prometheus：

kubectl apply -f prometheus-deploy.yaml -n demo

配置RBAC权限（必要时）

如果你的集群启用了RBAC（Role-Based Access Control，基于角色的访问控制），需要为Prometheus创建必要的权限：

apiVersion: v1
kind: ServiceAccount
metadata:
  name: prometheus-server
  namespace: demo
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus-server
rules:
- apiGroups: [""]
  resources: ["endpoints", "services", "pods"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: prometheus-server
subjects:
- kind: ServiceAccount
  name: prometheus-server
  namespace: demo
roleRef:
  kind: ClusterRole
  name: prometheus-server
  apiGroup: rbac.authorization.k8s.io

应用RBAC配置：

kubectl apply -f prometheus-rbac.yaml -n demo
# 更新Prometheus Deployment使用新的ServiceAccount
kubectl patch deployment prometheus-server -n demo -p '{"spec":{"template":{"spec":{"serviceAccountName":"prometheus-server"}}}}'

步骤三：验证监控数据与可视化

访问Prometheus Dashboard

获取Prometheus服务的访问地址：

# 对于Minikube环境
minikube service prometheus-service -n demo --url

# 对于其他环境，获取NodeIP和NodePort
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[0].address}')
NODE_PORT=$(kubectl get svc prometheus-service -n demo -o jsonpath='{.spec.ports[0].nodePort}')
echo "Prometheus地址: http://${NODE_IP}:${NODE_PORT}"

在浏览器中访问上述地址，导航到"Status > Targets"页面，应能看到状态为"UP"的HAProxy目标，类似： demo/voyager-stats-ing-stats:http

常用监控指标查询

在Prometheus的"Graph"页面，尝试以下关键指标：

HAProxy前端连接数：

haproxy_frontend_current_sessions{frontend="http-01-frontend"}

后端服务器健康状态：

haproxy_backend_up{backend="default-stats-ing-web-80"}

说明：值为1表示健康，0表示不健康

HTTP请求速率：

rate(haproxy_frontend_http_requests_total{frontend="http-01-frontend"}[5m])

响应状态码分布：

haproxy_frontend_http_responses_total{frontend="http-01-frontend",code=~"2.."}
haproxy_frontend_http_responses_total{frontend="http-01-frontend",code=~"4.."}
haproxy_frontend_http_responses_total{frontend="http-01-frontend",code=~"5.."}

mermaid

常见问题排查

Prometheus Target显示Down：
- 检查Stats Service是否正常运行：kubectl get svc -n demo voyager-stats-ing-stats
- 验证注解是否正确应用：kubectl describe svc voyager-stats-ing-stats -n demo | grep prometheus.io
- 检查网络策略是否阻止Prometheus访问：kubectl get networkpolicy -n demo
指标缺失或不完整：
- 确认Ingress注解ingress.appscode.com/stats: 'true'已正确设置
- 查看HAProxy Pod日志：kubectl logs -n demo <haproxy-pod-name> haproxy
- 检查Prometheus配置是否正确加载：kubectl exec -n demo <prometheus-pod-name> -- cat /etc/prometheus/prometheus.yml
权限相关错误：
- 查看Prometheus Pod日志中的权限错误：kubectl logs -n demo <prometheus-pod-name>
- 验证RBAC配置是否正确应用：kubectl describe clusterrolebinding prometheus-server

环境清理与生产环境建议

清理测试环境

完成测试后，安全删除所有资源：

kubectl delete namespace demo

此命令将删除命名空间内的所有资源，包括Ingress、Service、Deployment和Prometheus实例。

生产环境部署建议

持久化存储：将Prometheus的存储从emptyDir替换为PersistentVolumeClaim
资源限制：为Prometheus和HAProxy Pod设置资源请求和限制
高可用：部署多个Prometheus实例并配置联邦（Federation）
指标保留策略：配置Prometheus的存储保留时间，避免磁盘占满
监控Alert：配置关键指标的告警规则，如后端健康状态、连接数阈值等
Grafana集成：部署Grafana并导入HAProxy监控面板（如Dashboard ID 249）

总结与展望

通过本文介绍的方法，你已成功实现了使用Voyager内置Prometheus监控功能对HAProxy Pod的全自动化监控。这种方案的核心优势在于：

配置简单：仅需添加几个注解即可完成监控启用
动态适应：自动适应HAProxy Pod的扩缩容和重新调度
低侵入性：无需修改HAProxy配置模板

对于需要更高级监控功能的场景，如跨命名空间监控、自定义指标采集频率或复杂告警规则，可考虑Voyager与CoreOS Prometheus Operator的集成方案。无论选择哪种方案，Voyager都提供了与Kubernetes生态深度集成的监控能力，帮助你构建更可靠的Ingress层。

最后，建议定期查看Voyager项目的官方文档和更新日志，以获取最新的监控功能和最佳实践。

【免费下载链接】voyager 🚀 Secure L7/L4 (HAProxy) Ingress Controller for Kubernetes 项目地址: https://gitcode.com/gh_mirrors/voyager1/voyager

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考