traffic-split

Splits connections between upstreams by weight and match rules.

Category TrafficAdd it to Stream routeEngine plugin traffic-splitPriority 966

What it does

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

The first rule whose conditions pass takes the connection, and its conditions read connection variables only, for example remote_addr or server_port. An entry that names no upstream at all stands for the stream route's own upstream.

When to use it

• A new set of MQTT brokers takes a tenth of the connections on 1883, while the current brokers keep the rest.
• Clients of your own network, 10.0.0.0/8, sent to brokers of their own, while every other client stays on the current pool.
• Moving the clients of a database to new replicas in steps, raising the weight of the new upstream as it proves itself.

Not for splitting HTTP requests by header, cookie or path — see traffic-split (Splits traffic between upstreams by weight and match rules) or balancing connections between the nodes of one backend — see Upstream (Upstreams are the backends that routes and services send traffic to).

Set it up

Send a tenth of the connections to a new set of brokers

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

Fill Rules as in the JSON below.

traffic-split · as the console saves it

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

Things to know

• Rules — The first rule whose conditions pass takes the connection, and conditions read connection variables only: a rule on an HTTP header or argument never passes on a stream.
• Rules — An empty list of rules is refused when you save.
• Conditions — A match entry with no conditions is refused when you save.
• Conditions — A condition whose operator the gateway does not know is refused when you save.
• Weighted upstreams — A rule holds at most 20 entries; more are refused when you save.
• Weight — A weight of 0 takes an entry out of the split only while another entry of the rule carries more. An entry left alone in its rule takes every connection, whatever its weight.
• Upstream ID — An ID written beside an upstream of its own is the one that is used.
• Upstream — An upstream written here needs its nodes. One found by service discovery is refused when you save.
• Upstream — An upstream written here opens no TLS to its nodes, and the scheme tls is refused when you save.
• Upstream — The scheme https would close every connection the entry takes, and it is refused when you save.
• Upstream — A consistent hash on a header, cookie or variable without a key fails every connection past one node.
• Upstream — A slow start, warm_up_conf, is refused when you save.
• AdviceGive the new brokers an upstream of their own and name it under Upstream ID, so that their nodes are kept in one place for every stream route that splits to them.

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 connection 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 connection 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 connection whatever its weight.

at least 0

Upstreamrules[].weighted_upstreams[].upstreamobject

An upstream written here for this share; only its nodes, algorithm and key, and timeout are read. The scheme opens no TLS to the nodes; Host passing, health checks, client certificate, retries, keepalive pool and service discovery are stored, never used. A keyless consistent hash on a header, cookie or variable fails every connection 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","nodes":{"10.0.0.14:9000":1}}

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