The Canary Release plugin helps minimize risk when deploying a new software version by gradually rolling out changes to a limited group of users. It also allows you to either roll back to the original upstream service or shift all traffic to the new version.
Important: The Canary plugin is not designed for a Kubernetes-native framework, and shouldn’t be used with the Kong Ingress Controller. Instead, use the Gateway API to manage canary deploys.
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:
|
Use case |
Configured by |
|---|---|
| Route traffic by fixed percentage |
config.percentage
|
| Route traffic by grouping Consumers into allow/deny ACL groups |
config.groups parameter with the ACL plugin
|
| Transfer traffic from one upstream service to another over a configured time period |
config.start and config.duration
|
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.
For example, if you set config.steps to 100 steps and config.percentage to 10%, the Canary Release plugin creates 100 buckets.
10 buckets will be routed to B while the other 90 will remain routed to A.
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.
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:
none, evenly distributing requests across bucketsThis method does not apply to allowing or denying groups with ACL.
In some cases, you may want to allow clients to pick either upstream service A or B instead of applying the configured canary rules.
By setting config.canary_by_header_name, clients can send the value always to always use the canary service (B) or send the value never to never use the canary service (always use A).
Once the canary has moved 100% of traffic over to upstream service B, the plugin is no longer needed. To finalize the canary release, you need to update the Gateway Service and Canary Release plugin configuration.
Note: If the plugin is configured on a Route, then all Routes for the current Gateway Service must have completed the canary.
config.upstream_host, config.upstream_uri, and config.upstream_port.Removing or disabling the Canary Release plugin before the canary is complete will instantly switch all traffic back to service A.
This plugin works with both active and passive health checks.
You can enable Upstream health checks using the config.upstream_fallback parameter.
This configuration will skip applying the canary upstream if it doesn’t have at least one healthy target.
For this configuration to take effect, the following conditions must be met:
config.upstream_host to an Upstream entity