Canary Release

Reduce the risk of introducing a new software version in production by slowly rolling out the change to a small subset of users. This plugin also enables roll back to your original upstream service, or shift all traffic to the new version.

• Detailed documentation for the Enterprise Canary Release Plugin

Terminology

• plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
• Service: the Kong entity representing an external upstream API or microservice.
• Route: the Kong entity representing a way to map downstream requests to upstream services.
• Consumer: the Kong entity representing a developer or machine using the API. When using Kong, a Consumer only communicates with Kong which proxies every call to the said upstream API.
• Credential: a unique string associated with a Consumer, also referred to as an API key.
• upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.
• API: a legacy entity used to represent your upstream services. Deprecated in favor of Services since CE 0.13.0 and EE 0.32.

Configuration

Enabling the plugin on a Service

Configure this plugin on a Service by making the following request:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=canary" 

• service: the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

Configure this plugin on a Route with:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=canary" 

• route_id: the id of the Route that this plugin configuration will target.

Enabling the plugin on a Consumer

You can use the http://localhost:8001/plugins endpoint to enable this plugin on specific Consumers:

$ curl -X POST http://kong:8001/plugins \
    --data "name=canary" \
    --data "consumer_id={consumer_id}" 

Where consumer_id is the id of the Consumer we want to associate with this plugin.

You can combine consumer_id and service_id

in the same request, to furthermore narrow the scope of the plugin.

Enabling the plugin on an API

If you are using an older version of Kong with the legacy API entity (deprecated in favor of Services since CE 0.13.0 and EE 0.32.), you can configure this plugin on top of such an API by making the following request:

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

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

Global plugins

All plugins can be configured using the http://kong:8001/plugins/ endpoint. A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Usage

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 linear 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 percentage 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 consumer then 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).