canary-header-Microservices Engine(MSE)-阿里云帮助中心

When you roll out a new service version, you typically need clients to send specific headers so the gateway can route a portion of traffic to the canary upstream. The canary-header plug-in removes this client-side requirement by injecting headers into a configurable percentage of incoming requests on the cloud-native gateway. The gateway then re-evaluates routing rules with the injected header, directing matched requests to the canary upstream automatically.

How it works

A request arrives at the cloud-native gateway and matches a route.
The canary-header plug-in randomly assigns a header to the request based on configured weights.
The gateway re-evaluates routing rules with the injected header.
If a canary route matches the injected header, the request is forwarded to the canary upstream. Otherwise, the request continues to the original upstream.

Configuration reference

Configure the plug-in with the weighted_headers array. Each entry defines a header key-value pair and its traffic weight.

Field	Type	Required	Default	Description
`weighted_headers`	array of object	Yes	-	Headers to inject and their traffic weights.

Each object in weighted_headers contains the following fields:

Field	Type	Required	Default	Description
`added_key`	string	Yes	-	Header key to inject (for example, `x-higress-canary`).
`added_value`	string	Yes	-	Header value to inject (for example, `gray`).
`weight`	number	Yes	-	Percentage of requests that receive this header. Valid range: 0--100. The sum of all weights must not exceed 100. If the total is less than 100, the remaining percentage of requests pass through without an injected header.

Configure the plug-in globally

Split all traffic between two header values

Inject x-higress-canary: gray into 30% of requests and x-higress-canary: base into the remaining 70%:

weighted_headers:
- added_key: x-higress-canary
  added_value: gray
  weight: 30
- added_key: x-higress-canary
  added_value: base
  weight: 70

Tag only canary traffic

Inject x-higress-canary: gray into 30% of requests. The other 70% receive no additional header:

weighted_headers:
- added_key: x-higress-canary
  added_value: gray
  weight: 30

Configure the plug-in for specific routes or domains

Use the _rules_ field to scope the plug-in to specific routes or domain names instead of applying it globally.

Route-based scoping

Apply the plug-in only to requests matching route-a. Of those requests, 30% receive x-higress-canary: gray and 70% receive x-higress-canary: base. After header injection, the gateway re-matches routes. If a route named route-a-gray matches on the x-higress-canary: gray header, 30% of route-a traffic is redirected to route-a-gray.

# Use the _rules_ field to configure fine-grained rules.
_rules_:
# Rule 1: Match a route name.
- _match_route_:
  - route-a
  weighted_headers:
  - added_key: x-higress-canary
    added_value: gray
    weight: 30
  - added_key: x-higress-canary
    added_value: base
    weight: 70

Domain-based scoping

Distribute traffic across three header values for all requests matching *.example.com:

# Rule 2: Match a domain name.
- _match_domain_:
  - "*.example.com"
  weighted_headers:
  - added_key: x-custom-header
    added_value: gray
    weight: 30
  - added_key: x-custom-header
    added_value: blue
    weight: 30
  - added_key: x-custom-header
    added_value: base
    weight: 40