feat(nacos): add metadata filtering support to nacos discovery

apisix/discovery/nacos/init.lua

@@ -21,6 +21,7 @@ local http               = require('resty.http')
 local core               = require('apisix.core')
 local ipairs             = ipairs
 local pairs              = pairs
+local next               = next
 local type               = type
 local math               = math
 local math_random        = math.random
@@ -54,6 +55,33 @@ local function get_key(namespace_id, group_name, service_name)
     return namespace_id .. '.' .. group_name .. '.' .. service_name
 end
 
+
+local function metadata_contains(host_metadata, route_metadata)
+    if not host_metadata or not next(host_metadata) then
+        return false
+    end
+
+    for k, v in pairs(route_metadata) do
+        local host_value = host_metadata[k]
+        if not host_value then
+            return false
+        end
+
+        -- Multi-value matching: check if host_value matches any value in the array
+        local found = false
+        for _, expected_value in ipairs(v) do
+            if host_value == expected_value then
+                found = true
+                break
+            end
+        end
+        if not found then
+            return false
+        end
+    end
+    return true
+end
+
 local function request(request_uri, path, body, method, basic_auth)
     local url = request_uri .. path
     log.info('request url:', url)
@@ -319,6 +347,7 @@ local function fetch_full_registry(premature)
                 host = host.ip,
                 port = host.port,
                 weight = host.weight or default_weight,
+                metadata = host.metadata,
             }
             -- docs: https://github.com/yidongnan/grpc-spring-boot-starter/pull/496
             if is_grpc(scheme) and host.metadata and host.metadata.gRPC_port then
@@ -355,6 +384,19 @@ function _M.nodes(service_name, discovery_args)
         return nil
     end
     local nodes = core.json.decode(value)
+
+    -- Apply metadata filtering if specified
+    local route_metadata = discovery_args and discovery_args.metadata
+    if route_metadata and next(route_metadata) then
+        local filtered_nodes = {}
+        for _, node in ipairs(nodes) do
+            if metadata_contains(node.metadata, route_metadata) then
+                core.table.insert(filtered_nodes, node)
+            end
+        end
+        return filtered_nodes
+    end
+
     return nodes
 end
 

apisix/schema_def.lua

@@ -488,7 +488,17 @@ local upstream_schema = {
                     description = "group name",
                     type = "string",
                 },
-            }
+                metadata = {
+                    description = "metadata for filtering service instances",
+                    type = "object",
+                    additionalProperties = {
+                        type = "array",
+                        items = {
+                            type = "string"
+                        }
+                    }
+                },
+            },
         },
         pass_host = {
             description = "mod of host passing",

ci/pod/docker-compose.first.yml

@@ -178,6 +178,9 @@ services:
       - ci/pod/nacos/env/service.env
     environment:
       SUFFIX_NUM: 1
+      METADATA_LANE: "a"
+      METADATA_ENV: "prod"
+      METADATA_VERSION: "1.0"
     restart: unless-stopped
     ports:
       - "18001:18001"
@@ -195,6 +198,8 @@ services:
       - ci/pod/nacos/env/service.env
     environment:
       SUFFIX_NUM: 2
+      METADATA_LANE: "b"
+      METADATA_ENV: "test"
     restart: unless-stopped
     ports:
       - "18002:18001"
@@ -213,6 +218,8 @@ services:
     environment:
       SUFFIX_NUM: 1
       NAMESPACE: test_ns
+      METADATA_LANE: "b"
+      METADATA_ENV: "test"
     restart: unless-stopped
     ports:
       - "18003:18001"

ci/pod/nacos/service/Dockerfile

@@ -25,8 +25,8 @@ ENV GROUP=${GROUP:-DEFAULT_GROUP}
 
 ADD https://raw.githubusercontent.com/api7/nacos-test-service/main/spring-nacos-1.0-SNAPSHOT.jar /app.jar
 
-ENTRYPOINT ["java","-Djava.security.egd=file:/dev/./urandom","-jar","/app.jar",\
-            "--suffix.num=${SUFFIX_NUM}","--spring.cloud.nacos.discovery.server-addr=${NACOS_ADDR}",\
-            "--spring.application.name=${SERVICE_NAME}","--spring.cloud.nacos.discovery.group=${GROUP}",\
-            "--spring.cloud.nacos.discovery.namespace=${NAMESPACE}"]
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
 EXPOSE 18001

ci/pod/nacos/service/entrypoint.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+#
+# 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.
+#
+
+# Build Java command with proper environment variable expansion
+JAVA_ARGS=(
+    "-Djava.security.egd=file:/dev/./urandom"
+    "-jar"
+    "/app.jar"
+    "--suffix.num=${SUFFIX_NUM}"
+    "--spring.cloud.nacos.discovery.server-addr=${NACOS_ADDR}"
+    "--spring.application.name=${SERVICE_NAME}"
+    "--spring.cloud.nacos.discovery.group=${GROUP}"
+    "--spring.cloud.nacos.discovery.namespace=${NAMESPACE}"
+)
+
+# Add metadata dynamically for all METADATA_* environment variables
+for var in $(env | grep '^METADATA_' | cut -d= -f1); do
+    # Convert METADATA_LANE to lane, METADATA_ENV to env, etc.
+    metadata_key=$(echo "${var#METADATA_}" | tr '[:upper:]' '[:lower:]')
+    metadata_value=$(eval echo \$${var})
+
+    if [ -n "${metadata_value}" ]; then
+        JAVA_ARGS+=("--spring.cloud.nacos.discovery.metadata.${metadata_key}=${metadata_value}")
+    fi
+done
+
+# Execute Java with expanded arguments
+exec java "${JAVA_ARGS[@]}"

docs/en/latest/discovery/nacos.md

@@ -132,6 +132,7 @@ $ curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 -H "X-API-KEY: $admin_
 | ------------ | ------ | ----------- | ------- | ----- | ------------------------------------------------------------ |
 | namespace_id | string | optional    | public     |       | This parameter is used to specify the namespace of the corresponding service |
 | group_name   | string | optional    | DEFAULT_GROUP       |       | This parameter is used to specify the group of the corresponding service |
+| metadata     | object | optional    | {}      |       | Filter service instances by metadata using containment matching |
 
 #### Specify the namespace
 
@@ -278,3 +279,52 @@ The formatted response as below:
   }
 }
 ```
+
+#### Metadata filtering
+
+APISIX supports filtering service instances based on metadata. When a route is configured with metadata conditions, only service instances whose metadata contains all the key-value pairs specified in the route's `metadata` 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", env: "prod"}`, but not routes configured with `{lane: "b"}` 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"
+          }
+        }
+    }
+}'
+```
+
+This route will only route traffic to service instances that have the metadata field `version` set to `v1`.
+
+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.

docs/zh/latest/discovery/nacos.md

@@ -132,6 +132,7 @@ $ curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 -H "X-API-KEY: $admin_
 | ------------ | ------ | ----------- | ------- | ----- | ------------------------------------------------------------ |
 | namespace_id | string | 可选    | public     |       | 服务所在的命名空间 |
 | group_name   | string | 可选    | DEFAULT_GROUP       |       | 服务所在的组 |
+| metadata     | object | 可选    | {}      |       | 使用包含匹配方式根据元数据过滤服务实例 |
 
 #### 指定命名空间
 
@@ -281,3 +282,52 @@ $ curl http://127.0.0.1:9180/apisix/admin/routes/4 -H "X-API-KEY: $admin_key" -X
   }
 }
 ```
+
+#### 使用元数据过滤服务实例
+
+APISIX 支持根据元数据过滤服务实例。当路由配置了元数据条件时，只有服务实例的元数据包含路由配置中指定的所有键值对，该服务实例才会被选中。
+
+举例：如果服务实例的元数据是 `{lane: "a", env: "prod", version: "1.0"}`，那么它能匹配配置了元数据 `{lane: "a"}` 或 `{lane: "a", env: "prod"}` 的路由，但不能匹配配置了 `{lane: "b"}` 或 `{lane: "a", region: "us"}` 的路由。
+
+使用元数据过滤的路由配置示例：
+
+```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"
+          }
+        }
+    }
+}'
+```
+
+此路由只会将流量转发到元数据字段 `version` 为 `v1` 的服务实例。
+
+使用多个元数据条件的示例：
+
+```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"
+          }
+        }
+    }
+}'
+```
+
+此路由只会将流量转发到元数据中同时包含 `lane: "a"` 和 `env: "prod"` 的服务实例。