Mastering Canary Deployments with Ingress-Nginx Annotations in Kubernetes

Background

When using Kubernetes as a cloud platform for business applications, Istio can be too heavy for simple blue‑green deployments, while Ingress‑Nginx 0.21 introduced a canary feature that allows traffic splitting via annotations.

Ingress‑Nginx Canary Annotation Overview

To enable the canary feature, set nginx.ingress.kubernetes.io/canary: "true" and then use the following annotations: nginx.ingress.kubernetes.io/canary-weight – integer 0‑100 indicating the percentage of traffic sent to the canary service. nginx.ingress.kubernetes.io/canary-by-header – split traffic based on a request header; values always route all traffic to the canary, never route none, other values are ignored. nginx.ingress.kubernetes.io/canary-by-header-value – used together with the header annotation to match a specific header value. nginx.ingress.kubernetes.io/canary-by-cookie – split traffic based on a cookie; always routes all traffic to the canary, never routes none.

The priority order is: canary-by-header → canary-by-cookie → canary-weight.

Weight‑Based Small‑Scale Version Testing

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "50"
  name: echoserverv2
  namespace: echoserver
spec:
  rules:
  - host: echo.chulinx.com
    http:
      paths:
      - backend:
          serviceName: echoserverv2
          servicePort: 8080
        path: /
---
kind: Service
apiVersion: v1
metadata:
  name: echoserverv2
  namespace: echoserver
spec:
  selector:
    name: echoserverv2
  type: ClusterIP
  ports:
  - name: echoserverv2
    port: 8080
    targetPort: 8080
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: echoserverv2
  namespace: echoserver
spec:
  template:
    metadata:
      labels:
        name: echoserverv2
    spec:
      containers:
      - image: mirrorgooglecontainers/echoserver:1.10
        name: echoserverv2
        ports:
        - containerPort: 8080
          name: echoserverv2

After applying the above, a 10‑request test shows roughly 5 requests to each version, demonstrating the weight‑based split.

Header‑Based A/B Testing

Modify the v2 ingress to add nginx.ingress.kubernetes.io/canary-by-header: "v2". Tests with headers v2:always, v2:never, and v2:true show that always routes all traffic to v2, never routes all to v1, and other values respect the weight setting.

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "50"
    nginx.ingress.kubernetes.io/canary-by-header: "v2"
  name: echoserverv2
  namespace: echoserver
spec:
  rules:
  - host: echo.chulinx.com
    http:
      paths:
      - backend:
          serviceName: echoserverv2
          servicePort: 8080
        path: /

Custom Header‑Value

Adding nginx.ingress.kubernetes.io/canary-by-header-value: "true" allows matching a specific header value while still falling back to weight‑based routing for other values.

Cookie‑Based Traffic Splitting

Using nginx.ingress.kubernetes.io/canary-by-cookie with values always or never routes traffic accordingly; other values are ignored and the weight rule applies.

Summary

Canary releases ensure overall system stability by allowing incremental testing of new versions. The article demonstrates practical use of Ingress‑Nginx canary annotations to achieve blue‑green, canary, and A/B testing deployments.

Other Deployment Strategies

Blue‑Green Deployment

Two complete environments exist: the live “green” version and the new “blue” version. Traffic is switched from green to blue once the blue version passes testing.

Canary Deployment

Only one environment exists; a small subset of instances runs the new version. Traffic is gradually increased as confidence grows.

A/B Testing

Multiple stable versions run simultaneously, and traffic is allocated to evaluate performance metrics such as conversion rates.