[Feature]: Add external-filter in Header for advanced routing (#1804)

* feature: Add external-filter in Header for advanced routing
* add docs and client use case for external-filter
* make labelSelectorFilter into func and add test case
* take redundant log
---------

Signed-off-by: rayne-Li <lizhengyin1115@163.com>
Signed-off-by: rayneLi <lizhengyin1115@163.com>

Author: rayne-Li

docs/source/features/gateway-plugins.rst

@@ -194,6 +194,39 @@ To set up rate limiting, add the user header in the request, like this:
     If rate limit support is required, ensure this `user` header is always set in the request. if you do not need rate limit, you do not need to set this header.
 
 
+External Filter
+===============
+The ``external-filter`` header is evaluated **before** the routing strategy selects the optimal target pod. allows users to dynamically restrict the target Pods using Kubernetes ``labelSelector`` expressions.
+
+The header value follows the Kubernetes label selector syntax:
+
+- ``key=value``
+- ``key in (a, b)``
+- ``key!=value``
+- comma-separated selector list
+
+For label selector syntax reference:
+https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
+
+.. code-block:: bash
+   curl -v http://${ENDPOINT}/v1/completions \
+      -H "Content-Type: application/json" \
+      -H "routing-strategy: random" \
+      -H "external-filter: environment=production,tier=frontend" \
+      -d '{
+            "model": "deepseek-r1-distill-llama-8b",
+            "prompt": "San Francisco is a",
+            "max_tokens": 128,
+            "temperature": 0
+          }'
+
+.. note::
+    1. Filtering happens **before** the routing strategy. It never changes which Pods are considered “optimal” by the routing strategy.
+    2. The ``external-filter`` only takes effect when a ``routing-strategy``` is set.
+    3. It only reduces the Pod selected by `model.aibrix.ai/name` and set by applying extra label constraints.
+    4. Same as `no target pod`, If the filter eliminates all Pods, the request will fail with ``no ready pods for routing``.
+    5. ``external-filter`` is optional. When omitted, no extra filtering is applied.
+
 Headers Explanation
 --------------------
 
@@ -216,7 +249,8 @@ Target Headers & General Error Headers
      - Specifies the destination pod selected by the routing algorithm. Useful for verifying routing decisions.
    * - ``routing-strategy``
      - Defines the routing strategy applied to this request. Ensures correct routing logic is followed.
-
+   * - ``external-filter``
+     - Provides a generic and pluggable mechanism to further filter candidate Pods after routing. Filtering applied only when a routing strategy is set; Skipped if no routing algorithm is present.
 
 Routing & Error Debugging Headers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

pkg/plugins/gateway/gateway.go

@@ -160,7 +160,7 @@ func (s *Server) Process(srv extProcPb.ExternalProcessor_ProcessServer) error {
 	}
 }
 
-func (s *Server) selectTargetPod(ctx *types.RoutingContext, pods types.PodList) (string, error) {
+func (s *Server) selectTargetPod(ctx *types.RoutingContext, pods types.PodList, externalFilterExpr string) (string, error) {
 	router, err := routing.Select(ctx)
 	if err != nil {
 		return "", err
@@ -170,6 +170,13 @@ func (s *Server) selectTargetPod(ctx *types.RoutingContext, pods types.PodList)
 		return "", fmt.Errorf("no pods for routing")
 	}
 	readyPods := utils.FilterRoutablePods(pods.All())
+
+	// filter pod by header 'external-filter'
+	readyPods, err = utils.FilterPodsByLabelSelector(readyPods, externalFilterExpr)
+	if err != nil {
+		return "", fmt.Errorf("filter pods by label selector failed: %v", err)
+	}
+
 	if len(readyPods) == 0 {
 		return "", fmt.Errorf("no ready pods for routing")
 	}

pkg/plugins/gateway/gateway_req_body.go

@@ -74,7 +74,8 @@ func (s *Server) HandleRequestBody(ctx context.Context, requestID string, req *e
 		headers = buildEnvoyProxyHeaders(headers, HeaderModel, model)
 		klog.InfoS("request start", "requestID", requestID, "requestPath", requestPath, "model", model, "stream", stream)
 	} else {
-		targetPodIP, err := s.selectTargetPod(routingCtx, podsArr)
+		externalFilter := routingCtx.ReqHeaders[HeaderExternalFilter]
+		targetPodIP, err := s.selectTargetPod(routingCtx, podsArr, externalFilter)
 		if targetPodIP == "" || err != nil {
 			klog.ErrorS(err, "failed to select target pod", "requestID", requestID, "routingStrategy", routingAlgorithm, "model", model, "routingDuration", routingCtx.GetRoutingDelay())
 			return generateErrorResponse(

pkg/plugins/gateway/gateway_req_headers.go

@@ -56,6 +56,8 @@ func (s *Server) HandleRequestHeaders(ctx context.Context, requestID string, req
 			requestPath = string(n.RawValue)
 		case authorizationKey:
 			reqHeaders[n.Key] = string(n.RawValue)
+		case HeaderExternalFilter:
+			reqHeaders[n.Key] = string(n.RawValue)
 		}
 	}