Master Canary Deployments with Ingress Nginx: A Step‑by‑Step Guide

In modern software development, frequent iterations and rapid feature releases are common, but they bring risks such as unforeseen bugs. Canary deployment mitigates these risks by routing a small portion of traffic to a new version, monitoring its behavior, and gradually increasing traffic if stable.

Application Scenarios

Ingress Nginx supports traffic splitting based on Header , Cookie , and Service Weight . These enable two main scenarios:

Split specific user traffic to a new version : Direct requests containing a particular header (e.g.,

foo=bar

) or cookie to the new service version, then fully switch over after validation.

Split a percentage of traffic to a new version : Route a defined proportion (e.g., 20%) of total traffic to the new version before a complete rollout.

Ingress Annotation Details

nginx.ingress.kubernetes.io/canary-by-header Routes traffic based on a specific request header. If the header value is "always", the request goes to the Canary backend; "never" forces it to the stable version; other values are ignored.

nginx.ingress.kubernetes.io/canary-by-header-value Works with

canary-by-header

to specify custom header values that trigger the Canary.

nginx.ingress.kubernetes.io/canary-by-header-pattern Similar to the previous annotation but uses a regular expression to match the header value.

nginx.ingress.kubernetes.io/canary-by-cookie Routes traffic based on a cookie value, supporting only "always" and "never".

nginx.ingress.kubernetes.io/canary-weight Specifies the percentage of traffic to send to the Canary backend (0‑100). Useful for blue‑green deployments.

Tip: Annotation evaluation follows the priority order:

canary-by-header

→

canary-by-cookie

→

canary-weight

. Non‑Canary annotations are ignored when the Ingress is marked as Canary.

Canary Configuration Examples

Header‑Based Canary

<code>$ cat <<'EOF' | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: canary
    nginx.ingress.kubernetes.io/canary-by-header-value: "true"
  name: simple-canary
  namespace: default
spec:
  ingressClassName: nginx
  rules:
  - host: simple.jiaxzeng.com
    http:
      paths:
      - backend:
          service:
            name: simple-canary
            port:
              number: 8899
        path: /
        pathType: Prefix
EOF</code>

Verify the Canary:

<code># Without Canary header
for i in `seq 3`; do curl -H "Host: simple.jiaxzeng.com" 172.139.20.100/who/hostname; done
# With Canary header
for i in `seq 3`; do curl -H "Host: simple.jiaxzeng.com" -H "canary: true" 172.139.20.100/who/hostname; done</code>

Cookie‑Based Canary

<code>$ cat <<'EOF' | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-cookie: canary
  name: simple-canary
  namespace: default
spec:
  ingressClassName: nginx
  rules:
  - host: simple.jiaxzeng.com
    http:
      paths:
      - backend:
          service:
            name: simple-canary
            port:
              number: 8899
        path: /
        pathType: Prefix
EOF</code>

Verify the Canary:

<code># Without Cookie
for i in `seq 3`; do curl -H "Host: simple.jiaxzeng.com" 172.139.20.100/who/hostname; done
# With Cookie
for i in `seq 3`; do curl -H "Host: simple.jiaxzeng.com" -H "Cookie: canary=always" 172.139.20.100/who/hostname; done</code>

Weight‑Based Canary

<code>$ cat <<'EOF' | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "30"
  name: simple-canary
  namespace: default
spec:
  ingressClassName: nginx
  rules:
  - host: simple.jiaxzeng.com
    http:
      paths:
      - backend:
          service:
            name: simple-canary
            port:
              number: 8899
        path: /
        pathType: Prefix
EOF</code>

Verify the Canary:

<code># Sample 10 requests
for i in `seq 10`; do curl -H "Host: simple.jiaxzeng.com" 172.139.20.100/who/hostname; done
# Large sample to estimate traffic share
for i in `seq 1000`; do curl -s -H "Host: simple.jiaxzeng.com" 172.139.20.100/who/hostname; done | grep canary | wc -l</code>

Tip: The weight‑based method approximates the desired traffic percentage; larger request volumes yield closer results.

Conclusion

Implementing Canary deployments with the Ingress Nginx Controller provides a reliable way to roll out new versions safely, allowing developers to test features without affecting most users and offering a quick rollback path when needed.