This is an automated email from the ASF dual-hosted git repository.
Yilialinn 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 24a2a23dc docs: update traffic-split plugin attribute types and valid
values (#13173)
24a2a23dc is described below
commit 24a2a23dc946215def890319ead2af98cd1b6034
Author: Yilia Lin <[email protected]>
AuthorDate: Mon Apr 20 14:13:16 2026 +0800
docs: update traffic-split plugin attribute types and valid values (#13173)
---
docs/en/latest/plugins/traffic-split.md | 1462 +++++++++++++++++++++++++++++-
docs/zh/latest/plugins/traffic-split.md | 1482 ++++++++++++++++++++++++++++++-
2 files changed, 2904 insertions(+), 40 deletions(-)
diff --git a/docs/en/latest/plugins/traffic-split.md
b/docs/en/latest/plugins/traffic-split.md
index a4a65b684..c33401070 100644
--- a/docs/en/latest/plugins/traffic-split.md
+++ b/docs/en/latest/plugins/traffic-split.md
@@ -32,6 +32,9 @@ description: The traffic-split Plugin directs traffic to
various Upstream servic
<link rel="canonical" href="https://docs.api7.ai/hub/traffic-split"; />
</head>
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 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.
@@ -51,16 +54,16 @@ The traffic ratio between Upstream services may be less
accurate since round rob
| 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.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 | string |
False | roundrobin | [roundrobin, chash, ewma, least_conn] | Algorithm for
traffic splitting. `roundrobin` for weighted round robin, `chash` for
consistent hashing, `ewma` for exponential weighted moving average, and
`least_conn` for least connections. |
+| rules.weighted_upstreams.upstream.hash_on | string |
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.pass_host | string |
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. |
+| rules.weighted_upstreams.upstream.upstream_host | string |
False | | | Used when `pass_host` is
`rewrite`. Host name of the Upstream. |
## Examples
@@ -80,13 +83,24 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
The following example demonstrates how to implement canary release with this
Plugin.
-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.
+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:
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/headers",
"id": "traffic-split-route",
@@ -125,7 +139,214 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-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.
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /headers
+ name: traffic-split-route
+ plugins:
+ traffic-split:
+ rules:
+ - weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[known issue]
+
+Gateway API currently has a bug where the Upstream scheme is not correctly
configured. As a result, requests are forwarded over HTTP instead of HTTPS,
which leads to the error `The plain HTTP request was sent to HTTPS port`.
+
+This issue is scheduled to be fixed in APISIX Ingress Controller version 2.0.2
and will also be addressed in API7 Ingress Controller in an upcoming release.
Until then, this example cannot be completed using Gateway API. The manifest
below is provided for reference only.
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ rules:
+ - weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: mockapi7-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /headers
+ upstreams:
+ - name: mockapi7-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ rules:
+ - weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+```
+
+</TabItem>
+
+</Tabs>
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+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.
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`.
@@ -154,9 +375,20 @@ Blue-green deployment is a deployment strategy that
involves maintaining two ide
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`:
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/headers",
"id": "traffic-split-route",
@@ -198,6 +430,216 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /headers
+ name: traffic-split-route
+ plugins:
+ traffic-split:
+ rules:
+ - match:
+ - vars:
+ - ["http_release", "==", "new_release"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[known issue]
+
+Gateway API currently has a bug where the Upstream scheme is not correctly
configured. As a result, requests are forwarded over HTTP instead of HTTPS,
which leads to the error `The plain HTTP request was sent to HTTPS port`.
+
+This issue is scheduled to be fixed in APISIX Ingress Controller version 2.0.2
and will also be addressed in API7 Ingress Controller in an upcoming release.
Until then, this example cannot be completed using Gateway API. The manifest
below is provided for reference only.
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["http_release", "==", "new_release"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: mockapi7-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /headers
+ upstreams:
+ - name: mockapi7-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["http_release", "==", "new_release"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+```
+
+</TabItem>
+
+</Tabs>
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
Send a request to the Route with the `release` header:
```shell
@@ -240,9 +682,20 @@ The following example demonstrates how to use
[lua-resty-expr](https://github.co
Create a Route and configure `traffic-split` Plugin with the following rules:
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/post",
"methods": ["POST"],
@@ -285,6 +738,221 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /post
+ methods:
+ - POST
+ name: traffic-split-route
+ plugins:
+ traffic-split:
+ rules:
+ - match:
+ - vars:
+ - ["post_arg_id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[known issue]
+
+Gateway API currently has a bug where the Upstream scheme is not correctly
configured. As a result, requests are forwarded over HTTP instead of HTTPS,
which leads to the error `The plain HTTP request was sent to HTTPS port`.
+
+This issue is scheduled to be fixed in APISIX Ingress Controller version 2.0.2
and will also be addressed in API7 Ingress Controller in an upcoming release.
Until then, this example cannot be completed using Gateway API. The manifest
below is provided for reference only.
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["post_arg_id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /post
+ method: POST
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: mockapi7-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /post
+ methods:
+ - POST
+ upstreams:
+ - name: mockapi7-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["post_arg_id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+```
+
+</TabItem>
+
+</Tabs>
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
Send a POST request with body `id=1`:
```shell
@@ -330,9 +998,20 @@ The following example demonstrates how to use
[lua-resty-expr](https://github.co
Create a Route and configure `traffic-split` Plugin to redirect traffic only
when all three conditions are satisfied:
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/headers",
"id": "traffic-split-route",
@@ -380,6 +1059,228 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /headers
+ name: traffic-split-route
+ plugins:
+ 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:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[known issue]
+
+Gateway API currently has a bug where the Upstream scheme is not correctly
configured. As a result, requests are forwarded over HTTP instead of HTTPS,
which leads to the error `The plain HTTP request was sent to HTTPS port`.
+
+This issue is scheduled to be fixed in APISIX Ingress Controller version 2.0.2
and will also be addressed in API7 Ingress Controller in an upcoming release.
Until then, this example cannot be completed using Gateway API. The manifest
below is provided for reference only.
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ 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:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: mockapi7-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /headers
+ upstreams:
+ - name: mockapi7-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ 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:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+```
+
+</TabItem>
+
+</Tabs>
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
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:
@@ -418,9 +1319,20 @@ The following example demonstrates how to use
[lua-resty-expr](https://github.co
Create a Route and configure `traffic-split` Plugin to redirect traffic when
either set of the configured conditions are satisfied:
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/headers",
"id": "traffic-split-route",
@@ -475,6 +1387,240 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /headers
+ name: 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:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[known issue]
+
+Gateway API currently has a bug where the Upstream scheme is not correctly
configured. As a result, requests are forwarded over HTTP instead of HTTPS,
which leads to the error `The plain HTTP request was sent to HTTPS port`.
+
+This issue is scheduled to be fixed in APISIX Ingress Controller version 2.0.2
and will also be addressed in API7 Ingress Controller in an upcoming release.
Until then, this example cannot be completed using Gateway API. The manifest
below is provided for reference only.
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ 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:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: mockapi7-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /headers
+ upstreams:
+ - name: mockapi7-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ 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:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+```
+
+</TabItem>
+
+</Tabs>
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
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.
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`.
@@ -511,13 +1657,24 @@ httpbin.org: 0, mock.api7.ai: 10
### Configure Different Rules for Different Upstreams
-The following example demonstrates how to set one-to-one mapping between rule
sets and upstreams.
+The following example demonstrates how to set one-to-one mapping between rule
sets and Upstreams.
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:
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/headers",
"id": "traffic-split-route",
@@ -582,6 +1739,281 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /headers
+ name: traffic-split-route
+ plugins:
+ traffic-split:
+ rules:
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 1
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "2"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+ weight: 1
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: postman-echo.com
+ port: 443
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[known issue]
+
+Gateway API currently has a bug where the Upstream scheme is not correctly
configured. As a result, requests are forwarded over HTTP instead of HTTPS,
which leads to the error `The plain HTTP request was sent to HTTPS port`.
+
+This issue is scheduled to be fixed in APISIX Ingress Controller version 2.0.2
and will also be addressed in API7 Ingress Controller in an upcoming release.
Until then, this example cannot be completed using Gateway API. The manifest
below is provided for reference only.
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: postman-echo-external-domain
+spec:
+ type: ExternalName
+ externalName: postman-echo.com
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 1
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "2"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+ weight: 1
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: postman-echo-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: postman-echo-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: postman-echo.com
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /headers
+ upstreams:
+ - name: postman-echo-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 1
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "2"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+ weight: 1
+```
+
+</TabItem>
+
+</Tabs>
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
Send a request with header `x-api-id: 1`:
```shell
diff --git a/docs/zh/latest/plugins/traffic-split.md
b/docs/zh/latest/plugins/traffic-split.md
index a460d4bfc..63d8d51e7 100644
--- a/docs/zh/latest/plugins/traffic-split.md
+++ b/docs/zh/latest/plugins/traffic-split.md
@@ -32,6 +32,9 @@ description: traffic-split 插件根据条件和/或权重将流量引导至各
<link rel="canonical" href="https://docs.api7.ai/hub/traffic-split"; />
</head>
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
`traffic-split` 插件根据条件和/或权重将流量引导至各种上游服务。它提供了一种动态且灵活的方法来实施发布策略和管理流量。
@@ -52,13 +55,13 @@ description: traffic-split 插件根据条件和/或权重将流量引导至各
| 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 | object | 否 | | |
上游配置。此处不支持某些上游配置选项。这些字段为
`service_name`、`discovery_type`、`checks`、`retries`、`retry_timeout`、`desc` 和
`labels`。作为解决方法，你可以创建一个上游对象并在 `upstream_id` 中配置它。|
+| rules.weighted_upstreams.upstream.type | string | 否 | roundrobin |
[roundrobin, chash, ewma, least_conn] | 流量分割算法。`roundrobin` 用于加权循环，`chash`
用于一致性哈希，`ewma` 用于指数加权移动平均，`least_conn` 用于最少连接。|
+| rules.weighted_upstreams.upstream.hash_on | string | 否 | 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.pass_host | string | 否 | "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` 时使用。上游的主机名。|
@@ -68,7 +71,7 @@ description: traffic-split 插件根据条件和/或权重将流量引导至各
:::note
-您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
+你可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
@@ -84,9 +87,20 @@ Canary 发布是一种逐步部署，其中越来越多的流量被定向到新
创建路由并使用以下规则配置 `traffic-split` 插件：
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/headers",
"id": "traffic-split-route",
@@ -125,6 +139,213 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /headers
+ name: traffic-split-route
+ plugins:
+ traffic-split:
+ rules:
+ - weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+```
+
+同步配置到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[已知问题]
+
+Gateway API 当前存在一个缺陷，导致上游协议未被正确配置。因此，请求会通过 HTTP 而不是 HTTPS 转发，从而触发错误 `The plain
HTTP request was sent to HTTPS port`。
+
+该问题计划在 APISIX Ingress Controller 2.0.2 版本中修复，并将在后续版本的 API7 Ingress Controller
中一并解决。在此之前，无法使用 Gateway API 完成本示例。下方清单内容仅供参考。
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ rules:
+ - weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: mockapi7-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /headers
+ upstreams:
+ - name: mockapi7-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ rules:
+ - weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+```
+
+</TabItem>
+
+</Tabs>
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
每个 Upstream 的流量比例由该 Upstream 的权重占所有 Upstream 总权重的比例决定，这里总权重计算为：3 + 2 = 5。
因此，60% 的流量要转发到 `httpbin.org`，另外 40% 的流量要转发到 `mock.api7.ai`。
@@ -138,7 +359,7 @@ resp=$(seq 10 | xargs -I{} curl
"http://127.0.0.1:9080/headers"; -sL) && \
echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```text
httpbin.org: 6, mock.api7.ai: 4
@@ -154,9 +375,20 @@ httpbin.org: 6, mock.api7.ai: 4
创建路由并配置 `traffic-split` 插件，以便仅当请求包含标头 `release: new_release` 时才执行插件以重定向流量：
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/headers",
"id": "traffic-split-route",
@@ -198,13 +430,223 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /headers
+ name: traffic-split-route
+ plugins:
+ traffic-split:
+ rules:
+ - match:
+ - vars:
+ - ["http_release", "==", "new_release"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+```
+
+同步配置到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[已知问题]
+
+Gateway API 当前存在一个缺陷，导致上游协议未被正确配置。因此，请求会通过 HTTP 而不是 HTTPS 转发，从而触发错误 `The plain
HTTP request was sent to HTTPS port`。
+
+该问题计划在 APISIX Ingress Controller 2.0.2 版本中修复，并将在后续版本的 API7 Ingress Controller
中一并解决。在此之前，无法使用 Gateway API 完成本示例。下方清单内容仅供参考。
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["http_release", "==", "new_release"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: mockapi7-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /headers
+ upstreams:
+ - name: mockapi7-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["http_release", "==", "new_release"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+```
+
+</TabItem>
+
+</Tabs>
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
向路由发送一个带有 `release` 标头的请求：
```shell
curl "http://127.0.0.1:9080/headers"; -H 'release: new_release'
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```json
{
@@ -222,7 +664,7 @@ curl "http://127.0.0.1:9080/headers"; -H 'release:
new_release'
curl "http://127.0.0.1:9080/headers";
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```json
{
@@ -240,9 +682,20 @@ curl "http://127.0.0.1:9080/headers";
创建路由并使用以下规则配置 `traffic-split` 插件：
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/post",
"methods": ["POST"],
@@ -285,6 +738,221 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /post
+ methods:
+ - POST
+ name: traffic-split-route
+ plugins:
+ traffic-split:
+ rules:
+ - match:
+ - vars:
+ - ["post_arg_id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+```
+
+同步配置到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[已知问题]
+
+Gateway API 当前存在一个缺陷，导致上游协议未被正确配置。因此，请求会通过 HTTP 而不是 HTTPS 转发，从而触发错误 `The plain
HTTP request was sent to HTTPS port`。
+
+该问题计划在 APISIX Ingress Controller 2.0.2 版本中修复，并将在后续版本的 API7 Ingress Controller
中一并解决。在此之前，无法使用 Gateway API 完成本示例。下方清单内容仅供参考。
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["post_arg_id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /post
+ method: POST
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: mockapi7-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /post
+ methods:
+ - POST
+ upstreams:
+ - name: mockapi7-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["post_arg_id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+```
+
+</TabItem>
+
+</Tabs>
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
发送主体为 `id=1` 的 POST 请求：
```shell
@@ -293,7 +961,7 @@ curl "http://127.0.0.1:9080/post"; -X POST \
-d 'id=1'
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```json
{
@@ -322,7 +990,7 @@ curl "http://127.0.0.1:9080/post"; -X POST \
-d 'random=string'
```
-您应该看到请求已转发到 `mock.api7.ai`。
+你应该看到请求已转发到 `mock.api7.ai`。
### 使用 APISIX 表达式定义 AND 匹配条件
@@ -330,9 +998,20 @@ curl "http://127.0.0.1:9080/post"; -X POST \
创建路由并配置 `traffic-split` 插件，以便仅在满足所有三个条件时重定向流量：
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/headers",
"id": "traffic-split-route",
@@ -380,6 +1059,228 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /headers
+ name: traffic-split-route
+ plugins:
+ 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:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+```
+
+同步配置到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[已知问题]
+
+Gateway API 当前存在一个缺陷，导致上游协议未被正确配置。因此，请求会通过 HTTP 而不是 HTTPS 转发，从而触发错误 `The plain
HTTP request was sent to HTTPS port`。
+
+该问题计划在 APISIX Ingress Controller 2.0.2 版本中修复，并将在后续版本的 API7 Ingress Controller
中一并解决。在此之前，无法使用 Gateway API 完成本示例。下方清单内容仅供参考。
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ 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:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: mockapi7-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /headers
+ upstreams:
+ - name: mockapi7-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ 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:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+```
+
+</TabItem>
+
+</Tabs>
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
如果满足条件，则 60% 的流量应定向到 `httpbin.org`，另外 40% 的流量应定向到
`mock.api7.ai`。如果不满足条件，则所有流量都应定向到 `mock.api7.ai`。
发送 10 个满足所有条件的连续请求以验证：
@@ -391,7 +1292,7 @@ resp=$(seq 10 | xargs -I{} curl
"http://127.0.0.1:9080/headers?name=jack"; -H 'us
echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```text
httpbin.org: 6, mock.api7.ai: 4
@@ -406,7 +1307,7 @@ resp=$(seq 10 | xargs -I{} curl
"http://127.0.0.1:9080/headers?name=random"; -sL)
echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```text
httpbin.org: 0, mock.api7.ai: 10
@@ -418,9 +1319,20 @@ httpbin.org: 0, mock.api7.ai: 10
创建路由并配置 `traffic-split` 插件，以在满足任一配置条件集时重定向流量：
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/headers",
"id": "traffic-split-route",
@@ -475,7 +1387,241 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-或者，您也可以使用
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 中的 OR
运算符来实现这些条件。
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /headers
+ name: 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:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+```
+
+同步配置到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[已知问题]
+
+Gateway API 当前存在一个缺陷，导致上游协议未被正确配置。因此，请求会通过 HTTP 而不是 HTTPS 转发，从而触发错误 `The plain
HTTP request was sent to HTTPS port`。
+
+该问题计划在 APISIX Ingress Controller 2.0.2 版本中修复，并将在后续版本的 API7 Ingress Controller
中一并解决。在此之前，无法使用 Gateway API 完成本示例。下方清单内容仅供参考。
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ 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:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: mockapi7-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /headers
+ upstreams:
+ - name: mockapi7-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ 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:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 3
+ - weight: 2
+```
+
+</TabItem>
+
+</Tabs>
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+或者，你也可以使用
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 中的 OR
运算符来实现这些条件。
如果满足条件，则 60% 的流量应定向到 `httpbin.org`，其余 40% 应定向到
`mock.api7.ai`。如果不满足条件，则所有流量都应定向到 `mock.api7.ai`。
@@ -488,7 +1634,7 @@ resp=$(seq 10 | xargs -I{} curl
"http://127.0.0.1:9080/headers?name2=rose"; -H 'u
echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```json
httpbin.org: 6, mock.api7.ai: 4
@@ -503,7 +1649,7 @@ resp=$(seq 10 | xargs -I{} curl
"http://127.0.0.1:9080/headers?name=random"; -sL)
echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```json
httpbin.org: 0, mock.api7.ai: 10
@@ -515,9 +1661,20 @@ httpbin.org: 0, mock.api7.ai: 10
创建一个路由并使用以下匹配规则配置 `traffic-split` 插件，以便在请求包含标头 `x-api-id: 1` 或 `x-api-id: 2`
时将流量重定向到相应的上游服务：
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/headers",
"id": "traffic-split-route",
@@ -582,13 +1739,288 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT
\
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: traffic-split-service
+ routes:
+ - uris:
+ - /headers
+ name: traffic-split-route
+ plugins:
+ traffic-split:
+ rules:
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 1
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "2"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+ weight: 1
+ upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: postman-echo.com
+ port: 443
+ weight: 1
+```
+
+同步配置到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::caution[已知问题]
+
+Gateway API 当前存在一个缺陷，导致上游协议未被正确配置。因此，请求会通过 HTTP 而不是 HTTPS 转发，从而触发错误 `The plain
HTTP request was sent to HTTPS port`。
+
+该问题计划在 APISIX Ingress Controller 2.0.2 版本中修复，并将在后续版本的 API7 Ingress Controller
中一并解决。在此之前，无法使用 Gateway API 完成本示例。下方清单内容仅供参考。
+
+:::
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ type: ExternalName
+ externalName: mock.api7.ai
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: postman-echo-external-domain
+spec:
+ type: ExternalName
+ externalName: postman-echo.com
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: traffic-split-plugin-config
+spec:
+ plugins:
+ - name: traffic-split
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 1
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "2"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+ weight: 1
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: traffic-split-plugin-config
+ backendRefs:
+ - name: postman-echo-external-domain
+ port: 443
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="traffic-split-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mockapi7-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: mock.api7.ai
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: postman-echo-external-domain
+spec:
+ ingressClassName: apisix
+ scheme: https
+ passHost: node
+ externalNodes:
+ - type: Domain
+ name: postman-echo.com
+ port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: traffic-split-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: traffic-split-route
+ match:
+ paths:
+ - /headers
+ upstreams:
+ - name: postman-echo-external-domain
+ plugins:
+ - name: traffic-split
+ enable: true
+ config:
+ rules:
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "1"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: httpbin.org
+ port: 443
+ weight: 1
+ weight: 1
+ - match:
+ - vars:
+ - ["http_x-api-id", "==", "2"]
+ weighted_upstreams:
+ - upstream:
+ type: roundrobin
+ scheme: https
+ pass_host: node
+ nodes:
+ - host: mock.api7.ai
+ port: 443
+ weight: 1
+ weight: 1
+```
+
+</TabItem>
+
+</Tabs>
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f traffic-split-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
发送带有标头 `x-api-id: 1` 的请求：
```shell
curl "http://127.0.0.1:9080/headers"; -H 'x-api-id: 1'
```
-您应该会看到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
+你应该会看到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
```json
{
@@ -606,7 +2038,7 @@ curl "http://127.0.0.1:9080/headers"; -H 'x-api-id: 1'
curl "http://127.0.0.1:9080/headers"; -H 'x-api-id: 2'
```
-您应该会看到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
+你应该会看到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
```json
{
@@ -624,7 +2056,7 @@ curl "http://127.0.0.1:9080/headers"; -H 'x-api-id: 2'
curl "http://127.0.0.1:9080/headers";
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```json
{
