You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/09/21 06:02:43 UTC
[apisix] branch master updated: docs(plugin): refactor traffic-split.md (#7933)
This is an automated email from the ASF dual-hosted git repository.
spacewander 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 de82bc1b5 docs(plugin): refactor traffic-split.md (#7933)
de82bc1b5 is described below
commit de82bc1b5e6f0e41de3ed07fee24b3e7eed04c38
Author: Yuedong Wu <57...@users.noreply.github.com>
AuthorDate: Wed Sep 21 14:02:37 2022 +0800
docs(plugin): refactor traffic-split.md (#7933)
---
docs/en/latest/plugins/traffic-split.md | 83 ++++-----
docs/zh/latest/plugins/traffic-split.md | 292 +++++++++++++++++++-------------
2 files changed, 216 insertions(+), 159 deletions(-)
diff --git a/docs/en/latest/plugins/traffic-split.md b/docs/en/latest/plugins/traffic-split.md
index 9f74456ad..b5df772e8 100644
--- a/docs/en/latest/plugins/traffic-split.md
+++ b/docs/en/latest/plugins/traffic-split.md
@@ -2,11 +2,13 @@
title: traffic-split
keywords:
- APISIX
- - Plugin
+ - API Gateway
- Traffic Split
- - traffic-split
-description: This document contains information about the Apache APISIX traffic-split Plugin.
+ - 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.
---
+
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -45,7 +47,7 @@ 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.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. |
@@ -80,7 +82,8 @@ If only the `weight` attribute is configured, it corresponds to the weight of th
You can configure the Plugin on a Route as shown below:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -123,7 +126,8 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
Alternatively, you can configure `upstream_id` if you have already configured an Upstream object:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -175,7 +179,8 @@ This is the process of gradually rolling out a release by splitting an increasin
To set this up, you can configure the `weight` attribute of your `weighted_upstreams` as shown below:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -226,7 +231,7 @@ curl http://127.0.0.1:9080/index.html -i
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-
+...
hello 1980
```
@@ -237,7 +242,7 @@ curl http://127.0.0.1:9080/index.html -i
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-
+...
world 1981
```
@@ -248,7 +253,8 @@ In this setup, user traffic is shifted from the "green" (production) environment
To set this up, you can configure `match` rules based on the request headers as shown below:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -297,8 +303,7 @@ curl http://127.0.0.1:9080/index.html -H 'release: new_release' -i
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
world 1981
```
@@ -309,8 +314,7 @@ curl http://127.0.0.1:9080/index.html -H 'release: old_release' -i
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
@@ -321,7 +325,8 @@ You can also make custom releases by configuring rules and setting weights.
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.
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -368,35 +373,36 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
After the rules are matched, 60% of the traffic hit the Upstream on port `1981` and 40% hit the one on `1980`.
```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' -H 'user-id:30' -H 'apisix-key: hello' -i
+curl 'http://127.0.0.1:9080/index.html?name=jack' \
+-H 'user-id:30' -H 'apisix-key: hello' -i
```
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
world 1981
```
If the rule fails to match, then the request is directed to the service on `1980`:
```shell
-curl 'http://127.0.0.1:9080/index.html?name=jack' -H 'user-id:30' -H 'apisix-key: hello' -i
+curl 'http://127.0.0.1:9080/index.html?name=jack' \
+-H 'user-id:30' -H 'apisix-key: hello' -i
```
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
In the example below, multiple `vars` rules are configured and they have an OR relationship.
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -450,52 +456,52 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
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
+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
```
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
world 1981
```
```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
+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
```
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
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:
```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
+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
```
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
world 1981
```
```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
+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
```
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
@@ -508,8 +514,7 @@ curl 'http://127.0.0.1:9080/index.html?name=jack' -i
```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
@@ -520,7 +525,8 @@ You can achieve one-to-one correspondence between rules and Upstream by configur
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:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hello",
"plugins": {
@@ -615,7 +621,8 @@ curl http://127.0.0.1:9080/hello -H 'x-api-id: 3'
To disable 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.
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {},
diff --git a/docs/zh/latest/plugins/traffic-split.md b/docs/zh/latest/plugins/traffic-split.md
index 00e76ffe2..97e87fd47 100644
--- a/docs/zh/latest/plugins/traffic-split.md
+++ b/docs/zh/latest/plugins/traffic-split.md
@@ -1,5 +1,12 @@
---
title: traffic-split
+keywords:
+ - APISIX
+ - API 网关
+ - Traffic Split
+ - 灰度发布
+ - 蓝绿发布
+description: 本文介绍了 Apache APISIX traffic-split 插件的相关操作，你可以使用此插件动态地将部分流量引导至各种上游服务。
---
<!--
@@ -23,53 +30,56 @@ title: traffic-split
## 描述
-traffic-split 插件使用户可以逐步引导各个上游之间的流量百分比。
+`traffic-split` 插件可以通过配置 `match` 和 `weighted_upstreams` 属性，从而动态地将部分流量引导至各种上游服务。该插件可应用于灰度发布和蓝绿发布的场景。
-注：由于加权循环算法（特别是在重置 wrr 状态时）的缺点，因此每个上游之间的比率可能不太准确。
+`match` 属性是用于引导流量的自定义规则，`weighted_upstreams` 属性则用于引导流量的上游服务。当一个请求被 `match` 属性匹配时，它将根据配置的 `weights` 属性被引导至上游服务。你也可以不使用 `match` 属性，只根据 `weighted_upstreams` 属性来引导所有流量。
+
+:::note 注意
+
+由于该插件使用了加权循环算法（特别是在重置 `wrr` 状态时），因此在使用该插件时，可能会存在上游服务之间的流量比例不精准现象。
+
+:::
## 属性
-| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述 |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ---------------------- | --------------| ------ | ------ | ------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| rules.match | array[object] | 可选 | | | 匹配规则列表，默认为空且规则将被无条件执行。 |
-| rules.match.vars | array[array] | 可选 | | | 由一个或多个{var, operator, val}元素组成的列表，类似这样：{{var, operator, val}, {var, operator, val}, ...}}。例如：{"arg_name", "==", "json"}，表示当前请求参数 name 是 json。这里的 var 与 Nginx 内部自身变量命名是保持一致，所以也可以使用 request_uri、host 等；对于 operator 部分，目前已支持的运算符有 ==、~=、~~、>、<、in、has 和 ! 。操作符的具体用法请看 [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 | | `hash_on` 支持的类型有 `vars`（Nginx 内置变量），`header`（自定义 header），`cookie`，`consumer`，`vars_combinations`，默认值为 `vars`。更多详细信息请参考 [upstream](../admin-api.md#upstream) 用法。 |
-| upstream.key | string | 可选 | | | 该选项只有类型是 `chash` 才有效。根据 `key` 来查找对应的 node `id`，相同的 `key` 在同一个对象中，永远返回相同 id。更多详细信息请参考 [upstream](../admin-api.md#upstream) 用法。 |
-| upstream.nodes | object | 可选 | | | 哈希表，内部元素的 key 是上游机器地址 列表，格式为地址 + Port，其中地址部 分可以是 IP 也可以是域名，⽐如 192.168.1.100:80、foo.com:80 等。 value 则是节点的权重，特别的，当权重 值为 0 有特殊含义，通常代表该上游节点 失效，永远不希望被选中。 |
-| upstream.timeout | object | 可选 | 15 | | 设置连接、发送消息、接收消息的超时时间（时间单位：秒，都默认为 15 秒）。 |
-| upstream.pass_host | enum | 可选 | "pass" | ["pass", "node", "rewrite"] | `pass`：将客户端的 host 透传给上游； `node`：使用 `upstream` node 中配置的 host； `rewrite`：使用配置项 `upstream_host` 的值 |
-| upstream.name | string | 可选 | | | 标识上游服务名称、使⽤场景等。 |
-| upstream.upstream_host | string | 可选 | | | 只在 pass_host 配置为 rewrite 时有效。 |
-| weighted_upstreams.weight | integer | 可选 | weight = 1 | | 根据 `weight` 值做流量划分，多个 weight 之间使用 roundrobin 算法划分。 |
-
-目前在 `weighted_upstreams.upstream` 的配置中，不支持的字段有：
-service_name、discovery_type、checks、retries、retry_timeout、desc、scheme、labels、create_time 和 update_time。但是你可以通过 `weighted_upstreams.upstream_id` 绑定 `upstream` 对象来实现他们。
-
-traffic-split 插件主要由 `match` 和 `weighted_upstreams` 两部分组成，`match` 是自定义的条件规则，`weighted_upstreams` 是 upstream 的配置信息。如果配置 `match` 和 `weighted_upstreams` 信息，那么在 `match` 规则校验通过后，会根据 `weighted_upstreams` 中的 `weight` 值；引导插件中各个 upstream 之间的流量比例，否则，所有流量直接到达 `route` 或 `service` 上配置的 `upstream`。当然你也可以只配置 `weighted_upstreams` 部分，这样会直接根据 `weighted_upstreams` 中的 `weight` 值，引导插件中各个 upstream 之间的流量比例。
-
-注：1、在 `match` 里，vars 中的表达式是 `and` 的关系，多个 `vars` 之间是 `or` 的关系。2、在插件的 weighted_upstreams 域中，如果存在只有 `weight` 的结构，表示 `route` 或 `service` 上的 upstream 流量权重值。例如：
-
-```json
-"weighted_upstreams": [
- ......
- {
- "weight": 2
- }
-]
-```
+| 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`、`scheme`、`labels`、`create_time` 和 `update_time` 等字段。如果你需要使用这些字段，可以在创建上游对象时指定这些字段，然后在该插件中配置 `weighted_upstreams.upstream_id` 属性即可。
+
+:::
+
+:::info 重要
-## 如何启用
+在 `match` 属性中，变量中的表达式以 AND 方式关联，多个变量以 OR 方式关联。
-创建一个路由并启用 `traffic-split` 插件，在配置插件上游信息时，有以下两种方式：
+如果你仅配置了 `weight` 属性，那么它将会使用该 Route 或 Service 中的上游服务的权重。
-1、通过插件中的 `upstream` 属性配置上游信息。
+:::
+
+## 启用插件
+
+以下示例展示了如何在指定路由上启用 `traffic-split` 插件，并通过插件中的 `upstream` 属性配置上游信息：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -109,10 +119,11 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-2、通过插件中的 `upstream_id` 属性绑定上游服务。
+如果你已经配置了一个上游对象，你可以通过插件中的 `upstream_id` 属性来绑定上游服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -141,16 +152,29 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
->注：1、通过 `upstream_id` 方式来绑定已定义的上游，它可以复用上游具有的健康检测、重试等功能。2、支持 `upstream` 和 `upstream_id` 的两种配置方式一起使用。
+:::tip 提示
+
+通过 `upstream_id` 方式来绑定已定义的上游，可以复用上游已存在的健康检查、重试等功能。
+
+:::
+
+:::note 注意
-## 示例
+`weighted_upstreams` 属性支持同时使用 `upstream` 和 `upstream_id` 两种配置方式。
+
+:::
+
+## 测试插件
### 灰度发布
-缺少 `match` 规则部分，根据插件中 `weighted_upstreams` 配置的 `weight` 值做流量分流。将 `插件的 upstream` 与 `route 的 upstream` 按 3:2 的流量比例进行划分，其中 60% 的流量到达插件中的 `1981` 端口的 upstream， 40% 的流量到达 route 上默认 `1980` 端口的 upstream。
+灰度发布（又名金丝雀发布）是指在已经上线与未上线服务之间，能够平滑过渡的一种发布方式。 在其上可以进行 A/B 测试，即让一部分用户继续用产品特性 A，一部分用户开始用产品特性 B。如果用户对特性 B 没有什么反对意见，那么逐步扩大范围，把所有用户都迁移到特性 B 上面来。
+
+以下示例展示了如何通过配置 `weighted_upstreams` 的 `weight` 属性来实现流量分流。按 3:2 的权重流量比例进行划分，其中 60% 的流量到达运行在 `1981` 端口上的上游服务，40% 的流量到达运行在 `1980` 端口上的上游服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -190,32 +214,41 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-**插件测试：**
+**测试**
+
+在请求 5 次后，其中会有 3 次命中运行在 `1981` 端口的插件上游服务，2 次命中运行在 `1980` 端口的路由上游服务：
-请求 5 次，3 次请求命中插件 1981 端口的 upstream, 2 次请求命中 `route` 的 1980 端口 upstream。
+```shell
+curl http://127.0.0.1:9080/index.html -i
+```
```shell
-$ curl http://127.0.0.1:9080/index.html -i
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-
+...
hello 1980
+```
-$ curl http://127.0.0.1:9080/index.html -i
+```shell
+curl http://127.0.0.1:9080/index.html -i
+```
+
+```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-
+...
world 1981
-
-......
```
### 蓝绿发布
-通过请求头获取 `match` 规则参数 (也可以通过请求参数获取 NGINX 变量)，在 `match` 规则匹配通过后，表示所有请求都命中到插件配置的 upstream ，否则所有请求只命中 `route` 上配置的 upstream 。
+在蓝绿发布场景中，你需要维护两个环境，一旦新的变化在蓝色环境（staging）中被测试和接受，用户流量就会从绿色环境（production）转移到蓝色环境。
+
+以下示例展示了如何基于请求头来配置 `match` 规则：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -253,38 +286,45 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-**插件测试：**
+**测试**
+
+1. 通过 `curl` 命令发出请求，如果请求带有一个值为 `new_release` 的 release header，它就会被引导至在插件上配置的新的上游服务：
-`match` 规则匹配通过，所有请求都命中插件配置的 1981 端口 upstream ：
+```shell
+curl http://127.0.0.1:9080/index.html -H 'release: new_release' -i
+```
```shell
-$ curl http://127.0.0.1:9080/index.html -H 'release: new_release' -i
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
world 1981
```
-`match` 规则匹配失败，所有请求都命中 `route` 上配置的 1980 端口 upstream ：
+2. 否则请求会被引导至在路由上配置的另一个上游服务：
+
+```shell
+curl http://127.0.0.1:9080/index.html -H 'release: old_release' -i
+```
```shell
-$ curl http://127.0.0.1:9080/index.html -H 'release: old_release' -i
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
### 自定义发布
-`match` 中可以设置多个 `vars` 规则，`vars` 中的多个表达式之间是 `and` 的关系， 多个 `vars` 规则之间是 `or` 的关系；只要其中一个 vars 规则通过，则整个 `match` 通过。
+你也可以通过配置规则和权重来实现自定义发布。
+
+**示例 1**
-**示例 1：只配置了一个 `vars` 规则， `vars` 中的多个表达式是 `and` 的关系。在 `weighted_upstreams` 中根据 `weight` 值将流量按 3:2 划分，其中只有 `weight` 值的部分表示 `route` 上的 upstream 所占的比例。 当 `match` 匹配不通过时，所有的流量只会命中 route 上的 upstream 。**
+下面的示例只配置了一个 `vars` 规则，流量按 3:2 的权重比例进行划分，不匹配 `vars` 的流量将被重定向到在路由上配置的上游服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -328,51 +368,52 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-插件设置了请求的 `match` 规则及端口为 `1981` 的 upstream，route 上具有端口为 `1980` 的 upstream。
+**测试**
-**插件测试：**
+1. 通过 `curl` 命令发出请求，在 `match` 规则校验通过后，将会有 60% 的请求被引导至插件 `1981` 端口的上游服务，40% 的请求被引导至路由 `1980` 端口的上游服务：
->1、在 `match` 规则校验通过后，60% 的请求命中到插件的 1981 端口的 upstream, 40% 的请求命中到 `route` 的 1980 端口的 upstream。
+```shell
+curl 'http://127.0.0.1:9080/index.html?name=jack' \
+-H 'user-id:30' -H 'apisix-key: hello' -i
+```
-match 规则校验成功， 命中端口为 `1981` 的 upstream。
+在请求 5 次后，其中会有 3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务：
```shell
-$ curl 'http://127.0.0.1:9080/index.html?name=jack' -H 'user-id:30' -H 'apisix-key: hello' -i
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
world 1981
```
-match 规则校验失败，命中默认端口为 `1980` 的 upstream。
-
```shell
-$ curl 'http://127.0.0.1:9080/index.html?name=jack' -H 'user-id:30' -H 'apisix-key: hello' -i
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
-在请求 5 次后，3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务。
+2. 如果 `match` 规则校验失败（如缺少请求头 `apisix-key`）, 那么请求将被引导至路由的 `1980` 端口的上游服务：
->2、`match` 规则校验失败 (缺少请求头 `apisix-key` ), 响应都为默认 upstream 的数据 `hello 1980`。
+```shell
+curl 'http://127.0.0.1:9080/index.html?name=jack' \
+-H 'user-id:30' -i
+```
```shell
-$ curl 'http://127.0.0.1:9080/index.html?name=jack' -H 'user-id:30' -i
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
-**示例 2：配置多个 `vars` 规则， `vars` 中的多个表达式是 `and` 的关系， 多个 `vars` 之间是 `or` 的关系。根据 `weighted_upstreams` 中的 `weight` 值将流量按 3:2 划分，其中只有 `weight` 值的部分表示 route 上的 upstream 所占的比例。 当 `match` 匹配不通过时，所有的流量只会命中 route 上的 upstream 。**
+**示例 2**
+
+下面的示例配置了多个 `vars` 规则，流量按 3:2 的权重比例进行划分，不匹配 `vars` 的流量将被重定向到在路由上配置的上游服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -423,75 +464,74 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-插件设置了请求的 `match` 规则及端口为 `1981` 的 upstream，route 上具有端口为 `1980` 的 upstream 。
+**测试**
+
+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
+```
->1、两个 `vars` 的表达式匹配成功， `match` 规则校验通过后，60% 的请求命中到插件的 1981 端口 upstream, 40% 的请求命中到 `route` 的 1980 端口 upstream。
+在请求 5 次后，其中会有 3 次命中 `1981` 端口的服务，2 次命中 `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
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
world 1981
```
```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
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
-在请求 5 次后，3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务。
+2. 如果第二个 `vars` 的表达式匹配失败（例如缺少 `name2` 请求参数），`match` 规则校验通过后，效果将会与上一种相同。即有 60% 的请求被引导至插件 `1981` 端口的上游服务，40% 的请求命中到路由的 `1980` 端口的上游服务：
->2、第二个 `vars` 的表达式匹配失败（缺少 `name2` 请求参数），`match` 规则校验通过后，60% 的请求命中到插件的 1981 端口 upstream, 40% 的请求流量命中到 `route` 的 1980 端口 upstream。
+```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
+```
+
+在请求 5 次后，其中会有 3 次命中 `1981` 端口的服务，2 次命中 `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
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
world 1981
```
```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
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
-在请求 5 次后，3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务。
+3. 如果两个 `vars` 的表达式均匹配失败（如缺少 `name` 和 `name2` 请求参数），`match` 规则会校验失败，请求将被引导至路由的 `1980` 端口的上游服务：
->3、两个 `vars` 的表达式校验失败（缺少 `name` 和 `name2` 请求参数），`match` 规则校验失败，响应都为默认 `route` 的 upstream 数据 `hello 1980`。
+```shell
+curl 'http://127.0.0.1:9080/index.html?name=jack' -i
+```
```shell
-$ curl 'http://127.0.0.1:9080/index.html?name=jack' -i
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 端口的上游（上游响应数据为对应的端口号）。
+以下示例展示了如何配置多个 `rules` 属性，实现不同的匹配规则与上游一一对应。当请求头 `x-api-id` 为 `1` 时，请求会被引导至 `1981` 端口的上游服务；当 `x-api-id` 为 `2` 时，请求会被引导至 `1982` 端口的上游服务；否则请求会被引导至 `1980` 端口的上游服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hello",
"plugins": {
@@ -551,35 +591,45 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-**测试插件：**
+**测试**
-请求头 `x-api-id` 等于 1，命中带 1981 端口的上游。
+1. 通过 `curl` 命令发出请求，请求头 `x-api-id` 为 `1`，则会命中 `1980` 端口的服务：
+
+```shell
+curl http://127.0.0.1:9080/hello -H 'x-api-id: 1'
+```
```shell
-$ curl http://127.0.0.1:9080/hello -H 'x-api-id: 1'
1981
```
-请求头 `x-api-id` 等于 2，命中带 1982 端口的上游。
+2. 如果请求头 `x-api-id` 为 `2`，则会命中 `1982` 端口的服务：
+
+```shell
+curl http://127.0.0.1:9080/hello -H 'x-api-id: 2'
+```
```shell
-$ curl http://127.0.0.1:9080/hello -H 'x-api-id: 2'
1982
```
-请求头 `x-api-id` 等于 3，规则不匹配，命中带 1980 端口的上游。
+3. 如果请求头 `x-api-id` 为 `3`，规则不匹配，则会命中带 `1980` 端口的服务：
+
+```shell
+curl http://127.0.0.1:9080/hello -H 'x-api-id: 3'
+```
```shell
-$ curl http://127.0.0.1:9080/hello -H 'x-api-id: 3'
1980
```
## 禁用插件
-当你想去掉 traffic-split 插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {},