Apache APISIX 在 OVH Kubernetes 集群中获取客户端真实 IP 的配置实践

背景介绍

在现代云原生架构中，Apache APISIX 作为高性能 API 网关，经常被部署在 Kubernetes 集群中。当集群位于 OVH 云平台时，由于负载均衡器的存在，APISIX 默认无法获取到客户端的真实 IP 地址，这给日志记录、访问控制等关键功能带来了挑战。

问题分析

在 OVH Kubernetes 集群中，流量会经过以下路径到达 APISIX：

1. 客户端请求首先到达 OVH 负载均衡器
2. 负载均衡器将请求转发到 Kubernetes 节点
3. 节点上的 kube-proxy 将请求路由到 APISIX Pod

在这个过程中，如果不进行特殊配置，APISIX 只能看到负载均衡器的 IP 地址，而非原始客户端的真实 IP。

解决方案

1. 启用 PROXY 协议

APISIX 支持 PROXY 协议，这是一种在 TCP 层传递客户端信息的标准方法。要启用此功能，需要在 APISIX 的 config.yaml 配置文件中进行以下设置：

proxy_protocol:
  listen_http_port: 9181
  listen_https_port: 9182
  enable_tcp_pp: true
  enable_tcp_pp_to_upstream: true

2. Kubernetes Service 配置

在 Kubernetes 中，需要确保 Service 资源正确配置：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/ovh-loadbalancer-proxy-protocol: "v2"
  name: apisix-gateway
spec:
  ports:
  - name: http
    port: 80
    targetPort: 9181
  - name: https
    port: 443
    targetPort: 9182
  selector:
    app: apisix
  type: LoadBalancer

关键点说明：

• service.beta.kubernetes.io/ovh-loadbalancer-proxy-protocol 注解启用 OVH 负载均衡器的 PROXY 协议支持
• Service 的 targetPort 必须与 APISIX 配置中的 listen_http_port 和 listen_https_port 对应

3. APISIX 路由配置验证

配置完成后，可以通过创建测试路由来验证客户端 IP 是否正确传递：

curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: your-admin-key' \
-d '{
    "uri": "/ip",
    "plugins": {
        "response-rewrite": {
            "body": "{\"client_ip\":\"$remote_addr\"}"
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "httpbin.org:80": 1
        }
    }
}'

访问该路由时，返回的 JSON 中应该显示真实的客户端 IP 而非负载均衡器的 IP。

常见问题排查

1. 配置不生效：

   • 检查 APISIX 日志确认 PROXY 协议已启用
   • 确保 Service 的 targetPort 与 APISIX 配置匹配
   • 验证 OVH 负载均衡器确实启用了 PROXY 协议

2. 连接问题：

   • 如果出现连接失败，检查防火墙规则是否允许 PROXY 协议端口通信
   • 确认 APISIX Pod 健康状态

3. IP 格式不正确：

   • 确保使用 PROXY 协议 v2 版本
   • 检查网络中间件是否修改了 PROXY 协议头

性能考量

启用 PROXY 协议会带来轻微的性能开销，主要体现在：

• 额外的 TCP 握手过程
• 每个连接需要解析 PROXY 协议头
• 内存中需要维护更多连接状态信息

在大多数生产场景中，这种开销是可以接受的，特别是与获取真实客户端 IP 带来的好处相比。

最佳实践建议

1. 逐步启用：先在测试环境验证配置，再逐步推广到生产环境
2. 监控设置：密切关注启用后的延迟和吞吐量变化
3. 日志记录：确保访问日志中包含客户端真实 IP 用于审计
4. 安全策略：基于真实客户端 IP 实施速率限制等安全措施

通过以上配置，APISIX 在 OVH Kubernetes 环境中可以准确获取客户端真实 IP，为后续的流量管理、安全防护等高级功能奠定基础。