feat(consul): filter nodes in upstream with metadata

docs keep same with #12445, but use metadata_match and array values

Author: jizhuozhi

apisix/discovery/consul/init.lua

@@ -21,6 +21,7 @@ local core_sleep         = require("apisix.core.utils").sleep
 local resty_consul       = require('resty.consul')
 local http               = require('resty.http')
 local util               = require("apisix.cli.util")
+local discovery_utils    = require("apisix.utils.discovery")
 local ipairs             = ipairs
 local error              = error
 local ngx                = ngx
@@ -78,36 +79,6 @@ function _M.all_nodes()
     return all_services
 end
 
-local function match_metadata_filters(inst, filters)
-    local metadata = inst.metadata or {}
-    for _, f in ipairs(filters) do
-        local key = f.key
-        local allowed_vals = f.value
-        local val = metadata[key]
-        local matched = false
-        for _, allowed in ipairs(allowed_vals) do
-            if val == allowed then
-                matched = true
-                break
-            end
-        end
-        if not matched then
-            return false
-        end
-    end
-    return true
-end
-
-local function match_nodes_by_metadata(nodes, filters)
-    local result = {}
-    for _, node in ipairs(nodes) do
-        if match_metadata_filters(node, filters) then
-            core.table.insert(result, node)
-        end
-    end
-    return result
-end
-
 function _M.nodes(service_name, discovery_args)
     if not all_services then
         log.error("all_services is nil, failed to fetch nodes for : ", service_name)
@@ -117,7 +88,7 @@ function _M.nodes(service_name, discovery_args)
     local resp_list = all_services[service_name]
 
     if discovery_args and discovery_args.metadata_match then
-        resp_list = match_nodes_by_metadata(resp_list, discovery_args.metadata_match)
+        resp_list = discovery_utils.nodes_metadata_match(resp_list, discovery_args.metadata_match)
     end
 
     if not resp_list then

apisix/schema_def.lua

@@ -488,6 +488,18 @@ local upstream_schema = {
                     description = "group name",
                     type = "string",
                 },
+                metadata_match = {
+                    description = "metadata for filtering service instances",
+                    type = "object",
+                    additionalProperties = {
+                        type = "array",
+                        items = {
+                            description = "candidate metadata value",
+                            type = "string",
+                        },
+                        uniqueItems = true,
+                    }
+                },
             }
         },
         pass_host = {

apisix/utils/discovery.lua

@@ -0,0 +1,50 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements.  See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License.  You may obtain a copy of the License at
+--
+--     http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+local ipairs = ipairs
+local pairs  = pairs
+
+local _M = {}
+
+local function do_metadata_match(inst, filters)
+    local metadata = inst.metadata or {}
+    for key, values in pairs(filters) do
+        local matched = false
+        for _, value in ipairs(values) do
+            if metadata[key] == value then
+                matched = true
+                break
+            end
+        end
+        if not matched then
+            return false
+        end
+    end
+    return true
+end
+
+local function nodes_metadata_match(nodes, metadata_match)
+    local result = {}
+    for _, node in ipairs(nodes) do
+        if do_metadata_match(node, metadata_match) then
+            core.table.insert(result, node)
+        end
+    end
+    return result
+end
+_M.nodes_metadata_match = nodes_metadata_match
+
+return _M

docs/en/latest/discovery/consul.md

@@ -232,6 +232,61 @@ $ curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 -H "X-API-KEY: $admin_
 }'
 ```
 
+### discovery_args
+
+| Name           | Type   | Requirement | Default | Valid | Description                                                  |
+|----------------| ------ | ----------- | ------- | ----- | ------------------------------------------------------------ |
+| metadata_match | object | optional    | {}      |       | Filter service instances by metadata using containment matching |
+
+#### Metadata filtering
+
+APISIX supports filtering service instances based on metadata. When a route is configured with metadata conditions, only service instances whose metadata matched with roles specified in the route's `metadata_match` configuration will be selected.
+
+Example: If a service instance has metadata `{lane: "a", env: "prod", version: "1.0"}`, it will match routes configured with metadata `{lane: ["a"]}` or `{lane: ["a", "b"], env: "prod"}`, but not routes configured with `{lane: ["c"]}` or `{lane: "a", region: "us"}`.
+
+Example of routing a request with metadata filtering:
+
+```shell
+$ curl http://127.0.0.1:9180/apisix/admin/routes/5 -H "X-API-KEY: $admin_key" -X PUT -i -d '
+{
+    "uri": "/nacosWithMetadata/*",
+    "upstream": {
+        "service_name": "APISIX-NACOS",
+        "type": "roundrobin",
+        "discovery_type": "nacos",
+        "discovery_args": {
+          "metadata": {
+            "version": ["v1", "v2"]
+          }
+        }
+    }
+}'
+```
+
+This route will only route traffic to service instances that have the metadata field `version` set to `v1` or `v2`.
+
+For multiple metadata criteria:
+
+```shell
+$ curl http://127.0.0.1:9180/apisix/admin/routes/6 -H "X-API-KEY: $admin_key" -X PUT -i -d '
+{
+    "uri": "/nacosWithMultipleMetadata/*",
+    "upstream": {
+        "service_name": "APISIX-NACOS",
+        "type": "roundrobin",
+        "discovery_type": "nacos",
+        "discovery_args": {
+          "metadata": {
+            "lane": ["a"],
+            "env": ["prod"]
+          }
+        }
+    }
+}'
+```
+
+This route will only route traffic to service instances that have both `lane: "a"` and `env: "prod"` in their metadata.
+
 You could find more usage in the `apisix/t/discovery/stream/consul.t` file.
 
 ## Debugging API