traffic-split

This is done by configuring match, which are custom rules for splitting traffic, and weighted_upstreams which is a set of Upstreams to direct traffic to.

When a request is matched based on the match attribute configuration, it will be directed to the Upstreams based on their configured weights. You can also omit using the match attribute and direct all traffic based on weighted_upstreams.

note

The traffic ratio between Upstream services may be less accurate since round robin algorithm is used to direct traffic (especially when the state is reset).

traffic-split - 图2note

Some of the configuration fields supported in Upstream are not supported in weighted_upstreams.upstream. These fields are service_name, discovery_type, checks, retries, retry_timeout, desc, scheme, labels, create_time, and update_time.

As a workaround, you can create an Upstream object and configure it in weighted_upstreams.upstream_id to achieve these functionalities.

IMPORTANT

In the match attribute configuration, the expression in variable is related as AND whereas multiple variables are related by OR.

If only the weight attribute is configured, it corresponds to the weight of the Upstream service configured on the Route or Service. You can see this in action below.

You can configure the Plugin on a Route as shown below:

Alternatively, you can configure upstream_id if you have already configured an Upstream object:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "uri": "/index.html",
  5.     "plugins": {
  6.         "traffic-split": {
  7.             "rules": [
  8.                 {
  9.                     "weighted_upstreams": [
  10.                         {
  11.                             "upstream_id": 1,
  12.                             "weight": 1
  13.                         },
  14.                         {
  15.                             "weight": 1
  16.                         }
  17.                     ]
  18.                 }
  19.             ]
  20.         }
  21.     },
  22.     "upstream": {
  23.             "type": "roundrobin",
  24.             "nodes": {
  25.                 "127.0.0.1:1980": 1
  26.             }
  27.     }
  28. }'
traffic-split - 图4tip

Configure via upstream_id to reuse Upstream’s health detection, retires, and other functions.

note

The examples below shows different use cases for using the traffic-split Plugin.

This is the process of gradually rolling out a release by splitting an increasing percentage of traffic to the new release until all traffic is directed to the new release.

To set this up, you can configure the weight attribute of your weighted_upstreams as shown below:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "uri": "/index.html",
  5.     "plugins": {
  6.         "traffic-split": {
  7.             "rules": [
  8.                 {
  9.                     "weighted_upstreams": [
  10.                         {
  11.                             "upstream": {
  12.                                 "name": "upstream_A",
  13.                                 "type": "roundrobin",
  14.                                 "nodes": {
  15.                                     "127.0.0.1:1981":10
  16.                                 },
  17.                                 "timeout": {
  18.                                     "connect": 15,
  19.                                     "send": 15,
  20.                                     "read": 15
  21.                                 }
  22.                             },
  23.                             "weight": 3
  24.                         },
  25.                         {
  26.                             "weight": 2
  27.                         }
  28.                     ]
  29.                 }
  30.             ]
  31.         }
  32.     },
  33.     "upstream": {
  34.             "type": "roundrobin",
  35.             "nodes": {
  36.                 "127.0.0.1:1980": 1
  37.             }
  38.     }
  39. }'

Here, the weights are in the ratio 3:2 which means that 60% of the traffic reaches the Upstream service running on :1981 (Plugin’s Upstream) and 40% reaches the service running on :1980 which is the Route’s Upstream service.

Now to test this configuration, if you make 5 requests, 3 will hit one service and 2 will hit the other:

  1. curl http://127.0.0.1:9080/index.html -i
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  4. hello 1980
  1. curl http://127.0.0.1:9080/index.html -i
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. ...
  4. world 1981

In this setup, user traffic is shifted from the “green” (production) environment to the “blue” (staging) environment once the new changes have been tested and accepted within the blue environment.

To set this up, you can configure match rules based on the request headers as shown below:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "uri": "/index.html",
  5.     "plugins": {
  6.         "traffic-split": {
  7.             "rules": [
  8.                 {
  9.                     "match": [
  10.                             "vars": [
  11.                                 ["http_release","==","new_release"]
  12.                             ]
  13.                         }
  14.                     ],
  15.                     "weighted_upstreams": [
  16.                         {
  17.                             "upstream": {
  18.                                 "name": "upstream_A",
  19.                                 "type": "roundrobin",
  20.                                 "nodes": {
  21.                                     "127.0.0.1:1981":10
  22.                                 }
  23.                             }
  24.                         }
  25.                     ]
  26.                 }
  27.             ]
  28.         }
  29.     },
  30.     "upstream": {
  31.             "type": "roundrobin",
  32.             "nodes": {
  33.                 "127.0.0.1:1980": 1
  34.             }
  35.     }
  36. }'

Here, if the request comes with a release header with value new_release it is directed to the new Upstream.

Now if you send a request with new_release as the value for the release header, it will be directed to one Upstream and other requests will be directed to another Upstream.

  1. curl http://127.0.0.1:9080/index.html -H 'release: new_release' -i
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. ...
  4. world 1981
  1. curl http://127.0.0.1:9080/index.html -H 'release: old_release' -i
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. ...
  4. hello 1980

You can also make custom releases by configuring rules and setting weights.

After the rules are matched, 60% of the traffic hit the Upstream on port 1981 and 40% hit the one on 1980.

  1. curl 'http://127.0.0.1:9080/index.html?name=jack' \
  2. -H 'user-id:30' -H 'apisix-key: hello' -i
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. ...
  4. world 1981

If the rule fails to match, then the request is directed to the service on 1980:

  1. curl 'http://127.0.0.1:9080/index.html?name=jack' \
  2. -H 'user-id:30' -H 'apisix-key: hello' -i
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. ...
  4. hello 1980

In the example below, multiple vars rules are configured and they have an OR relationship.

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "uri": "/index.html",
  5.     "plugins": {
  6.         "traffic-split": {
  7.             "rules": [
  8.                 {
  9.                     "match": [
  10.                         {
  11.                             "vars": [
  12.                                 ["arg_name","==","jack"],
  13.                                 ["http_user-id",">","23"],
  14.                                 ["http_apisix-key","~~","[a-z]+"]
  15.                             ]
  16.                         },
  17.                         {
  18.                             "vars": [
  19.                                 ["arg_name2","==","rose"],
  20.                                 ["http_user-id2","!",">","33"],
  21.                                 ["http_apisix-key2","~~","[a-z]+"]
  22.                             ]
  23.                         }
  24.                     ],
  25.                     "weighted_upstreams": [
  26.                         {
  27.                             "upstream": {
  28.                                 "name": "upstream_A",
  29.                                 "type": "roundrobin",
  30.                                 "nodes": {
  31.                                     "127.0.0.1:1981":10
  32.                                 }
  33.                             },
  34.                             "weight": 3
  35.                         },
  36.                         {
  37.                             "weight": 2
  38.                         }
  39.                     ]
  40.                 }
  41.             ]
  42.         }
  43.     },
  44.     "upstream": {
  45.             "type": "roundrobin",
  46.             "nodes": {
  47.                 "127.0.0.1:1980": 1
  48.             }
  49.     }

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:

  1. curl 'http://127.0.0.1:9080/index.html?name=jack&name2=rose' \
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. ...
  4. world 1981
  1. curl 'http://127.0.0.1:9080/index.html?name=jack&name2=rose' \
  2. -H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2: world' -i
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. ...
  4. 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:

  1. curl 'http://127.0.0.1:9080/index.html?name=jack' \
  2. -H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2: world' -i
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. ...
  4. world 1981
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. ...
  4. hello 1980

In the example below the required headers are missing and both the vars rules fail to match and the request is directed to the default Upstream of the Route (1980):

  1. curl 'http://127.0.0.1:9080/index.html?name=jack' -i
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. ...
  4. hello 1980

You can achieve one-to-one correspondence between rules and Upstream by configuring multiple rules:

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:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "uri": "/hello",
  5.     "plugins": {
  6.         "traffic-split": {
  7.             "rules": [
  8.                 {
  9.                     "match": [
  10.                         {
  11.                             "vars": [
  12.                                 ["http_x-api-id","==","1"]
  13.                             ]
  14.                         }
  15.                     ],
  16.                     "weighted_upstreams": [
  17.                         {
  18.                             "upstream": {
  19.                                 "name": "upstream-A",
  20.                                 "type": "roundrobin",
  21.                                 "nodes": {
  22.                                     "127.0.0.1:1981":1
  23.                                 }
  24.                             },
  25.                             "weight": 3
  26.                         }
  27.                     ]
  28.                 },
  29.                 {
  30.                     "match": [
  31.                         {
  32.                             "vars": [
  33.                                 ["http_x-api-id","==","2"]
  34.                             ]
  35.                         }
  36.                     ],
  37.                     "weighted_upstreams": [
  38.                         {
  39.                             "upstream": {
  40.                                 "name": "upstream-B",
  41.                                 "type": "roundrobin",
  42.                                 "nodes": {
  43.                                     "127.0.0.1:1982":1
  44.                                 }
  45.                             },
  46.                             "weight": 3
  47.                         }
  48.                     ]
  49.                 }
  50.             ]
  51.         }
  52.     },
  53.     "upstream": {
  54.             "type": "roundrobin",
  55.             "nodes": {
  56.                 "127.0.0.1:1980": 1
  57.             }
  58.     }
  59. }'

Now, when the request header x-api-id is equal to 1, it will hit the Upstream on 1981:

  1. curl http://127.0.0.1:9080/hello -H 'x-api-id: 1'
  1. 1981

If request header x-api-id is equal to 2, it will hit the Upstream on 1982:

  1. curl http://127.0.0.1:9080/hello -H 'x-api-id: 2'
  1. 1982
  1. curl http://127.0.0.1:9080/hello -H 'x-api-id: 3'
  1. 1980

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.

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "uri": "/index.html",
  5.     "plugins": {},
  6.     "upstream": {
  7.         "type": "roundrobin",
  8.         "nodes": {
  9.             "127.0.0.1:1980": 1
  10.         }
  11. }'