traffic-label

Labels requests for later plugins by match rules.

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

What it does

traffic-label writes headers into the requests a route takes, chosen by rules, so the backend and the plugins that run after it can tell kinds of traffic apart. Each of the Rules pairs Conditions, read like a route's own, with Actions whose Headers to set are written into the request.

The header it writes replaces a header of the same name the client sent. The label is a request header and nothing else: it is not one of the Labels of a consumer, and acl does not read it.

How a request gets its label

The rules are read from the top for each request.

• A rule whose Conditions the request meets takes it. A rule with no conditions at all takes every request that reaches it.
• Of the matched rule's Actions, one is taken per request, chosen by the Weight of each.
• An action that writes headers ends the walk, and the rules below are not read for that request.
• An action that carries only a Weight hands its share to the rules below, and a request no rule labels reaches the backend unlabelled.

A last rule with no conditions catches every request the rules above it let through, as external does in the example.

When to use it

• The backend of the orders API treats calls from the internal network apart from calls from the internet, and reads which is which from one header.
• A new version of a backend should see a share of the traffic first, marked by a header that a later step reads, with the weights of two actions.
• Requests that carry a release header, canary for example, should be marked for the backend, and every other request marked as ordinary.
• A header that tells the backend how a request was classified must come from the gateway, never from the client.

Not for letting a consumer through or refusing it by a team or tier set on the consumer — see acl (Allows or denies consumers by the labels they carry), sending a share of the requests to another upstream — see traffic-split (Splits traffic between upstreams by weight and match rules) or headers the backend always receives on a route, whatever the request — see proxy-rewrite (Rewrites the request URI, method, host and headers before proxying).

Set it up

Mark requests from the internal network with a header the backend can read

The last rule has no conditions, so every other request is marked external and a value the client sent itself is overwritten; behind a load balancer, add real-ip so that the first rule reads the caller's own address.

Fill Rules as in the JSON below.

traffic-label · as the console saves it

{
  "rules": [
    {
      "match": [
        [
          "remote_addr",
          "ipmatch",
          "10.0.0.0/8"
        ]
      ],
      "actions": [
        {
          "set_headers": {
            "X-Traffic-Source": "internal"
          }
        }
      ]
    },
    {
      "actions": [
        {
          "set_headers": {
            "X-Traffic-Source": "external"
          }
        }
      ]
    }
  ]
}

Things to know

• Rules — The first matching rule ends the walk only when its action writes headers. An action with a weight alone lets the rules below label the request.
• Rules — A request from 10.20.30.40 meets the rule on 10.0.0.0/8 and reaches the backend with X-Traffic-Source set to internal. A request from 203.0.113.9 falls to the last rule and is marked external.
• Headers to set — A header the client sent under the same name is overwritten: a client from 203.0.113.9 that sends X-Traffic-Source as internal reaches the backend marked external.
• Conditions — A condition on remote_addr reads the address the request arrives from. Behind a load balancer, add real-ip to the same route, as the example does, so it reads each client's own address.
• Headers to set — A value is one text or number: a header given a list of values is refused when you save.
• Headers to set — A header name with a colon in it is refused when you save.
• Headers to set — A value whose only variable is unknown is sent as nothing, and the header is dropped.
• Weight — The turns are counted inside each worker process, so the shares only approach the weights over many requests.
• AdviceEnd the rules with one that has no conditions, as the example does, so every request carries a value the backend can trust.

Settings

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

Rulesrulesarray of objectsRequired

at least 1 item

Each item:

Conditionsrules[].matcharray

Read like a route's conditions. A rule with no conditions at all takes every request.

at least 1 item · conditions on request variables: see Conditions on request variables

Actionsrules[].actionsarray of objectsRequired

One action of the matched rule is taken per request, chosen by the weights. An action carrying only a weight hands its share to the rules below, or leaves it unlabelled where none follows.

at least 1 item

Each item:

Headers to setrules[].actions[].set_headersobject

Headers written into the request; a $name or ${name} anywhere in a value takes that request variable, so $host sends the host asked for. A value whose only variable is unknown is sent as nothing, and the header is dropped. An object whose keys are a name without a colon, each with a string or number as its value.

at least 1 key

Weightrules[].actions[].weightintegerdefault 1

The share of the matched rule's requests this action takes, from 1 up. The turns are counted inside each worker process, so the shares only approach the weights over many requests.

at least 1

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