如何通过Ingress Nginx注解基于URL查询字符串路由请求？（遇502错误）

需求 #

通过Ingress注解实现基于URL查询字符串将请求转发至不同后端服务，示例：

• https://example.com/foo?differentQueryString=0 → 转发至service-a
• https://example.com/foo/bar?queryString=0 → 转发至service-b
• 注意：请求路径不影响转发规则，支持任意路径如/foo/bar、/foo或/bar/foo等。

问题现象 #

参考相关资料后，尝试了如下Ingress配置，但请求返回502错误：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-ingress
 annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      if ($args ~ queryString=0){
            backend.service.name = service-b
          }
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: service-a
                port:
                  number: 80
          - path: /
            pathType: Prefix
            backend:
              service:
                name: service-b
                port:
                  number: 80

问题原因 #

配置中的backend.service.name = service-b不是NGINX的合法配置指令，NGINX无法识别该语法，导致Ingress Controller生成的NGINX配置无效，最终返回502错误。

解决方案 #

方法一：使用configuration-snippet直接判断转发 #

删除Ingress中重复的路径规则，保留默认后端为service-a，然后在注解中通过NGINX的proxy_pass指令，根据查询字符串条件转发到对应服务的上游地址（上游地址格式为http://<命名空间>-<服务名>-<端口>）：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-ingress
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      # 忽略大小写匹配queryString=0
      if ($args ~* "queryString=0") {
        proxy_pass http://default-service-b-80;
      }
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: service-a
                port:
                  number: 80

注意：将default替换为你的服务所在的命名空间。

方法二：使用map指令更优雅地管理转发规则 #

通过server-snippet定义查询字符串到后端服务的映射，再通过configuration-snippet统一转发：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-ingress
  annotations:
    nginx.ingress.kubernetes.io/server-snippet: |
      map $args $target_backend {
        # 匹配queryString=0，转发到service-b的上游
        ~*queryString=0 http://default-service-b-80;
        # 默认转发到service-a的上游
        default http://default-service-a-80;
      }
    nginx.ingress.kubernetes.io/configuration-snippet: |
      proxy_pass $target_backend;
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: service-a
                port:
                  number: 80

说明 #

• NGINX Ingress Controller会自动为K8s Service生成对应的上游（upstream），格式为<命名空间>-<服务名>-<端口>，确保替换为实际的命名空间和服务信息。
• 两种方法均无需额外配置ConfigMap或重复路由规则，符合需求。

内容的提问来源于stack exchange，提问作者Matan Baruch