This is an automated email from the ASF dual-hosted git repository.
traky pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 4bc03e9f7 docs: improve `traffic-split` plugin docs (#11935)
4bc03e9f7 is described below
commit 4bc03e9f7d768919eb2414febfaf7f4825053364
Author: Traky Deng <[email protected]>
AuthorDate: Fri Mar 28 15:27:36 2025 +0800
docs: improve `traffic-split` plugin docs (#11935)
---
docs/en/latest/plugins/traffic-split.md | 892 ++++++++++++++++---------------
docs/zh/latest/plugins/traffic-split.md | 896 ++++++++++++++++----------------
2 files changed, 882 insertions(+), 906 deletions(-)
diff --git a/docs/en/latest/plugins/traffic-split.md
b/docs/en/latest/plugins/traffic-split.md
index 9eb00d651..a4a65b684 100644
--- a/docs/en/latest/plugins/traffic-split.md
+++ b/docs/en/latest/plugins/traffic-split.md
@@ -6,7 +6,7 @@ keywords:
- Traffic Split
- Blue-green Deployment
- Canary Deployment
-description: This document contains information about the Apache APISIX
traffic-split Plugin, you can use it to dynamically direct portions of traffic
to various Upstream services.
+description: The traffic-split Plugin directs traffic to various Upstream
services based on conditions and/or weights. It provides a dynamic and flexible
approach to implement release strategies and manage traffic.
---
<!--
@@ -28,13 +28,13 @@ description: This document contains information about the
Apache APISIX traffic-
#
-->
-## Description
-
-The `traffic-split` Plugin can be used to dynamically direct portions of
traffic to various Upstream services.
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/traffic-split"; />
+</head>
-This is done by configuring `match`, which are custom rules for splitting
traffic, and `weighted_upstreams` which is a set of Upstreams to direct traffic
to.
+## Description
-When a request is matched based on the `match` attribute configuration, it
will be directed to the Upstreams based on their configured `weights`. You can
also omit using the `match` attribute and direct all traffic based on
`weighted_upstreams`.
+The `traffic-split` Plugin directs traffic to various Upstream services based
on conditions and/or weights. It provides a dynamic and flexible approach to
implement release strategies and manage traffic.
:::note
@@ -46,42 +46,28 @@ The traffic ratio between Upstream services may be less
accurate since round rob
| Name | Type | Required | Default |
Valid values | Description
|
|--------------------------------|----------------|----------|------------|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| rules.match | array[object] | False | |
| Rules to match for conditional traffic split. By
default the list is empty and the traffic will be split unconditionally.
|
-| rules.match.vars | array[array] | False | |
| List of variables to match for filtering requests
for conditional traffic split. It is in the format `{variable operator value}`.
For example, `{"arg_name", "==", "json"}`. The variables here are consistent
with NGINX internal variables. For details on supported operators,
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list). |
-| rules.weighted_upstreams | array[object] | False | |
| List of Upstream configurations.
|
-| weighted_upstreams.upstream_id | string/integer | False | |
| ID of the configured Upstream object.
|
-| weighted_upstreams.upstream | object | False | |
| Configuration of the Upstream.
|
-| upstream.type | enum | False | roundrobin |
[roundrobin, chash] | Type of mechanism to use for traffic splitting.
`roundobin` supports weighted load and `chash` does consistent hashing.
|
-| upstream.hash_on | enum | False | vars |
| Only valid if the `type` is `chash`. Supported
`vars` (Nginx variables), `header` (custom header), `cookie`, `consumer`, and
`vars_combinations`. For more details, refer
[Upstream](../admin-api.md#upstream).
|
-| upstream.key | string | False | |
| Only valid if the `type` is `chash`. Finds the
corresponding node `id` according to `hash_on` and `key` values. For more
details, refer [Upstream](../admin-api.md#upstream).
|
-| upstream.nodes | object | False | |
| IP addresses (with optional ports) of the Upstream
nodes represented as a hash table. In the hash table, the key is the IP address
and the value is the weight of the node. Setting `weight` to `0` means that a
request is never forwarded to that node.
|
-| upstream.timeout | object | False | 15 |
| Timeout in seconds for connecting, sending and
receiving messages.
|
-| upstream.pass_host | enum | False | "pass" |
["pass", "node", "rewrite"] | Configures the host when the request is forwarded
to the upstream. Can be one of `pass`, `node` or `rewrite`. `pass`-
transparently passes the client's host to the Upstream. `node`- uses the host
configured in the node of the Upstream. `rewrite`- Uses the value configured in
`upstream_host`. |
-| upstream.name | string | False | |
| Identifier for the Upstream for specifying service
name, usage scenarios etc.
|
-| upstream.upstream_host | string | False | |
| Host of the Upstream request. Only valid when
`pass_host` attribute is set to `rewrite`.
|
-| weighted_upstreams.weight | integer | False | weight = 1 |
| Weight to give to each Upstream node for splitting
traffic.
|
+| rules.match | array[object] | False | |
| An array of one or more pairs of matching conditions
and actions to be executed. |
+| rules.match | array[object] | False | |
| Rules to match for conditional traffic split.
|
+| rules.match.vars | array[array] | False | |
| An array of one or more matching conditions in the
form of [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)
to conditionally execute the plugin. |
+| rules.weighted_upstreams | array[object] | False | |
| List of Upstream configurations. |
+| rules.weighted_upstreams.upstream_id | string/integer | False |
| | ID of the configured Upstream object. |
+| rules.weighted_upstreams.weight | integer | False | weight =
1 | | Weight for each upstream. |
+| rules.weighted_upstreams.upstream | object | False |
| | Configuration of the upstream. Certain
configuration options Upstream are not supported here. These fields are
`service_name`, `discovery_type`, `checks`, `retries`, `retry_timeout`, `desc`,
and `labels`. As a workaround, you can create an Upstream object and configure
it in `upstream_id`. |
+| rules.weighted_upstreams.upstream.type | array |
False | roundrobin | [roundrobin, chash] | Algorithm for traffic
splitting. `roundrobin` for weighted round robin and `chash` for consistent
hashing. |
+| rules.weighted_upstreams.upstream.hash_on | array |
False | vars | | Used when `type` is
`chash`. Support hashing on [NGINX
variables](https://nginx.org/en/docs/varindex.html), headers, cookie, Consumer,
or a combination of [NGINX
variables](https://nginx.org/en/docs/varindex.html). |
+| rules.weighted_upstreams.upstream.key | string |
False | | | Used when `type` is
`chash`. When `hash_on` is set to `header` or `cookie`, `key` is required. When
`hash_on` is set to `consumer`, `key` is not required as the Consumer name will
be used as the key automatically. |
+| rules.weighted_upstreams.upstream.nodes | object |
False | | | Addresses of the Upstream
nodes. |
+| rules.weighted_upstreams.upstream.timeout | object |
False | 15 | | Timeout in seconds for
connecting, sending and receiving messages. |
+| rules.weighted_upstreams.upstream.pass_host | array |
False | "pass" | ["pass", "node", "rewrite"] | Mode deciding how the
host name is passed. `pass` passes the client's host name to the upstream.
`node` passes the host configured in the node of the upstream. `rewrite` passes
the value configured in `upstream_host`. |
+| rules.weighted_upstreams.upstream.name | string |
False | | | Identifier for the
Upstream for specifying service name, usage scenarios, and so on. |
+| rules.weighted_upstreams.upstream.upstream_host | string |
False | | | Used when `pass_host` is
`rewrite`. Host name of the upstream. |
+
+## Examples
+
+The examples below show different use cases for using the `traffic-split`
Plugin.
:::note
-Some of the configuration fields supported in Upstream are not supported in
weighted_upstreams.upstream. These fields are `service_name`, `discovery_type`,
`checks`, `retries`, `retry_timeout`, `desc`, `labels`, `create_time`, and
`update_time`.
-
-As a workaround, you can create an Upstream object and configure it in
`weighted_upstreams.upstream_id` to achieve these functionalities.
-
-:::
-
-:::info IMPORTANT
-
-In the `match` attribute configuration, the expression in variable is related
as AND whereas multiple variables are related by OR.
-
-If only the `weight` attribute is configured, it corresponds to the weight of
the Upstream service configured on the Route or Service. You can see this in
action below.
-
-:::
-
-## Enable Plugin
-
-You can configure the Plugin on a Route as shown below:
-
-:::note
You can fetch the `admin_key` from `config.yaml` and save to an environment
variable with the following command:
```bash
@@ -90,556 +76,562 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
- "plugins": {
- "traffic-split": {
- "rules": [
- {
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream_A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":10
- },
- "timeout": {
- "connect": 15,
- "send": 15,
- "read": 15
- }
- },
- "weight": 1
- },
- {
- "weight": 1
- }
- ]
- }
- ]
- }
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
-```
+### Implement Canary Release
+
+The following example demonstrates how to implement canary release with this
Plugin.
-Alternatively, you can configure `upstream_id` if you have already configured
an Upstream object:
+A Canary release is a gradual deployment in which an increasing percentage of
traffic is directed to a new release, allowing for a controlled and monitored
rollout. This method ensures that any potential issues or bugs in the new
release can be identified and addressed early on, before fully redirecting all
traffic.
+
+Create a Route and configure `traffic-split` Plugin with the following rules:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/headers",
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "weighted_upstreams": [
- {
- "upstream_id": 1,
- "weight": 1
- },
- {
- "weight": 1
- }
- ]
- }
+ "traffic-split": {
+ "rules": [
+ {
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
+ },
+ "weight": 3
+ },
+ {
+ "weight": 2
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
}
-}'
+ }'
```
-:::tip
+The proportion of traffic to each Upstream is determined by the weight of the
Upstream relative to the total weight of all upstreams. Here, the total weight
is calculated as: 3 + 2 = 5.
-Configure via `upstream_id` to reuse Upstream's health detection, retires, and
other functions.
+Therefore, 60% of the traffic are to be forwarded to `httpbin.org` and the
other 40% of the traffic are to be forwarded to `mock.api7.ai`.
-:::
+Send 10 consecutive requests to the Route to verify:
-:::note
+```shell
+resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/headers"; -sL) && \
+ count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+ count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+ echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
+```
-You can use both `upstream` configuration and `upstream_id` configuration
together.
+You should see a response similar to the following:
-:::
+```text
+httpbin.org: 6, mock.api7.ai: 4
+```
-## Example usage
+Adjust the Upstream weights accordingly to complete the canary release.
-The examples below shows different use cases for using the `traffic-split`
Plugin.
+### Implement Blue-Green Deployment
-### Canary release
+The following example demonstrates how to implement blue-green deployment with
this Plugin.
-This is the process of gradually rolling out a release by splitting an
increasing percentage of traffic to the new release until all traffic is
directed to the new release.
+Blue-green deployment is a deployment strategy that involves maintaining two
identical environments: the _blue_ and the _green_. The blue environment refers
to the current production deployment and the green environment refers to the
new deployment. Once the green environment is tested to be ready for
production, traffic will be routed to the green environment, making it the new
production deployment.
-To set this up, you can configure the `weight` attribute of your
`weighted_upstreams` as shown below:
+Create a Route and configure `traffic-split` Plugin to execute the Plugin to
redirect traffic only when the request contains a header `release: new_release`:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/headers",
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream_A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":10
- },
- "timeout": {
- "connect": 15,
- "send": 15,
- "read": 15
- }
- },
- "weight": 3
- },
- {
- "weight": 2
- }
- ]
+ "traffic-split": {
+ "rules": [
+ {
+ "match": [
+ {
+ "vars": [
+ ["http_release","==","new_release"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
}
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
}
-}'
+ }'
```
-Here, the weights are in the ratio 3:2 which means that 60% of the traffic
reaches the Upstream service running on `:1981` (Plugin's Upstream) and 40%
reaches the service running on `:1980` which is the Route's Upstream service.
-
-Now to test this configuration, if you make 5 requests, 3 will hit one service
and 2 will hit the other:
+Send a request to the Route with the `release` header:
```shell
-curl http://127.0.0.1:9080/index.html -i
+curl "http://127.0.0.1:9080/headers"; -H 'release: new_release'
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
+You should see a response similar to the following:
+
+```json
+{
+ "headers": {
+ "Accept": "*/*",
+ "Host": "httpbin.org",
+ ...
+ }
+}
```
+Send a request to the Route without any additional header:
+
```shell
-curl http://127.0.0.1:9080/index.html -i
+curl "http://127.0.0.1:9080/headers";
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-world 1981
+You should see a response similar to the following:
+
+```json
+{
+ "headers": {
+ "accept": "*/*",
+ "host": "mock.api7.ai",
+ ...
+ }
+}
```
-### Blue-green release
+### Define Matching Condition for POST Request With APISIX Expressions
-In this setup, user traffic is shifted from the "green" (production)
environment to the "blue" (staging) environment once the new changes have been
tested and accepted within the blue environment.
+The following example demonstrates how to use
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) in rules
to conditionally execute the Plugin when certain condition of a POST request is
satisfied.
-To set this up, you can configure `match` rules based on the request headers
as shown below:
+Create a Route and configure `traffic-split` Plugin with the following rules:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/post",
+ "methods": ["POST"],
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "match": [
- {
- "vars": [
- ["http_release","==","new_release"]
- ]
- }
- ],
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream_A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":10
- }
- }
- }
- ]
+ "traffic-split": {
+ "rules": [
+ {
+ "match": [
+ {
+ "vars": [
+ ["post_arg_id", "==", "1"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
}
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
}
-}'
+ }'
```
-Here, if the request comes with a `release` header with value `new_release` it
is directed to the new Upstream.
-
-Now if you send a request with `new_release` as the value for the `release`
header, it will be directed to one Upstream and other requests will be directed
to another Upstream.
+Send a POST request with body `id=1`:
```shell
-curl http://127.0.0.1:9080/index.html -H 'release: new_release' -i
+curl "http://127.0.0.1:9080/post"; -X POST \
+ -H 'Content-Type: application/x-www-form-urlencoded' \
+ -d 'id=1'
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-world 1981
-```
+You should see a response similar to the following:
-```shell
-curl http://127.0.0.1:9080/index.html -H 'release: old_release' -i
+```json
+{
+ "args": {},
+ "data": "",
+ "files": {},
+ "form": {
+ "id": "1"
+ },
+ "headers": {
+ "Accept": "*/*",
+ "Content-Length": "4",
+ "Content-Type": "application/x-www-form-urlencoded",
+ "Host": "httpbin.org",
+ ...
+ },
+ ...
+}
```
+Send a POST request without `id=1` in the body:
+
```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
+curl "http://127.0.0.1:9080/post"; -X POST \
+ -H 'Content-Type: application/x-www-form-urlencoded' \
+ -d 'random=string'
```
-### Custom release
+You should see that the request was forwarded to `mock.api7.ai`.
+
+### Define AND Matching Conditions With APISIX Expressions
-You can also make custom releases by configuring rules and setting weights.
+The following example demonstrates how to use
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) in rules
to conditionally execute the Plugin when multiple conditions are satisfied.
-In the example below, only one `vars` rule is configured and the multiple
expressions in the rule have an AND relationship. The weights are configured in
3:2 ratio and traffic not matching the `vars` will be redirected to the
Upstream configured on the Route.
+Create a Route and configure `traffic-split` Plugin to redirect traffic only
when all three conditions are satisfied:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/headers",
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "match": [
- {
- "vars": [
- ["arg_name","==","jack"],
- ["http_user-id",">","23"],
- ["http_apisix-key","~~","[a-z]+"]
- ]
- }
- ],
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream_A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":10
- }
- },
- "weight": 3
- },
- {
- "weight": 2
- }
- ]
- }
+ "traffic-split": {
+ "rules": [
+ {
+ "match": [
+ {
+ "vars": [
+ ["arg_name","==","jack"],
+ ["http_user-id",">","23"],
+ ["http_apisix-key","~~","[a-z]+"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
+ },
+ "weight": 3
+ },
+ {
+ "weight": 2
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
}
-}'
+ }'
```
-After the rules are matched, 60% of the traffic hit the Upstream on port
`1981` and 40% hit the one on `1980`.
+If conditions are satisfied, 60% of the traffic should be directed to
`httpbin.org` and the other 40% should be directed to `mock.api7.ai`. If
conditions are not satisfied, all traffic should be directed to `mock.api7.ai`.
+
+Send 10 consecutive requests that satisfy all conditions to verify:
```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' \
--H 'user-id:30' -H 'apisix-key: hello' -i
+resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/headers?name=jack"; -H
'user-id: 30' -H 'apisix-key: helloapisix' -sL) && \
+ count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+ count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+ echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-world 1981
+You should see a response similar to the following:
+
+```text
+httpbin.org: 6, mock.api7.ai: 4
```
-If the rule fails to match, then the request is directed to the service on
`1980`:
+Send 10 consecutive requests that do not satisfy the conditions to verify:
```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' \
--H 'user-id:30' -H 'apisix-key: hello' -i
+resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/headers?name=random";
-sL) && \
+ count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+ count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+ echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
+You should see a response similar to the following:
+
+```text
+httpbin.org: 0, mock.api7.ai: 10
```
-In the example below, multiple `vars` rules are configured and they have an OR
relationship.
+### Define OR Matching Conditions With APISIX Expressions
+
+The following example demonstrates how to use
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) in rules
to conditionally execute the Plugin when either set of the condition is
satisfied.
+
+Create a Route and configure `traffic-split` Plugin to redirect traffic when
either set of the configured conditions are satisfied:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/headers",
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "match": [
- {
- "vars": [
- ["arg_name","==","jack"],
- ["http_user-id",">","23"],
- ["http_apisix-key","~~","[a-z]+"]
- ]
- },
- {
- "vars": [
- ["arg_name2","==","rose"],
- ["http_user-id2","!",">","33"],
- ["http_apisix-key2","~~","[a-z]+"]
- ]
- }
- ],
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream_A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":10
- }
- },
- "weight": 3
- },
- {
- "weight": 2
- }
- ]
- }
+ "traffic-split": {
+ "rules": [
+ {
+ "match": [
+ {
+ "vars": [
+ ["arg_name","==","jack"],
+ ["http_user-id",">","23"],
+ ["http_apisix-key","~~","[a-z]+"]
+ ]
+ },
+ {
+ "vars": [
+ ["arg_name2","==","rose"],
+ ["http_user-id2","!",">","33"],
+ ["http_apisix-key2","~~","[a-z]+"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
+ },
+ "weight": 3
+ },
+ {
+ "weight": 2
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
}
-}'
+ }'
```
-In the example below, both the `vars` rules are matched. After the rules are
matched, 60% of the traffic is directed to the service on `1981` and 40% to the
service on `1980`:
-
-```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack&name2=rose' \
--H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2:
world' -i
-```
+Alternatively, you can also use the OR operator in the
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) for
these conditions.
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-world 1981
-```
+If conditions are satisfied, 60% of the traffic should be directed to
`httpbin.org` and the other 40% should be directed to `mock.api7.ai`. If
conditions are not satisfied, all traffic should be directed to `mock.api7.ai`.
-```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack&name2=rose' \
--H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2:
world' -i
-```
+Send 10 consecutive requests that satisfy the second set of conditions to
verify:
```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
+resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/headers?name2=rose"; -H
'user-id:30' -H 'apisix-key2: helloapisix' -sL) && \
+ count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+ count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+ echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-In the example below, the second `vars` rule fail to match. But since it is an
OR relationship, the rules are matched and traffic is directed as configured:
+You should see a response similar to the following:
-```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' \
--H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2:
world' -i
+```json
+httpbin.org: 6, mock.api7.ai: 4
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-world 1981
-```
+Send 10 consecutive requests that do not satisfy any set of conditions to
verify:
```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' \
--H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2:
world' -i
+resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/headers?name=random";
-sL) && \
+ count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+ count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+ echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
-```
-
-In the example below the required headers are missing and both the `vars`
rules fail to match and the request is directed to the default Upstream of the
Route (`1980`):
-
-```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' -i
-```
+You should see a response similar to the following:
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
+```json
+httpbin.org: 0, mock.api7.ai: 10
```
-### Multiple rules to correspond to Upstream
+### Configure Different Rules for Different Upstreams
-You can achieve one-to-one correspondence between rules and Upstream by
configuring multiple `rules`:
+The following example demonstrates how to set one-to-one mapping between rule
sets and upstreams.
-For example, when the request header `x-api-id` is equal to `1` it should be
directed to Upstream on port `1981` and if it is equal to `2` it should be
directed to Upstream on port `1982`. And in other cases, it should default to
the Upstream on port `1980`. You can configure this as shown below:
+Create a Route and configure `traffic-split` Plugin with the following
matching rules to redirect traffic when the request contains a header
`x-api-id: 1` or `x-api-id: 2`, to the corresponding Upstream service:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/hello",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/headers",
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "match": [
- {
- "vars": [
- ["http_x-api-id","==","1"]
- ]
- }
- ],
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream-A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":1
- }
- },
- "weight": 3
- }
- ]
+ "traffic-split": {
+ "rules": [
+ {
+ "match": [
+ {
+ "vars": [
+ ["http_x-api-id","==","1"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
},
- {
- "match": [
- {
- "vars": [
- ["http_x-api-id","==","2"]
- ]
- }
- ],
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream-B",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1982":1
- }
- },
- "weight": 3
- }
- ]
- }
+ "weight": 1
+ }
]
- }
+ },
+ {
+ "match": [
+ {
+ "vars": [
+ ["http_x-api-id","==","2"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
+ },
+ "weight": 1
+ }
+ ]
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "nodes": {
+ "postman-echo.com:443": 1
+ },
+ "scheme": "https",
+ "pass_host": "node"
}
-}'
+ }'
```
-Now, when the request header `x-api-id` is equal to `1`, it will hit the
Upstream on `1981`:
-
-```shell
-curl http://127.0.0.1:9080/hello -H 'x-api-id: 1'
-```
+Send a request with header `x-api-id: 1`:
```shell
-1981
+curl "http://127.0.0.1:9080/headers"; -H 'x-api-id: 1'
```
-If request header `x-api-id` is equal to `2`, it will hit the Upstream on
`1982`:
+You should see an `HTTP/1.1 200 OK` response similar to the following:
-```shell
-curl http://127.0.0.1:9080/hello -H 'x-api-id: 2'
+```json
+{
+ "headers": {
+ "Accept": "*/*",
+ "Host": "httpbin.org",
+ ...
+ }
+}
```
+Send a request with header `x-api-id: 2`:
+
```shell
-1982
+curl "http://127.0.0.1:9080/headers"; -H 'x-api-id: 2'
```
-If request header `x-api-id` is equal to `3`, the rules do not match, and it
will hit the Upstream on `1980`:
+You should see an `HTTP/1.1 200 OK` response similar to the following:
-```shell
-curl http://127.0.0.1:9080/hello -H 'x-api-id: 3'
+```json
+{
+ "headers": {
+ "accept": "*/*",
+ "host": "mock.api7.ai",
+ ...
+ }
+}
```
+Send a request without any additional header:
+
```shell
-1980
+curl "http://127.0.0.1:9080/headers";
```
-## Delete Plugin
-
-To remove the `traffic-split` Plugin, you can delete the corresponding JSON
configuration from the Plugin configuration. APISIX will automatically reload
and you do not have to restart for this to take effect.
+You should see a response similar to the following:
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
+```json
{
- "uri": "/index.html",
- "plugins": {},
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
+ "headers": {
+ "accept": "*/*",
+ "host": "postman-echo.com",
+ ...
+ }
+}
```
diff --git a/docs/zh/latest/plugins/traffic-split.md
b/docs/zh/latest/plugins/traffic-split.md
index 1a725ae98..a460d4bfc 100644
--- a/docs/zh/latest/plugins/traffic-split.md
+++ b/docs/zh/latest/plugins/traffic-split.md
@@ -6,7 +6,7 @@ keywords:
- Traffic Split
- 灰度发布
- 蓝绿发布
-description: 本文介绍了 Apache APISIX traffic-split
插件的相关操作，你可以使用此插件动态地将部分流量引导至各种上游服务。
+description: traffic-split 插件根据条件和/或权重将流量引导至各种上游服务。它提供了一种动态灵活的方法来实施发布策略和管理流量。
---
<!--
@@ -28,11 +28,13 @@ description: 本文介绍了 Apache APISIX traffic-split 插件的相关操作
#
-->
-## 描述
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/traffic-split"; />
+</head>
-`traffic-split` 插件可以通过配置 `match` 和 `weighted_upstreams`
属性，从而动态地将部分流量引导至各种上游服务。该插件可应用于灰度发布和蓝绿发布的场景。
+## 描述
-`match` 属性是用于引导流量的自定义规则，`weighted_upstreams` 属性则用于引导流量的上游服务。当一个请求被 `match`
属性匹配时，它将根据配置的 `weights` 属性被引导至上游服务。你也可以不使用 `match` 属性，只根据 `weighted_upstreams`
属性来引导所有流量。
+`traffic-split` 插件根据条件和/或权重将流量引导至各种上游服务。它提供了一种动态且灵活的方法来实施发布策略和管理流量。
:::note 注意
@@ -42,40 +44,27 @@ description: 本文介绍了 Apache APISIX traffic-split 插件的相关操作
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
-| ---------------------- | --------------| ------ | ------ | ------
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| rules.match | array[object] | 否 | | |
匹配规则列表，默认为空且规则将被无条件执行。
|
-| rules.match.vars | array[array] | 否 | | |
由一个或多个 `{var, operator, val}` 元素组成的列表，例如：`{"arg_name", "==", "json"}`，表示当前请求参数
`name` 是 `json`。这里的 `var` 与 NGINX 内部自身变量命名是保持一致，所以也可以使用 `request_uri`、`host`
等；对于已支持的运算符，具体用法请参考
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 的
`operator-list` 部分。 |
-| rules.weighted_upstreams | array[object] | 否 | | |
上游配置规则列表。
|
-| weighted_upstreams.upstream_id | string/integer | 否 | | |
通过上游 `id` 绑定对应上游。
|
-| weighted_upstreams.upstream | object | 否 | | | 上游配置信息。
|
-| upstream.type | enum | 否 | roundrobin | [roundrobin,
chash] | 流量引导机制的类型；`roundrobin` 表示支持权重的负载，`chash` 表示使用一致性哈希。
|
-| upstream.hash_on | enum | 否 | vars | | 该属性仅当
`upstream.type` 是 `chash` 时有效。支持的类型有 `vars`（NGINX 内置变量），`header`（自定义
header），`cookie`，`consumer`，`vars_combinations`。更多信息请参考
[Upstream](../admin-api.md#upstream) 用法。
|
-| upstream.key | string | 否 | | | 该属性仅当
`upstream.type` 是 `chash` 时有效。根据 `hash_on` 和 `key` 来查找对应的 Node `id`。更多信息请参考
[Upstream](../admin-api.md#upstream) 用法。
|
-| upstream.nodes | object | 否 | | |
哈希表，键是上游节点的 IP 地址与可选端口的组合，值是节点的权重。将 `weight` 设置为 `0` 表示一个请求永远不会被转发到该节点。
|
-| upstream.timeout | object | 否 | 15 | |
发送和接收消息的超时时间（单位为秒）。
|
-| upstream.pass_host | enum | 否 | "pass" | ["pass", "node",
"rewrite"] | 当请求被转发到上游时配置 `host`。`pass` 代表将客户端的 `host` 透明传输给上游；`node` 代表使用
`upstream` Node 中配置的 `host`； `rewrite` 代表使用配置项 `upstream_host` 的值。
|
-| upstream.name | string | 否 | | | 标识上游服务名称、使用场景等。
|
-| upstream.upstream_host | string | 否 | | | 上游服务请求的
`host`，仅当 `pass_host` 属性配置为 `rewrite` 时生效。
|
-| weighted_upstreams.weight | integer | 否 | weight = 1 | |
根据 `weight` 值做流量划分，多个 `weight` 之间使用 `roundrobin` 算法划分。
|
-
-:::note 注意
-
-目前 `weighted_upstreams.upstream` 的配置不支持
`service_name`、`discovery_type`、`checks`、`retries`、`retry_timeout`、`desc`、`labels`、`create_time`
和 `update_time` 等字段。如果你需要使用这些字段，可以在创建上游对象时指定这些字段，然后在该插件中配置
`weighted_upstreams.upstream_id` 属性即可。
-
-:::
-
-:::info 重要
-
-在 `match` 属性中，变量中的表达式以 AND 方式关联，多个变量以 OR 方式关联。
-
-如果你仅配置了 `weight` 属性，那么它将会使用该 Route 或 Service 中的上游服务的权重。
-
-:::
-
-## 启用插件
-
-以下示例展示了如何在指定路由上启用 `traffic-split` 插件，并通过插件中的 `upstream` 属性配置上游信息：
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ---------------------- | --------------| ------ | ------ | ------
|--------------------------------------------------------
--------------------------------------------------
--------------------------------------------------
--------------------------------------------------
--------------------------------------------------|
+| rules.match | array[object] | 否 | | | 要执行的一对或多对匹配条件和操作的数组。 |
+| rules.match | array[object] | 否 | | | 条件流量分割的匹配规则。 |
+| rules.match.vars | array[array] | 否 | | | 以
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)
形式包含一个或多个匹配条件的数组，用于有条件地执行插件。 |
+| rules.weighted_upstreams | array[object] | 否 | | | 上游配置列表。 |
+| rules.weighted_upstreams.upstream_id | 字符串/整数 | 否 | | | 配置的上游对象的 ID。 |
+| rules.weighted_upstreams.weight | 整数 | 否 | weight = 1 | | 每个上游的权重。 |
+| rules.weighted_upstreams.upstream | object | 否 | | |
上游配置。此处不支持某些上游配置选项。这些字段为
`service_name`、`discovery_type`、`checks`、`retries`、`retry_timeout`、`desc` 和
`labels`。作为解决方法，您可以创建一个上游对象并在 `upstream_id` 中配置它。|
+| rules.weighted_upstreams.upstream.type | array | 否 | roundrobin |
[roundrobin, chash] | 流量分割算法。`roundrobin` 用于加权循环，`chash` 用于一致性哈希。|
+| rules.weighted_upstreams.upstream.hash_on | array | 否 | vars | | 当 `type`
为 `chash` 时使用。支持对 [NGINX
变量](https://nginx.org/en/docs/varindex.html)、headers、cookie、Consumer 或 [Nginx
变量](https://nginx.org/en/docs/varindex.html) 的组合进行哈希处理。 |
+| rules.weighted_upstreams.upstream.key | string | 否 | | | 当 `type` 为
`chash` 时使用。当 `hash_on` 设置为 `header` 或 `cookie` 时，需要 `key`。当 `hash_on` 设置为
`consumer` 时，不需要 `key`，因为消费者名称将自动用作密钥。 |
+| rules.weighted_upstreams.upstream.nodes | object | 否 | | | 上游节点的地址。 |
+| rules.weighted_upstreams.upstream.timeout | object | 否 | 15 | |
连接、发送和接收消息的超时时间（秒）。 |
+| rules.weighted_upstreams.upstream.pass_host | array | 否 | "pass" | ["pass",
"node", "rewrite"] | 决定如何传递主机名的模式。`pass` 将客户端的主机名传递给上游。`node`
传递上游节点中配置的主机。`rewrite` 传递 `upstream_host` 中配置的值。|
+| rules.weighted_upstreams.upstream.name | string | 否 | | |
用于指定服务名称、使用场景等的上游标识符。|
+| rules.weighted_upstreams.upstream.upstream_host | string | 否 | | | 当
`pass_host` 为 `rewrite` 时使用。上游的主机名。|
+
+## 示例
+
+以下示例展示了使用 `traffic-split` 插件的不同用例。
:::note
@@ -87,567 +76,562 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
- "plugins": {
- "traffic-split": {
- "rules": [
- {
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream_A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":10
- },
- "timeout": {
- "connect": 15,
- "send": 15,
- "read": 15
- }
- },
- "weight": 1
- },
- {
- "weight": 1
- }
- ]
- }
- ]
- }
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
-```
+### 实现 Canary 发布
+
+以下示例演示了如何使用此插件实现 Canary 发布。
-如果你已经配置了一个上游对象，你可以通过插件中的 `upstream_id` 属性来绑定上游服务：
+Canary
发布是一种逐步部署，其中越来越多的流量被定向到新版本，从而实现受控和受监控的发布。此方法可确保在完全重定向所有流量之前，尽早识别和解决新版本中的任何潜在问题或错误。
+
+创建路由并使用以下规则配置 `traffic-split` 插件：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/headers",
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "weighted_upstreams": [
- {
- "upstream_id": 1,
- "weight": 1
- },
- {
- "weight": 1
- }
- ]
- }
+ "traffic-split": {
+ "rules": [
+ {
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
+ },
+ "weight": 3
+ },
+ {
+ "weight": 2
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
}
-}'
+ }'
```
-:::tip 提示
+每个 Upstream 的流量比例由该 Upstream 的权重占所有 Upstream 总权重的比例决定，这里总权重计算为：3 + 2 = 5。
-通过 `upstream_id` 方式来绑定已定义的上游，可以复用上游已存在的健康检查、重试等功能。
+因此，60% 的流量要转发到 `httpbin.org`，另外 40% 的流量要转发到 `mock.api7.ai`。
-:::
+向路由发送 10 个连续请求来验证：
-:::note 注意
+```shell
+resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/headers"; -sL) && \
+ count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+ count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+ echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
+```
-`weighted_upstreams` 属性支持同时使用 `upstream` 和 `upstream_id` 两种配置方式。
+您应该会看到类似以下内容的响应：
-:::
+```text
+httpbin.org: 6, mock.api7.ai: 4
+```
+
+相应地调整上游权重以完成金丝雀发布。
-## 测试插件
+### 实现蓝绿部署
-### 灰度发布
+以下示例演示如何使用此插件实现蓝绿部署。
-灰度发布（又名金丝雀发布）是指在已经上线与未上线服务之间，能够平滑过渡的一种发布方式。在其上可以进行 A/B 测试，即让一部分用户继续用产品特性
A，一部分用户开始用产品特性 B。如果用户对特性 B 没有什么反对意见，那么逐步扩大范围，把所有用户都迁移到特性 B 上面来。
+蓝绿部署是一种部署策略，涉及维护两个相同的环境：蓝色和绿色。蓝色环境指的是当前的生产部署，绿色环境指的是新的部署。一旦绿色环境经过测试可以投入生产，流量将被路由到绿色环境，使其成为新的生产部署。
-以下示例展示了如何通过配置 `weighted_upstreams` 的 `weight` 属性来实现流量分流。按 3:2 的权重流量比例进行划分，其中
60% 的流量到达运行在 `1981` 端口上的上游服务，40% 的流量到达运行在 `1980` 端口上的上游服务：
+创建路由并配置 `traffic-split` 插件，以便仅当请求包含标头 `release: new_release` 时才执行插件以重定向流量：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/headers",
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream_A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":10
- },
- "timeout": {
- "connect": 15,
- "send": 15,
- "read": 15
- }
- },
- "weight": 3
- },
- {
- "weight": 2
- }
- ]
+ "traffic-split": {
+ "rules": [
+ {
+ "match": [
+ {
+ "vars": [
+ ["http_release","==","new_release"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
}
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
}
-}'
+ }'
```
-**测试**
-
-在请求 5 次后，其中会有 3 次命中运行在 `1981` 端口的插件上游服务，2 次命中运行在 `1980` 端口的路由上游服务：
+向路由发送一个带有 `release` 标头的请求：
```shell
-curl http://127.0.0.1:9080/index.html -i
+curl "http://127.0.0.1:9080/headers"; -H 'release: new_release'
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
+您应该会看到类似以下内容的响应：
+
+```json
+{
+ "headers": {
+ "Accept": "*/*",
+ "Host": "httpbin.org",
+ ...
+ }
+}
```
+向路由发送一个不带任何附加标头的请求：
+
```shell
-curl http://127.0.0.1:9080/index.html -i
+curl "http://127.0.0.1:9080/headers";
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-world 1981
+您应该会看到类似以下内容的响应：
+
+```json
+{
+ "headers": {
+ "accept": "*/*",
+ "host": "mock.api7.ai",
+ ...
+ }
+}
```
-### 蓝绿发布
+### 使用 APISIX 表达式定义 POST 请求的匹配条件
-在蓝绿发布场景中，你需要维护两个环境，一旦新的变化在蓝色环境（staging）中被测试和接受，用户流量就会从绿色环境（production）转移到蓝色环境。
+以下示例演示了如何在规则中使用
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)，在满足 POST
请求的某些条件时有条件地执行插件。
-以下示例展示了如何基于请求头来配置 `match` 规则：
+创建路由并使用以下规则配置 `traffic-split` 插件：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/post",
+ "methods": ["POST"],
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "match": [
- {
- "vars": [
- ["http_release","==","new_release"]
- ]
- }
- ],
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream_A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":10
- }
- }
- }
- ]
+ "traffic-split": {
+ "rules": [
+ {
+ "match": [
+ {
+ "vars": [
+ ["post_arg_id", "==", "1"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
}
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
}
-}'
+ }'
```
-**测试**
-
-1. 通过 `curl` 命令发出请求，如果请求带有一个值为 `new_release` 的 release
header，它就会被引导至在插件上配置的新的上游服务：
-
-```shell
-curl http://127.0.0.1:9080/index.html -H 'release: new_release' -i
-```
+发送主体为 `id=1` 的 POST 请求：
```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-world 1981
+curl "http://127.0.0.1:9080/post"; -X POST \
+ -H 'Content-Type: application/x-www-form-urlencoded' \
+ -d 'id=1'
```
-2. 否则请求会被引导至在路由上配置的另一个上游服务：
+您应该会看到类似以下内容的响应：
-```shell
-curl http://127.0.0.1:9080/index.html -H 'release: old_release' -i
+```json
+{
+ "args": {},
+ "data": "",
+ "files": {},
+ "form": {
+ "id": "1"
+ },
+ "headers": {
+ "Accept": "*/*",
+ "Content-Length": "4",
+ "Content-Type": "application/x-www-form-urlencoded",
+ "Host": "httpbin.org",
+ ...
+ },
+ ...
+}
```
+发送主体中不包含 `id=1` 的 POST 请求：
+
```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
+curl "http://127.0.0.1:9080/post"; -X POST \
+ -H 'Content-Type: application/x-www-form-urlencoded' \
+ -d 'random=string'
```
-### 自定义发布
+您应该看到请求已转发到 `mock.api7.ai`。
-你也可以通过配置规则和权重来实现自定义发布。
+### 使用 APISIX 表达式定义 AND 匹配条件
-**示例 1**
+以下示例演示了如何在规则中使用
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)，在满足多个条件时有条件地执行插件。
-下面的示例只配置了一个 `vars` 规则，流量按 3:2 的权重比例进行划分，不匹配 `vars` 的流量将被重定向到在路由上配置的上游服务：
+创建路由并配置 `traffic-split` 插件，以便仅在满足所有三个条件时重定向流量：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/headers",
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "match": [
- {
- "vars": [
- ["arg_name","==","jack"],
- ["http_user-id",">","23"],
- ["http_apisix-key","~~","[a-z]+"]
- ]
- }
- ],
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream_A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":10
- }
- },
- "weight": 3
- },
- {
- "weight": 2
- }
- ]
- }
+ "traffic-split": {
+ "rules": [
+ {
+ "match": [
+ {
+ "vars": [
+ ["arg_name","==","jack"],
+ ["http_user-id",">","23"],
+ ["http_apisix-key","~~","[a-z]+"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
+ },
+ "weight": 3
+ },
+ {
+ "weight": 2
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
}
-}'
+ }'
```
-**测试**
+如果满足条件，则 60% 的流量应定向到 `httpbin.org`，另外 40% 的流量应定向到
`mock.api7.ai`。如果不满足条件，则所有流量都应定向到 `mock.api7.ai`。
-1. 通过 `curl` 命令发出请求，在 `match` 规则校验通过后，将会有 60% 的请求被引导至插件 `1981` 端口的上游服务，40%
的请求被引导至路由 `1980` 端口的上游服务：
+发送 10 个满足所有条件的连续请求以验证：
```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' \
--H 'user-id:30' -H 'apisix-key: hello' -i
+resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/headers?name=jack"; -H
'user-id: 30' -H 'apisix-key: helloapisix' -sL) && \
+ count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+ count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+ echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-在请求 5 次后，其中会有 3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务：
+您应该会看到类似以下内容的响应：
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-world 1981
+```text
+httpbin.org: 6, mock.api7.ai: 4
```
+连续发送 10 个不满足条件的请求进行验证：
+
```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
+resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/headers?name=random";
-sL) && \
+ count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+ count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+ echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-2. 如果 `match` 规则校验失败（如缺少请求头 `apisix-key`）, 那么请求将被引导至路由的 `1980` 端口的上游服务：
+您应该会看到类似以下内容的响应：
-```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' \
--H 'user-id:30' -i
+```text
+httpbin.org: 0, mock.api7.ai: 10
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
-```
+### 使用 APISIX 表达式定义或匹配条件
-**示例 2**
+以下示例演示了如何在规则中使用
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)，在满足任一条件集时有条件地执行插件。
-下面的示例配置了多个 `vars` 规则，流量按 3:2 的权重比例进行划分，不匹配 `vars` 的流量将被重定向到在路由上配置的上游服务：
+创建路由并配置 `traffic-split` 插件，以在满足任一配置条件集时重定向流量：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/headers",
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "match": [
- {
- "vars": [
- ["arg_name","==","jack"],
- ["http_user-id",">","23"],
- ["http_apisix-key","~~","[a-z]+"]
- ]
- },
- {
- "vars": [
- ["arg_name2","==","rose"],
- ["http_user-id2","!",">","33"],
- ["http_apisix-key2","~~","[a-z]+"]
- ]
- }
- ],
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream_A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":10
- }
- },
- "weight": 3
- },
- {
- "weight": 2
- }
- ]
- }
+ "traffic-split": {
+ "rules": [
+ {
+ "match": [
+ {
+ "vars": [
+ ["arg_name","==","jack"],
+ ["http_user-id",">","23"],
+ ["http_apisix-key","~~","[a-z]+"]
+ ]
+ },
+ {
+ "vars": [
+ ["arg_name2","==","rose"],
+ ["http_user-id2","!",">","33"],
+ ["http_apisix-key2","~~","[a-z]+"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
+ },
+ "weight": 3
+ },
+ {
+ "weight": 2
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
}
-}'
+ }'
```
-**测试**
-
-1. 通过 `curl` 命令发出请求，如果两个 `vars` 表达式均匹配成功，`match` 规则校验通过后，将会有 60% 的请求被引导至插件
`1981` 端口的上游服务，40% 的请求命中到路由的 `1980` 端口的上游服务：
-
-```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack&name2=rose' \
--H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2:
world' -i
-```
+或者，您也可以使用
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 中的 OR
运算符来实现这些条件。
-在请求 5 次后，其中会有 3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务：
+如果满足条件，则 60% 的流量应定向到 `httpbin.org`，其余 40% 应定向到
`mock.api7.ai`。如果不满足条件，则所有流量都应定向到 `mock.api7.ai`。
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-world 1981
-```
+发送 10 个满足第二组条件的连续请求以验证：
```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
+resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/headers?name2=rose"; -H
'user-id:30' -H 'apisix-key2: helloapisix' -sL) && \
+ count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+ count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+ echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-2. 如果第二个 `vars` 的表达式匹配失败（例如缺少 `name2` 请求参数），`match` 规则校验通过后，效果将会与上一种相同。即有 60%
的请求被引导至插件 `1981` 端口的上游服务，40% 的请求命中到路由的 `1980` 端口的上游服务：
+您应该会看到类似以下内容的响应：
-```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' \
--H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2:
world' -i
+```json
+httpbin.org: 6, mock.api7.ai: 4
```
-在请求 5 次后，其中会有 3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务：
+发送 10 个连续的不满足任何一组条件的请求来验证：
```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-world 1981
+resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/headers?name=random";
-sL) && \
+ count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+ count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+ echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
-```
-
-3. 如果两个 `vars` 的表达式均匹配失败（如缺少 `name` 和 `name2` 请求参数），`match` 规则会校验失败，请求将被引导至路由的
`1980` 端口的上游服务：
+您应该会看到类似以下内容的响应：
-```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' -i
+```json
+httpbin.org: 0, mock.api7.ai: 10
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-...
-hello 1980
-```
+### 为不同的上游配置不同的规则
-### 匹配规则与上游对应
+以下示例演示了如何在规则集和上游之间设置一对一映射。
-以下示例展示了如何配置多个 `rules` 属性，实现不同的匹配规则与上游一一对应。当请求头 `x-api-id` 为 `1` 时，请求会被引导至
`1981` 端口的上游服务；当 `x-api-id` 为 `2` 时，请求会被引导至 `1982` 端口的上游服务；否则请求会被引导至 `1980`
端口的上游服务：
+创建一个路由并使用以下匹配规则配置 `traffic-split` 插件，以便在请求包含标头 `x-api-id: 1` 或 `x-api-id: 2`
时将流量重定向到相应的上游服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/hello",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -d '{
+ "uri": "/headers",
+ "id": "traffic-split-route",
"plugins": {
- "traffic-split": {
- "rules": [
- {
- "match": [
- {
- "vars": [
- ["http_x-api-id","==","1"]
- ]
- }
- ],
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream-A",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1981":1
- }
- },
- "weight": 3
- }
- ]
+ "traffic-split": {
+ "rules": [
+ {
+ "match": [
+ {
+ "vars": [
+ ["http_x-api-id","==","1"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "httpbin.org:443":1
+ }
},
- {
- "match": [
- {
- "vars": [
- ["http_x-api-id","==","2"]
- ]
- }
- ],
- "weighted_upstreams": [
- {
- "upstream": {
- "name": "upstream-B",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1982":1
- }
- },
- "weight": 3
- }
- ]
- }
+ "weight": 1
+ }
+ ]
+ },
+ {
+ "match": [
+ {
+ "vars": [
+ ["http_x-api-id","==","2"]
+ ]
+ }
+ ],
+ "weighted_upstreams": [
+ {
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "pass_host": "node",
+ "nodes": {
+ "mock.api7.ai:443":1
+ }
+ },
+ "weight": 1
+ }
]
- }
+ }
+ ]
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "nodes": {
+ "postman-echo.com:443": 1
+ },
+ "scheme": "https",
+ "pass_host": "node"
}
-}'
+ }'
```
-**测试**
-
-1. 通过 `curl` 命令发出请求，请求头 `x-api-id` 为 `1`，则会命中 `1980` 端口的服务：
+发送带有标头 `x-api-id: 1` 的请求：
```shell
-curl http://127.0.0.1:9080/hello -H 'x-api-id: 1'
+curl "http://127.0.0.1:9080/headers"; -H 'x-api-id: 1'
```
-```shell
-1981
-```
+您应该会看到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
-2. 如果请求头 `x-api-id` 为 `2`，则会命中 `1982` 端口的服务：
-
-```shell
-curl http://127.0.0.1:9080/hello -H 'x-api-id: 2'
+```json
+{
+ "headers": {
+ "Accept": "*/*",
+ "Host": "httpbin.org",
+ ...
+ }
+}
```
+发送带有标头 `x-api-id: 2` 的请求：
+
```shell
-1982
+curl "http://127.0.0.1:9080/headers"; -H 'x-api-id: 2'
```
-3. 如果请求头 `x-api-id` 为 `3`，规则不匹配，则会命中带 `1980` 端口的服务：
+您应该会看到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
-```shell
-curl http://127.0.0.1:9080/hello -H 'x-api-id: 3'
+```json
+{
+ "headers": {
+ "accept": "*/*",
+ "host": "mock.api7.ai",
+ ...
+ }
+}
```
+发送不带任何附加标头的请求：
+
```shell
-1980
+curl "http://127.0.0.1:9080/headers";
```
-## 删除插件
-
-当你需要删除该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+您应该会看到类似以下内容的响应：
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
+```json
{
- "uri": "/index.html",
- "plugins": {},
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
+ "headers": {
+ "accept": "*/*",
+ "host": "postman-echo.com",
+ ...
+ }
+}
```
