Master Canary Deployments with Argo Rollout: A Step‑by‑Step Guide

Introduction

Blue‑green deployment swaps an entire environment at once, while canary deployment gradually shifts a small portion of production traffic to a new version for testing. Canary releases are achieved by routing a percentage of traffic or specific request headers to the canary environment.

Canary Deployment Overview

The architecture deploys two sets of services: a Prod environment and a Canary environment. An Ingress‑Nginx gateway forwards traffic based on weight (e.g., 20% to canary, 80% to prod) or a special header ( X‑Canary).

Manual Setup

1. Create the production deployment and service :

cat prod_deployment.yaml
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
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: prod-service
  labels:
    app: prod
spec:
  selector:
    app: prod
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  type: ClusterIP

Apply with kubectl apply -f prod_deployment.yaml and create an Ingress that routes all traffic to prod-service.

2. Create the canary deployment and service :

cat canary_deployment.yaml
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
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: canary-service
  labels:
    app: canary
spec:
  selector:
    app: canary
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  type: ClusterIP

Apply with kubectl apply -f canary_deployment.yaml.

3. Configure canary Ingress (NGINX) :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: canary-ingress
  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:
      - path: "/"
        pathType: Prefix
        backend:
          service:
            name: canary-service
            port:
              number: 80

For Traefik, use a TraefikService with weighted routing and an IngressRoute that references it.

Automating Canary with Argo Rollout

Create a Rollout object that defines the canary strategy, weight steps, and optional pauses:

cat canary-rollout.yaml
apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: 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
        ports:
        - name: http
          containerPort: 8080
  strategy:
    canary:
      canaryService: canary-demo-canary
      stableService: canary-demo
      steps:
      - setWeight: 20
      - pause: {}
      - setWeight: 50
      - pause:
          duration: 30s
      - setWeight: 70
      - pause:
          duration: 30s

Apply with kubectl apply -f canary-rollout.yaml. Argo Rollout will automatically create a new ReplicaSet, adjust the Service selector, and modify the Ingress annotations ( nginx.ingress.kubernetes.io/canary-weight) to shift traffic according to the defined steps.

To promote manually during a pause, run kubectl argo rollouts promote canary-demo. After all steps complete, the canary environment becomes the stable production environment and the old ReplicaSet is scaled down.

Automation Principles

Argo Rollout manipulates three Kubernetes objects during a canary release:

ReplicaSet : creates a new set for the canary version.

Service : switches its selector to point to the canary pods when needed.

Ingress : updates the canary-weight annotation to control traffic percentage and uses canary-by-header for header‑based routing.

When the rollout finishes, the canary Ingress weight is set to 0, the stable Service selector is updated to the canary pods, and the old ReplicaSet is scaled to zero, completing the promotion.

Conclusion

Canary releases provide fine‑grained traffic control and risk mitigation compared to blue‑green deployments. Using Argo Rollout, the entire process—from defining weight steps to automatic promotion—can be expressed as declarative YAML, enabling seamless GitOps integration and reducing manual effort.