Canary Release Plugin

Kong plugin for Canary release of an API.


Configuring the plugin is straightforward, you can add it on top of an existing API by executing the following request on your Kong server:

$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name=canary" \
    --data "config.percentage=50"

api: The id or name of the API that this plugin configuration will target.

You can also apply it for every API using the http://kong:8001/plugins/ endpoint.

Form Parameter Default Description
name canary The name of the plugin to use, in this case: canary
config.start Future time in seconds since epoch, when the release will start (ignored when percentage is set)
config.duration 3600 How long, in seconds, should the transition take (ignored when percentage is set)
config.percentage Fixed % of traffic to be routed to new target, if given overrides start and duration
config.steps 1000
config.upstream_host Target hostname where traffic will be routed, required if upstream_uri is not set
config.upstream_uri Upstream URI where traffic will be routed, required if upstream_host is not set
config.hash consumer Entity to be used for hashing. Options: consumer, ip, or none. Please make sure when not using none, to properly set the settings for trusted_ips (see settings trusted_ips and real_ip_header in the Kong config file)


The plugin will route traffic to 2 different upstream services, referred to as A and B. The location of service A will be defined by the upstream_url property of the api the plugin is configured on. The location of service B is defined by the config.upstream_host or config.upstream_uri as configured on the plugin.

There are 2 modes of operation:

  1. Set a fixed percentage to be routed to destination B. See parameter config.percentage.
  2. Set a period over which (in lineair time) the traffic will be moved over from destination A to B. See parameters config.start and config.duration.

Determining where to route a request.

The plugin defines a number of "buckets" (config.steps). Each of those can be routed to either A or B. For example: 100 steps, and precentage at 10%. Then 100 buckets will be created, of which 10 will be routed to upstream B, and 90 will remain at A.

Which requests end up in a specific bucket is determined by the config.hash parameter. When set to consumerthen it is made sure that each consumer will consistently end up in the same bucket. The effect being that once a bucket a consumer belongs to is switched to B, it will then always go to B, and a consumer will not "flip-flop" between A and B. Alternatively if it is set to ip then the same concept applies, but based on the originating ip address.

The downside of consumer and ip is that if any specific consumer or ip is responsible for a more than average part of the load, the migration is not nicely distributed. Eg. with percentage set to 50%, then 50% of either the consumers or ips are rerouted, but not necessarily 50% of the requests.

When set to none then the requests will be nicely distributed, each bucket will get the same number of requests, but in this case a consumer or ip might be flip-flopping between destination A and B on consecutive requests.

In any case there is an automatic fallback in case a consumer or ip could not be identified for some reason. The fall-back order will be consumer->ip->none.

Finalizing the canary

Once the canary is complete, either going to 100% for a percent-based canary, or after the timed canary reached 100%, the configuration needs to be updated.

This takes 2 steps:

  1. Update location A to point to location B. This can be done by a PATCH request on the API where the upstream_url property is updated to the url as specified by config.upstream_host or config.upstream_uri (or location B).
  2. Since now the location A and B are the same, the canary plugin can now be removed from the system with a DELETE request.

If the canary was not complete yet, then executing those steps prematurely, will instantly switch 100% of traffic to the new location (B).

Keep up with the latest features