Kong Enterprise 3.3 delivers enhanced security, usability, and platform reliability. Learn more

Kubernetes Canary Deployment in 5 Minutes

Welcome to our second hands-on Kuma guide! The first one walked you through securing your application with mTLS using Kuma. Today, this guide will walk you through Kuma’s new L4 traffic routing rules. These rules will allow you to easily implement blue/green and Kubernetes canary deployments. In summary, Kuma will now alleviate the stress of deploying new versions and/or features into your service mesh. Let’s take a glimpse at how to achieve it in our sample application:

kubernetes canary deployment diagram

Start Kubernetes and Marketplace Application

To start, you need a Kubernetes cluster with at least 4GB of memory. We’ve tested Kuma on Kubernetes v1.13.0 – v1.16.x, so use anything older than v1.13.0 with caution. In this tutorial, we’ll be using v1.15.4 on minikube, but feel free to run this in a cluster of your choice.

$ minikube start --cpus 2 --memory 4096 --kubernetes-version v1.15.4
😄  minikube v1.4.0 on Darwin 10.14.6
🔥  Creating virtualbox VM (CPUs=2, Memory=4096MB, Disk=20000MB) ...
🐳  Preparing Kubernetes v1.15.4 on Docker 18.09.9 ...
🚜  Pulling images ...
🚀  Launching Kubernetes ...
⌛  Waiting for: apiserver proxy etcd scheduler controller dns
🏄  Done! kubectl is now configured to use "minikube"

When running on Kubernetes, Kuma will store all of its state and configuration on the underlying Kubernetes API server, and therefore requiring no dependency to store the data. 

With your Kubernetes cluster up and running, we can throw up a demo application built for Kuma. Deploy the marketplace application by running:

$ kubectl apply -f http://bit.ly/kuma101
namespace/kuma-demo created
serviceaccount/elasticsearch created
service/elasticsearch created
replicationcontroller/es created
deployment.apps/redis-master created
service/redis created
service/backend created
deployment.apps/kuma-demo-backend-v0 created
deployment.apps/kuma-demo-backend-v1 created
deployment.apps/kuma-demo-backend-v2 created
configmap/demo-app-config created
service/frontend created
deployment.apps/kuma-demo-app created

This will deploy our demo marketplace application split across four pods. The first pod is an Elasticsearch service that stores all the items in our marketplace. The second pod is the Vue front-end application that will give us a visual page to interact with. The third pod is our Node API server, which is in charge of interacting with the two databases. Lastly, we have the Redis service that stores reviews for each item. Let’s check that the pods are up and running by checking the `kuma-demo` namespace:

$ kubectl get pods -n kuma-demo
NAME                                       READY    STATUS      RESTARTS      AGE
es-87mgm                                   1/1      Running        0          91s
kuma-demo-app-7f799bbfdf-7bk2x             2/2      Running        0          91s
kuma-demo-backend-v0-6548b88bf8-46z6n      1/1      Running        0          91s
redis-master-6d4cf995c5-d4kc6              1/1      Running        0          91s

With the application running, port-forward the sample application to access the front-end UI at http://localhost:8080:

$ kubectl port-forward ${KUMA_DEMO_APP_POD_NAME} -n kuma-demo 8080:80
Forwarding from -> 80
Forwarding from [::1]:8080 -> 80

Now that you can visualize the application, play around with it! This is what you just created:

The only difference is this diagram includes the v1 and v2 deployment of our back-end API. If you inspect our pods in `kuma-demo` namespace again, you will only find a lonely v0, but don’t worry, I included the deployments for v1 and v2 for you. Before we scale those deployments, let’s add Kuma.

Download Kuma

To start, we need to download the latest version of Kuma. You can find installation procedures for different platforms on our official documentation. The following guide is being created on macOS so it will be using the Darwin image:

$ wget https://kong.bintray.com/kuma/kuma-0.3.0-darwin-amd64.tar.gz
--2019-12-09 11:25:49--  https://kong.bintray.com/kuma/kuma-0.3.0-darwin-amd64.tar.gz
Resolving kong.bintray.com (kong.bintray.com)...,
Connecting to kong.bintray.com (kong.bintray.com)||:443... connected.
HTTP request sent, awaiting response... 302
Location: https://akamai.bintray.com/3a/3afc187b8e3daa912648fcbe16f0aa9c2eb90b4b0df4f0a5d47d74ae426371b1?__gda__=exp=1575920269~hmac=0d7c9af597660ab1036b3d50bef98fc68dfa0b832e2005d25e1628ae92c6621e&response-content-disposition=attachment%3Bfilename%3D%22kuma-0.3.0-darwin-amd64.tar.gz%22&response-content-type=application%2Fgzip&requestInfo=U2FsdGVkX1-CBTtYNUxxbm2yT4muZ0ig1ICnD2XOqJI7BobZ4DB_RouzRRsn3NBrSFjF_IqjN9wzbGk28ZcFS_mD79NCyZ0V0XxawLL8UvY5D8h-QQdfKTeRUpLUqOKI&response-X-Checksum-Sha1=6df196169311c66a544eccfdd73931b6f3b83593&response-X-Checksum-Sha2=3afc187b8e3daa912648fcbe16f0aa9c2eb90b4b0df4f0a5d47d74ae426371b1 [following]
--2019-12-09 11:25:49--  https://akamai.bintray.com/3a/3afc187b8e3daa912648fcbe16f0aa9c2eb90b4b0df4f0a5d47d74ae426371b1?__gda__=exp=1575920269~hmac=0d7c9af597660ab1036b3d50bef98fc68dfa0b832e2005d25e1628ae92c6621e&response-content-disposition=attachment%3Bfilename%3D%22kuma-0.3.0-darwin-amd64.tar.gz%22&response-content-type=application%2Fgzip&requestInfo=U2FsdGVkX1-CBTtYNUxxbm2yT4muZ0ig1ICnD2XOqJI7BobZ4DB_RouzRRsn3NBrSFjF_IqjN9wzbGk28ZcFS_mD79NCyZ0V0XxawLL8UvY5D8h-QQdfKTeRUpLUqOKI&response-X-Checksum-Sha1=6df196169311c66a544eccfdd73931b6f3b83593&response-X-Checksum-Sha2=3afc187b8e3daa912648fcbe16f0aa9c2eb90b4b0df4f0a5d47d74ae426371b1
Resolving akamai.bintray.com (akamai.bintray.com)...
Connecting to akamai.bintray.com (akamai.bintray.com)||:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 38017379 (36M) [application/gzip]
Saving to: ‘kuma-0.3.0-darwin-amd64.tar.gz’

kuma-0.3.0-darwin-amd64.tar.gz      100%[================================================================>]  36.26M  4.38MB/s    in 8.8s

2019-12-09 11:25:59 (4.13 MB/s) - ‘kuma-0.3.0-darwin-amd64.tar.gz’ saved [38017379/38017379]

Next, let’s unbundle the files to get the following components:

$ tar xvzf kuma-0.3.0-darwin-amd64.tar.gz
x ./
x ./conf/
x ./conf/kuma-cp.conf
x ./bin/
x ./bin/kuma-tcp-echo
x ./bin/kuma-dp
x ./bin/kumactl
x ./bin/kuma-cp
x ./bin/envoy

Lastly, go into the ./bin directory where the Kuma components will be:

$ cd bin && ls
envoy   kuma-cp   kuma-dp   kuma-tcp-echo kumactl

Install Kuma

With Kuma downloaded, let’s utilize `kumactl` to install Kuma on our cluster. The `kumactl` executable is a very important component in your journey with Kuma, so be sure to read more about it here. Run the following command to install Kuma onto our Kubernetes cluster:

$ ./kumactl install control-plane | kubectl apply -f -
namespace/kuma-system created
secret/kuma-admission-server-tls-cert created
secret/kuma-injector-tls-cert created
secret/kuma-sds-tls-cert created
configmap/kuma-control-plane-config created
configmap/kuma-injector-config created
serviceaccount/kuma-control-plane created
customresourcedefinition.apiextensions.k8s.io/dataplaneinsights.kuma.io created
customresourcedefinition.apiextensions.k8s.io/dataplanes.kuma.io created
customresourcedefinition.apiextensions.k8s.io/meshes.kuma.io created
customresourcedefinition.apiextensions.k8s.io/proxytemplates.kuma.io created
customresourcedefinition.apiextensions.k8s.io/trafficlogs.kuma.io created
customresourcedefinition.apiextensions.k8s.io/trafficpermissions.kuma.io created
customresourcedefinition.apiextensions.k8s.io/trafficroutes.kuma.io created
clusterrole.rbac.authorization.k8s.io/kuma:control-plane created
clusterrolebinding.rbac.authorization.k8s.io/kuma:control-plane created
role.rbac.authorization.k8s.io/kuma:control-plane created
rolebinding.rbac.authorization.k8s.io/kuma:control-plane created
service/kuma-injector created
service/kuma-control-plane created
deployment.apps/kuma-control-plane created
deployment.apps/kuma-injector created
mutatingwebhookconfiguration.admissionregistration.k8s.io/kuma-admission-mutating-webhook-configuration created
mutatingwebhookconfiguration.admissionregistration.k8s.io/kuma-injector-webhook-configuration created
validatingwebhookconfiguration.admissionregistration.k8s.io/kuma-validating-webhook-configuration created

When deploying on Kubernetes, you are supposed to change the state of Kuma by leveraging Kuma’s CRDs. Therefore, we will now use `kubectl` to help us through the remaining demo. To start, let’s check the pods are up and running within the `kuma-system` namespace:

$ kubectl get pods -n kuma-system
NAME                                  READY   STATUS    RESTARTS   AGE
kuma-control-plane-7bcc56c869-lzw9t   1/1     Running   0          70s
kuma-injector-9c96cddc8-745r7         1/1     Running   0          70s

While running on Kubernetes, no external dependencies are required, since it leverages the underlying Kubernetes API server to store its configuration. However, as you can see above, a `kuma-injector` service will also start in order to automatically inject sidecar data plane proxies without human intervention. Data plane proxies are injected into namespaces that include the following label:

kuma.io/sidecar-injection: enabled

Now that our control plane and injector are running, let’s delete the existing kuma-demo pods so they restart. This will give the injector a chance to deploy those sidecar proxies among each pod. 

$ kubectl delete pods --all -n kuma-demo
pod "es-87mgm" deleted
pod "kuma-demo-app-7f799bbfdf-7bk2x" deleted
pod "kuma-demo-backend-v0-6548b88bf8-46z6n" deleted
pod "redis-master-6d4cf995c5-d4kc6" deleted

Check that the pods are up and running again with an additional container. The additional container is the Envoy sidecar proxy that Kuma is injecting into each pod.

$ kubectl get pods -n kuma-demo
NAME                                    READY    STATUS     RESTARTS    AGE
es-jxzfp                                2/2      Running    0           43s
kuma-demo-app-7f799bbfdf-p5gjq          3/3      Running    0           43s
kuma-demo-backend-v0-6548b88bf8-8sbzn   2/2      Running    0           43s
redis-master-6d4cf995c5-42hlc           2/2      Running    0           42s

Now if we port-forward our marketplace application again, I challenge you to spot the difference.

$ kubectl port-forward ${KUMA_DEMO_APP_POD_NAME} -n kuma-demo 8080:80
Forwarding from -> 80
Forwarding from [::1]:8080 -> 80

A-ha! Couldn’t find a thing, right? Well, that is because Kuma doesn’t require a change to your application’s code in order to be used. The only change is that Envoy now handles all the traffic between the services. Kuma implements a pragmatic approach that is very different from the first-generation control planes:

  • It runs with low operational overhead across all the organization
  • It supports every platform
  • It’s easy to use while relying on a solid networking foundation delivered by Envoy – and we see it in action right here!

Kubernetes Canary Deployment

With the mesh up and running, let’s start expanding our application with brand new features. Our current marketplace application has no sales. With the holiday season upon us, the engineering team worked hard to develop v1 and v2 version of the Kuma marketplace to support flash sales. The backend-v1 service will always have one item on sale, and the backend-v2 service will always have two items on sale. So to start, scale up the deployments of v1 and v2 like so:

$ kubectl scale deployment kuma-demo-backend-v1 -n kuma-demo --replicas=1
deployment.extensions/kuma-demo-backend-v1 scaled


$ kubectl scale deployment kuma-demo-backend-v2 -n kuma-demo --replicas=1
deployment.extensions/kuma-demo-backend-v2 scaled

Now if we check our pods again, you will see three backend services:

$ kubectl get pods -n kuma-demo
NAME                                       READY   STATUS      RESTARTS    AGE
es-jxzfp                                   2/2     Running      0          9m16s
kuma-demo-app-7f799bbfdf-p5gjq             3/3     Running      0          9m16s
kuma-demo-backend-v0-6548b88bf8-8sbzn      2/2     Running      0          9m16s
kuma-demo-backend-v1-894bcd4bc-p7xz8       2/2     Running      0          20s
kuma-demo-backend-v2-dffb4bffd-48z67       2/2     Running      0          11s
redis-master-6d4cf995c5-42hlc              2/2     Running      0          9m15s

With the new versions up and running, use the new `TrafficRoute` policy to slowly roll out users to our flash-sale capability. This is also known as Kubernetes canary deployment: a pattern for rolling out new releases to a subset of users or servers. By deploying the change to a small subset of users, we can test its stability and make sure we don’t go broke by introducing too many sales at once.

First, define the following alias:

$ alias benchmark='echo "NUM_REQ NUM_SPECIAL_OFFERS"; kubectl -n kuma-demo exec $( kubectl -n kuma-demo get pods -l app=kuma-demo-frontend -o=jsonpath="{.items[0].metadata.name}" ) -c kuma-fe -- sh -c '"'"'for i in `seq 1 100`; do curl -s http://backend:3001/items?q | jq -c ".[] | select(._source.specialOffer == true)" | wc -l ; done | sort | uniq -c | sort -k2n'"'"''

This alias will help send 100 requests from `frontend-app` to `backend-api` and count the number of special offers in the response. Then it will group the request by the number of special offers. Here is an example of the output before we start configuring our traffic-routing:

$ benchmark
34                     0
33                     1
33                     2

The traffic is equally distributed because have not set any traffic-routing. Let’s change that! Here is what we need to achieve:

Kubernetes Canary Deployment Diagram 2

We can achieve that with the following policy:

 cat <<EOF | kubectl apply -f -
apiVersion: kuma.io/v1alpha1
kind: TrafficRoute
  name: frontend-to-backend
  namespace: kuma-demo
mesh: default
  - match:
      service: frontend.kuma-demo.svc:80
  - match:
      service: backend.kuma-demo.svc:3001
  # it is NOT a percentage. just a positive weight
  - weight: 80
      service: backend.kuma-demo.svc:3001
      version: v0
  # we're NOT checking if total of all weights is 100
  - weight: 20
      service: backend.kuma-demo.svc:3001
      version: v1
  # 0 means no traffic will be sent there
  - weight: 0
      service: backend.kuma-demo.svc:3001
      version: v2

trafficroute.kuma.io/frontend-to-backend created

That is all that is necessary! With one simple policy and the weight you apply to each matching service, you can slowly roll out the v1 and v2 version of your application. Let’s run the benchmark alias one more time to see the `TrafficRoute` policy in action:

$ benchmark
83                     0
17                     1

We do not see any results for two special offers because it is configured with a weight of 0. Once we’re comfortable with not going bankrupt with our rollout of v1, we can slowly apply weight to v2. You can also see the action live on the webpage. One last time, port-forward the application frontend like so:

$ kubectl port-forward ${KUMA_DEMO_APP_POD_NAME} -n kuma-demo 8080:80
Forwarding from -> 80
Forwarding from [::1]:8080 -> 80

Two out of roughly 10 requests to our webpage will have the sale feature enabled:

That’s all! This was a really quick run-through, so make sure you check out Kuma’s official webpage or repository to find out about more features. You can also join our Slack channel to chat with us live and meet the community! Lastly, sign up for the Kuma newsletter below to stay up-to-date as we push out more features that will make this the best service mesh solution for you.

Share Post

Subscribe to Our Newsletter!

    How to Scale High-Performance APIs and Microservices

    Learn how to make your API strategy a competitive advantage.

    June 20, 2023 8:00 AM (PT) Register Now