doc: add docs about traffic split

apache · Mar 19, 2021 · 3ac2766 · 3ac2766
1 parent d0d5d8b
commit 3ac2766
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 14 deletions.
diff --git a/docs/en/latest/concepts/apisix_route.md b/docs/en/latest/concepts/apisix_route.md
@@ -85,9 +85,9 @@ spec:
         - /
         methods:
         - GET
-      backend:
-        serviceName: foo
-        servicePort: 80
+      backends:
+        - serviceName: foo
+          servicePort: 80
 ```
 
 The `nginxVars` allows user to configure match conditions with arbitrary predicates in HTTP, such as queries, HTTP headers and etc.
@@ -108,9 +108,9 @@ spec:
           - subject: arg_id
             op: Equal
             value: 2143
-      backend:
-        serviceName: foo
-        servicePort: 80
+      backends:
+        - serviceName: foo
+          servicePort: 80
 ```
 
 The above configuration configures an extra route match condition, which asks the
@@ -139,12 +139,46 @@ spec:
           - /*
         methods:
           - GET
-      backend:
-        serviceName: foo
-        servicePort: 80
-        resolveGranularity: service
+      backends:
+        - serviceName: foo
+          servicePort: 80
+          resolveGranularity: service
 ```
 
+Weight Based Traffic Split
+--------------------------
+
+There can more than one backend specified in one route rule,
+when multiple backends co-exist there, the traffic split based on weights
+will be applied (which actually uses the [traffic-split](http://apisix.apache.org/docs/apisix/plugins/traffic-split/) plugin in Apache APISIX).
+You can specify weight for each backend, the default weight is `100`.
+
+```yaml
+apiVersion: apisix.apache.org/v2alpha1
+kind: ApisixRoute
+metadata:
+  name: method-route
+spec:
+  http:
+    - name: method
+      match:
+        paths:
+          - /*
+        methods:
+          - GET
+      backends:
+        - serviceName: foo
+          servicePort: 80
+          weight: 100
+        - serviceName: bar
+          servicePort: 81
+          weight: 50
+```
+
+The above `ApisixRoute` has one route rule, which contains two backends `foo` and `bar`, the
+weight ratio is `100:50`, which means `2/3` requests will be sent to service `foo` and `1/3` requests
+will be proxied to serivce `bar`.
+
 Plugins
 -------
 
@@ -164,9 +198,9 @@ spec:
         - local.httpbin.org
         paths:
           - /*
-      backend:
-        serviceName: foo
-        servicePort: 80
+      backends:
+        - serviceName: foo
+          servicePort: 80
       plugins:
         - name: cors
           enable: true

diff --git a/docs/en/latest/references/apisix_route_v2alpha1.md b/docs/en/latest/references/apisix_route_v2alpha1.md
@@ -40,10 +40,15 @@ Meaning of each field in the spec of ApisixRoute are followed, the top level fie
 | http[].match.nginxVars[].op | string | Expression operator, see [Expression Operators](#expression-operators) for the detail of enumerations.
 | http[].match.nginxVars[].value | string | Expected expression result, it's exclusive with `http[].match.nginxVars[].set`.
 | http[].match.nginxVars[].set | array | Expected expression result set, only used when the operator is `In` or `NotIn`, it's exclusive with `http[].match.nginxVars[].value`.
-| http[].backend | object | The backend service
+| http[].backend | object | The backend service. Deprecated: use http[].backends instead.
 | http[].backend.serviceName | string | The backend service name, note the service and ApisixRoute should be created in the same namespace. Cross namespace referencing is not allowed.
 | http[].backend.servicePort | integer or string | The backend service port, can be the port number of the name defined in the service object.
 | http[].backend.resolveGranualrity | string | See [Service Resolve Granularity](#service-resolve-granularity) for the details.
+| http[].backends | object | The backend services. When the number of backends more than one, weight based traffic split policy will be applied to shifting traffic between these backends.
+| http[].backends[].serviceName | string | The backend service name, note the service and ApisixRoute should be created in the same namespace. Cross namespace referencing is not allowed.
+| http[].backends[].servicePort | integer or string | The backend service port, can be the port number of the name defined in the service object.
+| http[].backends[].resolveGranualrity | string | See [Service Resolve Granularity](#service-resolve-granularity) for the details.
+| http[].backends[].weight | int | The backend weight, which is critical when shifting traffic between multiple backends, default is `100`. Weight is ignored when there is only one backend.
 | http[].plugins | array | A series of APISIX plugins that will be executed once this route rule is matched |
 | http[].plugins[].name | string | The plugin name, see [docs](http://apisix.apache.org/docs/apisix/getting-started) for learning the available plugins.
 | http[].plugins[].enable | boolean | Whether the plugin is in use |