Canary Releases using Istio

Istio can be used to distribute the traffic load using different rules, a popular procedure to introduce a new functionality in an application is to roll out the new release to a small number of users. This type of deployment is called a Canary release.

A small percentage of the user traffic will be sent to the new release, called Canary Release, if everything works as expected, the Canary release will get more traffic and eventually all users will start using the new release. If something goes wrong, only a small percentage of user will be affected and the canary release can be removed without a mayor impact doing a rollback.

Deploying a Canary Release in Kubernetes Using Istio

This example uses a deployment that shows a blue webpage and its new release that shows a green page. We want to send 75% of the users to the blue release (the old one) and 25% to the green release (the new one).

Istio has to be configured to accept http traffic on the Kubernetes Ingress Gateway and send it to the Istio Gateway that will use an Istio Virtual Service to select the traffic with certain specifications (i.e. has a named header,  is targeted to a named host or has a known path prefix). An Istio Destination Rule acts as a  switch between different subsets of the application. Labels are used to link all the services and configuration.


Install Kubernetes

See Building a Kubernetes Cluster with Vagrant and Ansible (without Minikube)

Install Istio

See Installing Istio in Kubernetes under VirtualBox (without Minikube) for a tutorial on installing Istio in Kubernetes and publishing the Istio Gateway on VirtualBox as requirement to apply this example.

Create the Color Application

We will be using a small application written in Go as a deployment example to show some Istio Patterns. The application, called Color, shows a web page with a solid background color that depends on the value of an environment variable configured on the Kubernetes deployment file. It will also display information about the pod and the request.

You can download the source code from IT Wonder Lab git repository, build the application and create your own Docker image, or use a prebuilt image from the IT Wonder Lab Docker public repository.

Building the Color Application

Download the source code or create the following structure in your GOPATH:

The go application Color is made up of a main.go file with the code needed to start an http server in port 8080 and render the template file response.html replacing some placeholders (Title, Color, Host Name and Requests). It also sets a cookie on the client with the value of the color (it will be used in other examples).

The yaml files are used for deployment in Kubernetes.

color-blue.yaml and color-green.yaml use the same container itwonderlab/color, the difference between the two deployments is:

  • Value of the environment variable COLOR that is used by the Go app to set the background of the web page.
  • Value of the label color, that is used by Kubernetes to identify and differentiate the green and blue deployments.

color-nodeport.yaml is a Kubernetes deployment of a traditional Kubernetes Node Port service. This is the “traditional” way of publishing an application with Kubernetes when Istio is not available.

The Node Port publishes the app color (not making any difference between blue and green) in external port 30085:

Compiling the Color Application

If you want to build your own Color Application, you can run it locally by executing:

And accessing the webpage http://localhost:8080/

or build and publish the Docker image with:

The Docker Image is built using the instructions of Dockerfile:

The Dockerfile uses two different Docker images golang and alpine in a multi-stage build intended to reduce the size of the final image (the Color application) to only 15.3 MB.

If you are using your own Docker repository, remember to set the correct Docker repository name by replacing all references to itwonderlab/color with your_docker_repo/color.

Deploying the Application in Kubernetes

Deploy the applications and the NodePort by running:

Test the application accessing a cluster IP and the assigned NodePort, example:

The Color App webpage is displayed with either green or blue background color. If you open another browser the color could change as Kubernetes redirects the request to a different deployment.

By using Istio we will be able to control the behaviour of Kubernetes and use rules and weight to select the version (or color) of the application that is shown for each request.

Istio Definition for a Canary Deployment

The color-istio-gw-canary-pct.yaml defines 4 resources to accomplish an Istio Canary Deployment of the green version of the Color application:

Istio - ansible-kubernetes-vagrant-tutorial-Istio-2.png


  • Istio Gateway ( Gateway): uses the existing ingressgateway created when Istio was deployed to accept http traffic at port 80 from any host (*).
  • Istio Virtual Service ( VirtualService): the Istio virtual service is used to:
    • Match traffic: http with any host header, represented with * and with the URI prefix /color
    • Route traffic:
      • To the destination service (in Istio is named host) color-service and subset named blue-sub with a weight of 75%.
      • To the destination service (in Istio is named host) color-service and subset named green-sub with a weight of 25%.
  • Istio Destination Rule ( DestinationRule): defines subsets of a known service, in our example defines two subsets of the color-service service or host (in Istio, the services are called host):
    • blue-sub: corresponds to the service color-service with label color equal to blue.
    • green-sub: corresponds to the service color-service with label color equal to green.
  • Kubernetes Service color-service:  creates a cluster service named “color-service“, that receives traffic at port 8000 and sends it to port 8080 of the containers (the port exposed by the Docker images of the Color Application). The Istio Destination Rule will make sure that this Service sends 75% of the requests to the application color with label color: blue and 25% to the application color with label color: green.


Create the objects in the Kubernetes Cluster with:

Open a browser and visit URL

The background of the page will be blue 75% of the times and green 25%.


Istio Canary Release Rollback

Imagine that the Canary release is wrong and we need to rollback the change, simply

Change the weight of subset blue to 100 and subset green to 0:

Apply the change in Kubernetes, reload the URL many times and see that green (the Canary release) is never shown.

Istio Canary Release to Production

Imagine now that the Canary release is perfect and we want to send all users to the new release of the application. Change the weight of subset green to 100 and subset blue to 0:

Apply the change in Kubernetes, reload the URL many times and see that green (the Canary release that now is in production) is the new color for all requests.


Leave a Reply

1 Comment threads
0 Thread replies
Most reacted comment
Hottest comment thread
0 Comment authors
Recent comment authors

This site uses Akismet to reduce spam. Learn how your comment data is processed.

newest oldest most voted
Notify of

[…] Istio Patterns: Traffic Splitting in Kubernetes (Canary Release) for instructions on how to build the […]