traffic-split

Splits traffic between upstreams by weight and match rules.

Category TrafficAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin traffic-splitPriority 966

What it does

traffic-split sends a share of a route's requests to another upstream. Each entry under Rules has a Match that decides which requests it takes, and Weighted upstreams that share them out by Weight.

The rules are read in order, and the first whose conditions pass takes the request. A request no rule takes goes to the route's own upstream, and so does the share of an entry that names no upstream.

When to use it

• A canary release: a new version of the orders service takes a tenth of the requests while the current one serves the rest.
• Moving from an old backend to a new one in steps, raising the new version's weight as it proves itself.
• Testers who send a release header reach the new version, while every other client stays on the current one.
• One tenant's requests, matched by a cookie or a header, sent to backends of its own.

Not for balancing requests between the instances of one backend — see Upstream (Upstreams are the backends that routes and services send traffic to) or choosing a backend by path, host or method — see Route (Routes match incoming requests and send them to an upstream).

Guides

Pages that walk through a job with traffic-split, step by step.

• Send a share of requests to a new versionSend a tenth of a route's requests to a new version of its backend, and raise the share as the new version proves itself.

Set it up

Send a tenth of the traffic to a new version of the service

Needs an upstream with the id checkout-v2; the entry without an upstream id sends to the route's own upstream.

Fill Rules as in the JSON below.

traffic-split · as the console saves it

{
  "rules": [
    {
      "weighted_upstreams": [
        {
          "upstream_id": "checkout-v2",
          "weight": 1
        },
        {
          "weight": 9
        }
      ]
    }
  ]
}

What you will see

• Over many requests every answer is 200, and both the route's own backend and the new version answer some of them; one request on its own cannot show the split.

Things to know

• Rules — The first rule whose conditions pass takes the request, so an unconditioned rule hides every rule below it. When no rule takes the request, the object's own upstream serves it.
• Weight — With weights 1 and 9, 100 requests are answered partly by the upstream checkout-v2 and partly by the route's own upstream.
• Weighted upstreams — An entry with a weight and no upstream sends its share to the route's own upstream. In the example, the requests that do not reach checkout-v2 reach the route's own backend.
• Weighted upstreams — A rule holds at most 20 entries; more are refused when you save.
• Rules — An empty list of rules is refused when you save.
• Conditions — A match entry with no conditions is refused when you save.
• Upstream — An upstream written here with https opens TLS without checking the backend's certificate.
• Upstream — An upstream written here needs its nodes. One found by service discovery is refused when you save.
• Upstream — A slow start, warm_up_conf, is refused when you save.
• AdviceGive a new version an upstream of its own and name it under Upstream ID, so that its nodes are kept in one place for every route that splits to it.

Settings

The fields as the console shows them, section by section.

Rulesrulesarray of objects

at least 1 item

Each item:

Matchrules[].matcharray of objects

The rule takes the request when any one of these condition sets passes.

Each item:

Conditionsrules[].match[].varsarrayRequired

conditions on request variables: see Conditions on request variables

Weighted upstreamsrules[].weighted_upstreamsarray of objectsdefault [{"weight":1}]

An entry that names no upstream at all stands for the object's own upstream.

1 to 20 items

Each item:

Upstream IDrules[].weighted_upstreams[].upstream_idstring or integer

An existing upstream to send this share to; an id that names none is stored and then fails every request of this rule. An id written beside an upstream of its own is the one that is used.

string 1 to 64 characters or integer at least 1 · letters, digits, dots, hyphens and underscores

pattern

^[a-zA-Z0-9-_.]+$

Weightrules[].weighted_upstreams[].weightintegerdefault 1

The share of this rule's traffic that goes to this upstream, such as 20 beside 80. A weight of 0 takes it out of the split only while another entry of the rule carries more than 0; an entry left alone in its rule takes every request whatever its weight.

at least 0

Upstreamrules[].weighted_upstreams[].upstreamobject

An upstream written here for this share; its nodes, algorithm and key, timeout, scheme and Host passing are read. https and wss open TLS (https checks no certificate, wss always does); ws, grpc and grpcs go plain; everything else is stored, never used. A keyless consistent hash on a header, cookie or variable fails every request past one node. Its keys are those of an upstream, each described on that page; only the ones named here are read.

example {"type":"roundrobin","scheme":"https","nodes":{"10.0.0.14:8443":1}}

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.