Mastering Canary Releases with Argo Rollout: A Step‑by‑Step Guide

Introduction

Canary release (also called gray release) is a deployment technique that routes a small portion of production traffic to a new version for validation before a full rollout. Combined with Argo Rollout , the process can be fully automated.

Canary Overview

The architecture consists of two deployments – a stable prod environment and a canary environment – each with its own Service. An Ingress‑Nginx gateway forwards traffic to the Services based on weight (e.g., 20% to canary, 80% to prod) or on a special request header X-Canary.

In the diagram, the same application is deployed twice: a production Prod environment and a canary Canary environment. Traffic is split by the Ingress controller according to the configured weight or header.

Manual Canary Deployment

1. Create the production deployment and Service

apiVersion: apps/v1
kind: Deployment
metadata:
  name: prod
  labels:
    app: prod
spec:
  replicas: 1
  selector:
    matchLabels:
      app: prod
  template:
    metadata:
      labels:
        app: prod
    spec:
      containers:
      - name: demo
        image: argoproj/rollouts-demo:blue
        imagePullPolicy: Always
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: prod-service
  labels:
    app: prod
spec:
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  selector:
    app: prod
  type: ClusterIP

Apply the files:

kubectl apply -f prod_deployment.yaml
kubectl wait pods -l app=prod --for condition=Ready --timeout=90s

Ingress for production:

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: prod-ingress
spec:
  entryPoints:
  - web
  routes:
  - match: Host(`canary.demo`) && PathPrefix(`/`)
    kind: Rule
    services:
    - name: prod-service
      port: 80

Visit the production URL http://canary.demo/ to see the blue version.

Deploy the Canary Environment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: canary
  labels:
    app: canary
spec:
  replicas: 1
  selector:
    matchLabels:
      app: canary
  template:
    metadata:
      labels:
        app: canary
    spec:
      containers:
      - name: demo
        image: argoproj/rollouts-demo:green
        imagePullPolicy: Always
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: canary-service
  labels:
    app: canary
spec:
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  selector:
    app: canary
  type: ClusterIP

Canary Ingress (NGINX annotations):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: canary-ingress-canary
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
    nginx.ingress.kubernetes.io/canary-by-header: "X-Canary"
spec:
  rules:
  - host: "canary.demo"
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: canary-service
            port:
              number: 80

When the request header X-Canary: always is present, traffic is routed to the canary service regardless of weight.

For Traefik the same logic can be expressed with a WeightedTraefikService and an IngressRoute that references it.

Automating Canary with Argo Rollout

Create a Rollout object that defines the canary strategy, traffic routing, and stepwise weight changes.

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: canary-demo
  labels:
    app: canary-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: canary-demo
  template:
    metadata:
      labels:
        app: canary-demo
    spec:
      containers:
      - name: canary-demo
        image: argoproj/rollouts-demo:blue
        imagePullPolicy: Always
        ports:
        - name: http
          containerPort: 8080
          protocol: TCP
        resources:
          requests:
            memory: 32Mi
            cpu: 5m
  strategy:
    canary:
      canaryService: canary-demo-canary
      stableService: canary-demo
      trafficRouting:
        nginx:
          stableIngress: canary-demo
          additionalIngressAnnotations:
            canary-by-header: X-Canary
      steps:
      - setWeight: 20
      - pause: {}
      - setWeight: 50
        pause:
          duration: 30s
      - setWeight: 70
        pause:
          duration: 30s

Apply the rollout: kubectl apply -f canary-rollout.yaml The rollout dashboard (Argo Rollout UI) shows the current step, pause points, and weight values.

When the rollout reaches the final step, the canary weight is set to 0, the stable Service selector is switched to the canary pods, and the old ReplicaSet is scaled down, effectively promoting the canary to production.

Verification

Use curl with the special header to confirm traffic is served by the canary version:

for i in $(seq 1 10); do curl -H "X-Canary: always" http://canary.auto/color; done

The response should contain the string green, indicating the canary image is active.

Conclusion

The tutorial covered the fundamentals of canary releases, manual setup of production and canary environments, traffic splitting by weight and header, and full automation using Argo Rollout. By defining the rollout steps, weight changes, and optional manual approvals, teams can safely validate new versions with real traffic before promoting them to production.