Kubernetes集群使用HAProxy Ingress实现/api前缀前后端分流不生效排查

现存配置问题点 #

• 未声明pathType字段，路径匹配逻辑完全错位
  K8s Ingress体系中pathType是决定路径匹配规则的核心标识，HAProxy Ingress对未声明该字段的路径默认采用精确匹配规则，只有完全等于/api的单个请求会被转发到后端服务，所有带子路径的请求（如/api/user、/api/list）都会因匹配失败落到前端，和原Nginx配置里location /api的前缀匹配逻辑完全不一致。
• 使用的Ingress API版本存在兼容缺陷
  当前配置采用的networking.k8s.io/v1beta1版本在K8s 1.22+版本已被官方废弃，主流版本的HAProxy Ingress控制器对该旧版API的解析存在兼容问题，会出现规则被静默忽略、仅保留全局默认后端流量转发能力的情况。
• 控制器未正常接管该Ingress资源
  配置仅使用旧版kubernetes.io/ingress.class: haproxy注解标记Ingress归属，新版HAProxy Ingress默认优先识别spec.ingressClassName字段的配置，旧注解在部分版本中会被直接忽略，导致控制器根本不加载该Ingress的路由规则，所有配置完全不生效。
• 路由规则结构不符合标准
  原配置将前端服务配置在全局spec.backend字段，未在http规则中声明根路径/的匹配项，控制器加载规则时根路径的流量转发优先级、匹配逻辑会出现异常，无法稳定承接前端静态资源的流量。

修正后可正常生效的配置 #

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: haproxy
  name: ingress
  namespace: lab
spec:
  ingressClassName: haproxy
  rules:
    - http:
        paths:
          # 根路径流量转发到前端服务
          - path: /
            pathType: Prefix
            backend:
              service:
                name: frontend
                port:
                  number: 80
          # /api前缀流量转发到后端服务
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: backend
                port:
                  number: 6969

落地验证步骤 #

• 执行kubectl describe ingress ingress -n lab，查看事件栏是否有HAProxy控制器上报的路由加载成功日志，确认资源被控制器正常接管。
• 从集群外部发起请求验证转发效果：
  • 访问http://<HAProxy Ingress入口IP>/，应返回前端静态页面内容
  • 访问http://<HAProxy Ingress入口IP>/api/任意接口路径，应返回后端服务的响应

注意：原Nginx配置中通过try_files $uri $uri/ /index.html实现的单页应用路由回退效果，是前端容器内部的Nginx逻辑负责处理，Ingress层仅需将根路径流量正确转发到前端容器即可，不需要额外配置，二者转发链路对齐后效果完全一致。如果后端服务本身不识别/api路径前缀，可根据需要添加对应的路径重写注解，实现和原Nginx配置一致的转发行为。

内容的提问来源于stack exchange，提问作者Hussein Feras