jizhuozhi commented on code in PR #12448: URL: https://github.com/apache/apisix/pull/12448#discussion_r2442274512
########## 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": "/consulWithMetadata/*", + "upstream": { + "service_name": "APISIX-CONSUL", + "type": "roundrobin", + "discovery_type": "consul", + "discovery_args": { + "metadata_match": { + "version": ["v1", "v2"] Review Comment: Hello @Baoyuantop , this feature has been running in our system since June, and we've benefited repeatedly from the ability to quickly recover from issues using an array rather than a string. To limit the blast radius of new feature releases, we divide service releases into three phases: canary, prod-blue, and prod-green. Canary handles only a minimal amount of traffic to verify system stability, while prod-blue receives 50% of the online traffic to verify business issues. We also implement modular deployments for our online services, ensuring that all services are fully integrated across canary, prod-blue, and prod-green environments. If an issue is discovered in prod-blue, we quickly remove that phase from the gateway entry point and forward all traffic to prod-green. With the current array-based configuration, if canary has some problem, we simply need to modify the apisix routing configuration: From ```json { "upstream": { "type": "roundrobin", "discovery_type": "consul", "discovery_args": { "metadata_match": { "env": ["canary", "prod-blue", "prod-green"] } } } } ``` To ```json { "upstream": { "type": "roundrobin", "discovery_type": "consul", "discovery_args": { "metadata_match": { "env": ["prod-blue", "prod-green"] } } } } ``` But if we are using single string value, we must predefine a key likes `env: prod` to present this is a prod instance (even canary), and for staging deployment, we need define a secondary key likes `staging: canary/prod-blue/prod-green`. Normally, it would be easy to use `env: prod` (traffic is distributed to canary/prod-blue/prod-green based on instance weights), but when canary fails, we need to use a secondary key `staging` to avoid using canary. However, since only one value can be configured, I can only choose `prod-blue` or `prod-green`, which means I have to choose half of the instances to serve all the traffic, even if the other half are available. From ```json { "upstream": { "type": "roundrobin", "discovery_type": "consul", "discovery_args": { "metadata_match": { "env": "prod" } } } } ``` To ```json { "upstream": { "type": "roundrobin", "discovery_type": "consul", "discovery_args": { "metadata_match": { "env": "prod", "staging": "prod-blue" // or "prod-green", cannot both "prod-blue" and "prod-green" } } } } ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
