> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Demo Progressive Delivery with Argo Rollouts

> Guide to using Argo Rollouts for progressive delivery on Kubernetes, demonstrating canary strategies, traffic shifting, promotion, rollback, and adopting existing Deployments via workloadRef

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:

```shell theme={null}
kubectl get pods -n argo-rollouts
```

Example output:

```text theme={null}
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.

```yaml theme={null}
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:

```text theme={null}
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:

```shell theme={null}
kubectl argo rollouts get rollout rollout-demo -n canary-demo
```

Sample summarized status output:

```text theme={null}
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%:

```yaml theme={null}
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:

```shell theme={null}
kubectl apply -f rollout.yaml
```

Verify the configured steps and current step with:

```shell theme={null}
kubectl argo rollouts get rollout rollout-demo -n canary-demo
```

## Promoting a canary

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

```shell theme={null}
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`:

```yaml theme={null}
      containers:
      - name: demo
        image: argoproj/rollouts-demo:yellow
        ports:
        - containerPort: 8080
```

Apply the change:

```shell theme={null}
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:

```shell theme={null}
kubectl get pods -n canary-demo
```

Example:

```text theme={null}
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.](https://mintcdn.com/kodekloud-c4ac6d9a/8pYzlc1aD6cgTw8b/images/Prep-Course-Certified-Cloud-Native-Platform-Engineering-CNPE/GitOps-and-Continuous-Delivery/Demo-Progressive-Delivery-with-Argo-Rollouts/argo-rollouts-rolloutdemo-canary-steps.jpg?fit=max\&auto=format\&n=8pYzlc1aD6cgTw8b\&q=85\&s=6aafb4317ae1b0c200e23a44d3219701)

## 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.

```yaml theme={null}
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:

```shell theme={null}
kubectl apply -f deployment.yaml
```

Now create a Rollout that references this Deployment with `workloadRef`:

```yaml theme={null}
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:

```shell theme={null}
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:

```shell theme={null}
kubectl get pods -n canary-demo
```

Example output showing Rollout-created pods:

```text theme={null}
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.](https://mintcdn.com/kodekloud-c4ac6d9a/8pYzlc1aD6cgTw8b/images/Prep-Course-Certified-Cloud-Native-Platform-Engineering-CNPE/GitOps-and-Continuous-Delivery/Demo-Progressive-Delivery-with-Argo-Rollouts/argo-rollouts-canary-demo-dashboard.jpg?fit=max\&auto=format\&n=8pYzlc1aD6cgTw8b\&q=85\&s=b0f120047f12fc760fd30f9d17ff975f)

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.](https://mintcdn.com/kodekloud-c4ac6d9a/8pYzlc1aD6cgTw8b/images/Prep-Course-Certified-Cloud-Native-Platform-Engineering-CNPE/GitOps-and-Continuous-Delivery/Demo-Progressive-Delivery-with-Argo-Rollouts/argo-rollouts-demo-app-canary-steps.jpg?fit=max\&auto=format\&n=8pYzlc1aD6cgTw8b\&q=85\&s=60cad0abe668d05d84722eba2a6025a1)

## 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/](https://argoproj.github.io/argo-rollouts/)
* Argo Rollouts GitHub: [https://github.com/argoproj/argo-rollouts](https://github.com/argoproj/argo-rollouts)
* Kubernetes Deployments docs: [https://kubernetes.io/docs/concepts/workloads/controllers/deployment/](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
* Istio traffic shifting (example provider): [https://istio.io/latest/docs/tasks/traffic-management/](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`.

> **[Watch Video](https://learn.kodekloud.com/user/courses/prep-course-certified-cloud-native-platform-engineer-cnpe/module/dff5382b-dbe7-4cac-bd2b-d5a47028945e/lesson/a0077fb2-6b11-4efb-a3e6-a2eb38e6b16e)**

> **[Practice Lab](https://learn.kodekloud.com/user/courses/prep-course-certified-cloud-native-platform-engineer-cnpe/module/dff5382b-dbe7-4cac-bd2b-d5a47028945e/lesson/52cac868-334e-4f7b-8cf5-be4a61331d73)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.