The Canary Release plugin allows you to route traffic to two separate upstream services.
The plugin attaches to a primary upstream service through a Gateway Service, Route, or even globally,
and then the plugin configuration connects the second upstream service using its config.upstream_host
, config.upstream_port
, or config.upstream_uri
.
The Canary Release plugin supports the following modes of operation:
The Canary Release plugin decides how to route requests to the canary based on a hash attribute (config.hash
) and a given number of buckets (config.steps
). Each of these buckets can be routed to primary upstream service A or secondary upstream service B.
The behavior of steps
depends on your canary deployment type:
-
Percentage-based canary: Steps create buckets for traffic distribution.
For example, if you set
config.steps
to 100 and config.percentage
to 10%, the plugin creates 100 buckets and routes 10 buckets to the canary, while the remaining 90 route to the primary service.
-
Time-based canary: Steps determine the number of increments used to gradually shift from 0% to 100% traffic over time.
For example, in a 10-hour time based canary:
- If
config.steps
is set to 10, you will have 10 increments of 10% each, with 1 increment per hour.
- If
config.steps
is set to 100, you will have 100 increments of 1% each, with 10 increments per hour.
The config.hash
parameter determines which requests end up in a specific bucket, based on their consumer
, ip
, or header
.
For example, if the plugin is configured to hash on Consumer, then each Consumer will consistently end up in the same bucket or increment.
The effect is that once a Consumer’s bucket switches to upstream service B, it will then always go to B.
The same applies to hashing on IP or header.
If any specific Consumer, IP, or header is responsible for more than the average percentage of traffic, the migration may not be evenly distributed.
For example, if the canary fixed percentage is 50%, then 50% of either the Consumers or IPs will be rerouted, but not necessarily 50% of the total requests.
When config.hash
is set to none
, the requests will be evenly distributed.
Each bucket will get the same number of requests, but a Consumer or IP might be routed to either upstream service A or B on consecutive requests.
If Consumer, IP, or header can’t be identified, the Canary Release plugin automatically falls back to another option, in the following order:
- Fall back to Consumer
- Fall back to IP
- Fall back to
none
, evenly distributing requests across buckets
This method does not apply to allowing or denying groups with ACL.