Demo Progressive Delivery with Argo Rollouts

Deployments that replace all pods at once are risky: a bad image can cause widespread user errors before you detect the problem. Progressive delivery lets you gradually shift traffic to a new version—observe metrics at each step and abort if something looks wrong so traffic reverts to the stable version. Argo Rollouts implements progressive delivery for Kubernetes as a drop-in replacement for Deployments. In this guide you’ll:

Verify Argo Rollouts is running
Create a basic Rollout (Canary)
Update canary steps to incrementally shift traffic
Promote a canary and change images
Adopt an existing Deployment with workloadRef
Inspect Rollout status using the CLI and dashboard

Make sure you have the Argo Rollouts controller and dashboard installed and that you have the kubectl argo rollouts plugin available. The examples below assume a canary-demo namespace.

Prerequisites

Kubernetes cluster with kubectl access
Argo Rollouts controller and dashboard installed (namespace: argo-rollouts)
Optional: traffic routing provider configured (Istio, NGINX, SMI) for precise traffic splitting

Verify the controller and dashboard are running:

kubectl get pods -n argo-rollouts

Example output:

NAME                                      READY   STATUS    RESTARTS   AGE
argo-rollouts-5f64f8d68-lxr9s            1/1     Running   0          10m
argo-rollouts-dashboard-755bbbc64c-59rhx 1/1     Running   0          10m

Creating a basic Rollout (Canary)

This Rollout uses a Canary strategy with two steps: set 25% traffic to the new ReplicaSet, then pause indefinitely until you promote.

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: rollout-demo
  namespace: canary-demo
spec:
  replicas: 4
  selector:
    matchLabels:
      app: rollout-demo
  template:
    metadata:
      labels:
        app: rollout-demo
    spec:
      containers:
      - name: demo
        image: argoproj/rollouts-demo:blue
        ports:
        - containerPort: 8080
  strategy:
    canary:
      steps:
      - setWeight: 25
      - pause: {}

Notes on the behavior:

Without a traffic provider, Rollouts approximates weights by scaling ReplicaSets (so weights map to pod counts).
With a traffic routing provider (Istio, NGINX, SMI), Rollouts will use actual request routing to enforce weights.

If you get an error such as:

Error from server (BadRequest): error when creating "rollout.yaml": Rollout in version "v1alpha1" cannot be handled as a Rollout: strict decoding error: unknown field "spec.strategy.canary.step"

it’s likely a typo (e.g., step instead of steps). Fix the key and reapply. Inspect the Rollout with the Argo Rollouts kubectl plugin:

kubectl argo rollouts get rollout rollout-demo -n canary-demo

Sample summarized status output:

Name:                rollout-demo
Namespace:           canary-demo
Status:              ✓ Healthy
Strategy:            Canary
  Step:              2/2
  SetWeight:         100
  ActualWeight:      100
Images:              argoproj/rollouts-demo:blue (stable)
Replicas:
  Desired:           4
  Current:           4
  Updated:           4
  Ready:             4
  Available:         4

Updating the canary steps

You can expand the canary steps to incrementally increase traffic, inserting pauses so you can observe metrics between increases. Example: 25%, 50%, 75%, then 100%:

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: rollout-demo
  namespace: canary-demo
spec:
  replicas: 4
  selector:
    matchLabels:
      app: rollout-demo
  template:
    metadata:
      labels:
        app: rollout-demo
    spec:
      containers:
      - name: demo
        image: argoproj/rollouts-demo:blue
        ports:
        - containerPort: 8080
  strategy:
    canary:
      steps:
      - setWeight: 25
      - pause: {}
      - setWeight: 50
      - pause: {}
      - setWeight: 75
      - pause: {}
      - setWeight: 100

Apply the updated manifest:

kubectl apply -f rollout.yaml

Verify the configured steps and current step with:

kubectl argo rollouts get rollout rollout-demo -n canary-demo

Promoting a canary

To move a paused canary to the next step via CLI:

kubectl argo rollouts promote rollout-demo -n canary-demo

If you haven’t changed the image (no new revision), promoting will do nothing because there is no new revision to advance. Change the image in the Rollout spec to create a new revision. For example, update the container image to yellow:

      containers:
      - name: demo
        image: argoproj/rollouts-demo:yellow
        ports:
        - containerPort: 8080

Apply the change:

kubectl apply -f rollout.yaml

When the new revision appears, Rollouts will create pods for it according to the current canary weight. With 4 replicas and a 25% step, expect one pod on the new image and three on the old image. Check pods:

kubectl get pods -n canary-demo

Example:

NAME                             READY   STATUS    RESTARTS   AGE
rollout-demo-544bf7c68b-6jhn     1/1     Running   0          5m7s   # blue
rollout-demo-544bf7c68b-6lzzj    1/1     Running   0          5m7s   # blue
rollout-demo-544bf7c68b-bpbdw    1/1     Running   0          5m7s   # blue
rollout-demo-5748bdbcb6-gm7l7    1/1     Running   0          42s    # yellow

Promote step-by-step (either CLI or the Rollouts dashboard) to 50% (two pods), 75% (three pods), and finally 100% (all pods). From the UI you can also Promote Full or rollback to the previous stable revision.

A screenshot of the Argo Rollouts web UI for a "rollout-demo" canary deployment, showing steps, summary, containers, and revision history. The left column lists set-weight and pause steps (25%, 50%, 75%), while the right shows container images and revision details.

Adopting an existing Deployment with workloadRef

If you already have a Deployment running and want to add progressive delivery without recreating it, use workloadRef. The Rollout will take control of the referenced Deployment, manage scaling, and create revisions. Create a Deployment that Rollouts can adopt. Note: replicas: 0 so the Rollout will scale it when it takes control.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-app
  namespace: canary-demo
spec:
  replicas: 0
  selector:
    matchLabels:
      app: demo-app
  template:
    metadata:
      labels:
        app: demo-app
    spec:
      containers:
      - name: demo-app
        image: argoproj/rollouts-demo:blue
        ports:
        - containerPort: 8080

Apply the Deployment:

kubectl apply -f deployment.yaml

Now create a Rollout that references this Deployment with workloadRef:

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: demo-app-rollout
  namespace: canary-demo
spec:
  replicas: 4
  workloadRef:
    apiVersion: apps/v1
    kind: Deployment
    name: demo-app
  strategy:
    canary:
      steps:
      - setWeight: 10
      - pause: {}
      - setWeight: 50
      - pause: {}
      - setWeight: 100

Apply the Rollout:

kubectl apply -f workloadref-rollout.yaml

The Rollout will scale the referenced Deployment to the requested replica count and create ReplicaSets/pods under the Rollout controller. Check pods:

kubectl get pods -n canary-demo

Example output showing Rollout-created pods:

NAME                                            READY   STATUS    RESTARTS   AGE
demo-app-rollout-677bb5cc8-6cxs5                1/1     Running   0          53s
demo-app-rollout-677bb5cc8-c4x6q                1/1     Running   0          53s
demo-app-rollout-677bb5cc8-rbxg4                1/1     Running   0          53s
demo-app-rollout-677bb5cc8-sbkmr                1/1     Running   0          53s
rollout-demo-5748bdcbb6-2qh8m                   1/1     Running   0          5m9s

A web dashboard (Argo Rollouts) showing two rollout cards — "demo-app-rollout" and "rollout-demo" — each using a Canary strategy with revision entries, pod status checks, and Restart/Promote buttons. The namespace "canary-demo" is visible in the top-right.

Using workloadRef is useful when you want to add progressive delivery to an existing Deployment without replacing or owning it immediately—Argo Rollouts will take control of scaling and revisions for that workload.

Inspecting canary steps and revision history

You can view canary steps, revision history, and perform promote/rollback actions in the Rollouts dashboard. The UI shows each step (set weight / pause), the current traffic split, and revision details.

A screenshot of the Argo Rollouts web UI for "demo-app-rollout" showing a canary deployment with steps to set traffic weights (10%, 50%, 100%) interleaved with pauses. The right panels display the strategy summary, container image (argoproj/rollouts-demo:blue) and a revision marked stable.

Quick reference: common Rollouts commands

Command	Purpose	Example
Get Rollout status	See current step, weight, and health	`kubectl argo rollouts get rollout rollout-demo -n canary-demo`
Promote canary	Advance a paused canary to next step	`kubectl argo rollouts promote rollout-demo -n canary-demo`
View pods	List pods in the namespace	`kubectl get pods -n canary-demo`
Apply manifest	Create or update resources	`kubectl apply -f rollout.yaml`

Summary

Argo Rollouts adds progressive delivery strategies (Canary, Blue/Green) and can act as a drop-in replacement for Deployments.
Define canary.steps to control traffic weight and pauses; with a traffic provider the routing is precise, otherwise Rollouts approximates using pod counts.
Promote canaries via CLI (kubectl argo rollouts promote) or the dashboard. You can also roll back to a stable revision.
Use workloadRef to adopt existing Deployments without recreating them.

Links and references

Argo Rollouts project: https://argoproj.github.io/argo-rollouts/
Argo Rollouts GitHub: https://github.com/argoproj/argo-rollouts
Kubernetes Deployments docs: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/
Istio traffic shifting (example provider): https://istio.io/latest/docs/tasks/traffic-management/

Practice progressive delivery with hands-on exercises to internalize the workflow: create Rollouts, iterate on canary steps, promote revisions, and adopt existing Deployments using workloadRef.

Course Introduction

Platform Architecture and Infrastructure

GitOps and Continuous Delivery

Platform APIs and Self-Service Capabilities

Observability and Operations

Security and Policy Enforcement

Conclusion

Demo Progressive Delivery with Argo Rollouts

Prerequisites

Creating a basic Rollout (Canary)

Updating the canary steps

Promoting a canary

Adopting an existing Deployment with workloadRef

Inspecting canary steps and revision history

Quick reference: common Rollouts commands

Summary

Links and references

Watch Video

Practice Lab

​Prerequisites

​Creating a basic Rollout (Canary)

​Updating the canary steps

​Promoting a canary

​Adopting an existing Deployment with workloadRef

​Inspecting canary steps and revision history

​Quick reference: common Rollouts commands

​Summary

​Links and references

Watch Video

Practice Lab

Prerequisites

Creating a basic Rollout (Canary)

Updating the canary steps

Promoting a canary

Adopting an existing Deployment with workloadRef

Inspecting canary steps and revision history

Quick reference: common Rollouts commands

Summary

Links and references