Argo Rollouts: Quick Guide to Concepts, Setup, and Operations

What Is Argo Rollouts?

Argo Rollouts is a Kubernetes controller used for progressive delivery and is part of the Argo open source project. It includes a set of custom resource definitions (CRDs) that introduce advanced deployment capabilities to Kubernetes with features like progressive delivery, blue-green deployment, canary releases, and canary analysis.

Argo Rollouts offers the option of integration with service meshes and ingress controllers to leverage their traffic management capabilities and divert traffic to new versions during updates. Rollouts can also query metrics from a range of providers, interpreting them and verifying key performance indicators (KPIs) to automate rollbacks or promotions during updates. 

Argo CD UI Blue Green Deployments

The following example shows how a blue-green deployment looks in the Argo CD user interface:Image Source: Argo

This is part of an extensive series of guides about Kubernetes.

Argo Rollouts and GitOps

GitOps is a set of best practices that enable teams to manage a CI/CD pipeline by leveraging automation and ensuring the desired state is defined within a Git repository.

Kubernetes is compatible with GitOps, and tools like Argo CD are helping development teams easily implement GitOps workflows in Kubernetes. However, until recently, deployment strategies were missing a piece. 

Kubernetes provides the Deployment object that allows developers to automatically deploy applications to nodes in a Kubernetes cluster. However, the Deployment object is missing a few important deployment strategies, notably blue/green deployments and canary deployments. It is possible to implement these deployment types, but this requires customizing deployment strategies using fragile scripts or repetitive Kubernetes manifests. 

Improved Kubernetes deployments with Argo Rollouts

The Argo project set out to provide a better experience for Kubernetes developers, allowing them to easily apply all common deployment strategies while retaining the familiar user experience of the Deployment object. 

The result was Argo Rollouts, implemented as a Kubernetes Custom Resource Definition (CRD), which is designed to work like a Deployment object, similarly reliable and idempotent, but with extended functionality. 

An additional advantage of Argo Rollouts is that it integrates with Argo CD, making it easy to execute any deployment strategy with GitOps for a CI/CD pipeline.

Easy to use for anyone familiar with Deployments

The following code example (from the Argo blog) shows how similar the Argo Rollouts developer experience is to the familiar Kubernetes Deployment object.

apiVersion: # Changed from apps/v1
kind: Rollout # Changed from Deployment
# --- Everything below this comment is the same as a deployment ---
  name: example-rollout
  replicas: 1
     app: nginx
        app: nginx
      - name: nginx
        image: nginx:1.15.4
    - containerPort: 80
  minReadySeconds: 30
  revisionHistoryLimit: 3
# --- Everything above this comment are the same as a deployment ---
    blueGreen: # A new field for the Blue Green strategy options
      previewService: my-service-preview # Reference to a service
      activeService: my-service-active # Reference to a service

Only the apiVersion and kind values have changed compared to a regular Deployment object, and a blueGreen parameter at the end provides an easy way to define which Kubernetes service should be the “blue” version and which should be the “green”.

The Argo Rollouts controller executes this strategy by managing ReplicaSets, and changing Service selectors to filter traffic so it reaches the intended instance (blue or green).

How Does Argo Rollouts Work?

Argo Rollouts Architecture

Image Source: Argo

The Argo Rollouts controller is based on the Kubernetes Deployment object. It manages ReplicaSets, enabling their creation, deletion, and scaling. The Rollout resource contains a spec.template field that defines the ReplicaSets, using the pod template from the Deployment.

The Argo Rollouts controller uses any changes to the template to introduce a new ReplicaSet. The spec.strategy field contains a strategy set that the controller uses to execute the rollout and create a new ReplicaSet from the old one. The controller scales up the new ReplicaSet and (optionally) analyzes it before defining it as Stable.

The controller tries to incorporate any additional changes that occur in  spec.template while transitioning to a new ReplicaSet from a stable ReplicaSet. For example, changes made to the application version during a rollout should produce a new ReplicaSet reflecting the updated template. 

To illustrate how the Argo Rollouts controller operates, let’s see how it executes a blue-green deployment:

  1. An old and new ReplicaSet are created side by side. 
  2. The old ReplicaSet receives all traffic
  3. Developers can test the new ReplicaSet until they determine it’s safe to roll out.
  4. Once the controller has rolled out the new version, it transfers the traffic from the old ReplicaSet and scales the old version down.
Operation of Argo Rollouts Controller

Image Source: Argo Project

Argo Rollouts Concepts

Here are some of the core concepts in Argo Rollouts:


A Rollout is a Kubernetes workload resource equivalent to a Deployment. Rollouts replace Deployment objects in scenarios that require progressive delivery or advanced deployment functionality. Rollouts provide several features that Kubernetes Deployments do not, including blue-green and canary deployments, ingress controller and service mesh integration to route traffic, metric provider integration for analysis, and automated promotions and rollbacks based on success metrics. 

Progressive Delivery

A progressive delivery process involves gradually releasing updates in a controlled manner to reduce risk. Argo Rollouts usually uses metric analysis to automate update promotion or rollback.

Progressive delivery builds on the concept of continuous delivery to introduce the speed of CI/CD to the deployment process. It involves restricting a new version’s exposure to a limited set of users and gradually widening exposure based on behavior. As long as the controller can verify correct behavior, it can progressively increase exposure to more users.

Deployment Strategies

While various deployment strategies have consistent terminologies, different tools offer varying implementations of these strategies. The following descriptions outline how Argo Rollouts handles each deployment strategy: 

  • RollingUpdate—gradually replaces an old version with a new version, scaling down the old version while bringing up the new and maintaining the application’s overall count. It is the default Deployment strategy.
  • Recreate—deletes the old version of an application before bringing up a new version, ensuring that there are never two versions of an application running simultaneously. However, this deployment strategy causes downtime. 
  • Blue-Green—deploys both versions of an application simultaneously, with only the old version receiving production traffic. Developers can test the new version before shifting live traffic to it. 
  • Canary—exposes a limited set of users to the new application version while sending all other traffic to the old version. Once the controller has verified that the new version behaves correctly, it can gradually replace the old version with the new one. Service meshes and ingress controllers like Istio and NGINX enable more advanced traffic management patterns for canary deployments than native traffic shaping capabilities. For example, they can achieve more granular traffic splitting and HTTP header-based splitting.

For more information, you can reference the Argo Rollouts project GitHub repository, here.

Installing Argo Rollouts

There are several ways to install Argo Rollouts: using a Kubernetes controller, via Helm, or using Kustomize, a popular tool for customizing Kubernetes objects.

Controller Installation

Here is how to install Argo Rollouts as a controller. Run the following command to create a namespace where the Argo Rollouts controller can run:

kubectl create namespace argo-rollouts
kubectl apply -n argo-rollouts -f

You can find the latest container images for the controller on Quay. Note that the Argo project used to be hosted on Docker Hub, but has moved to Quay.

Installing Argo Rollouts with Helm

Argo Rollouts can be installed via a community-maintained Helm chart, which can be found here.

To install Argo Rollouts via Helm, run these commands:

helm repo add argo

helm install my-release argo/argo-rollouts

After installation, install the Argo dashboard using this command:

--set dashboard.enabled=true

Activate the dashboard using this command:

kubectl port-forward service/argo-rollouts-dashboard 31000:3100

The UI will then be available at address localhost:31000

Installing Argo Rollouts Using Kustomize 

You can use kustomize to follow CRD object structure and add useful features like ConfigMap and Secret generation, common labels, and annotations. 

To deploy Argo Rollouts with kustomize, download the rollout-transform.yaml file(it is available here) and save it to your kustomize directory. 

Then include the file in your kustomize configurations section, like this:

kind: Kustomization

- rollout-transform.yaml

Quick Tutorial: Canary Deployment with Argo Rollouts

Let’s see how to perform a canary deployment using a Rollout object managed by Argo Rollouts. The steps and code are abbreviated from the official quick start tutorial.

1. Deploy a Rollout

The first step is to create a Rollout object that specifies your deployment strategy. For example, the below strategy specifies a Canary deployment.

  replicas: 5
      - setWeight: 20
      - pause: {}
      - setWeight: 40
      - pause: {duration: 10}
      - setWeight: 60
      - pause: {duration: 10}
      - setWeight: 80
      - pause: {duration: 10}

This code initially deploys a new version to 20% of the pods, then waits for manual action – this is the pause: {} command. After an operator approves the deployment, it is automatically delivered to 40%, then 60%, then 80%, and finally 100% of the pods, with intervals of 10 minutes.

Use this command to deploy the Rollout:

kubectl apply -f

And use this command to run a service that references the Rollout:

kubectl apply -f

The first time you deploy the Rollout, it will immediately scale to 100% because there was no update. Run this command to see the status of the Rollout:

kubectl argo rollouts get rollout rollouts-demo --watch
Deploy a Rollout Tutorial

Image Source: Argo

The baseline version of the application has been deployed to 5 pods.

2. Update the Rollout

Every time you update the spec.template of the pods in your Rollout, a new version will be deployed, with canary deployment behavior as we specified in step 1. 

Use this command to update rollouts-demo

Rollout a new version called “yellow”:

kubectl argo rollouts set image rollouts-demo \


Recall that the rollout strategy specified that the new version should be deployed to only 20% of the traffic and then pause and wait for operator approval. To see that this really took place, run the get rollout command again:

get rollout Command

Image Source: Argo

This is exactly what we wanted—the new version of the application, labeled revision:2, has been deployed to one pod out of five (20% of the pods). The Rollout now stops and waits for an operator to check the deployment.

3. Promote the Rollout

Our configuration indicated that after scaling the canary to 20%, the Rollout should stop indefinitely and wait for an operator. Use this command to promote the Rollout, which means the new version looks good and we want to continue the deployment:

kubectl argo rollouts promote rollouts-demo

Now the Rollout executes the remaining steps—scaling the canary to 40%, waiting 10 minutes, scaling to 60%, etc.—until it scales the canary to 100%. Run get rollout during this process if you want to see the Rollout in action. After 40 minutes, run it one last time to see the end result:

Argo Rollouts Demo Final Step

Image Source: Argo

You can see that revision:1, the original version, appears as ScaledDown, and ScaledDown now has five running pods. The canary deployment has completed successfully.


Argo Rollouts extends the capabilities of the Kubernetes Deployment object, allowing teams to easily implement advanced progressive delivery strategies. We provided a quick tutorial that shows how this happens in three primary steps:

  1. You deploy a Rollout by applying a Rollout object in your Kubernetes cluster just like you would do with a Deployment. The Rollout manifest defines the specifics of the deployment strategy.
  2. Update the Rollout to reflect a new version of the application. The Rollout then executes the first phase of the deployment strategy – for example, deploying a canary to 20% of the pods. 
  3. Promote the Rollout by making the new version of the application the primary production version.

We hope this will be useful as you adopt progressive delivery in your Kubernetes clusters. 

See Additional Guides on Key Kubernetes Topics

Together with our content partners, we have authored in-depth guides on several other topics that can also be useful as you explore the world of Kubernetes.

Kubernetes Architecture

Authored by Komodor

Container Security

Authored by Tigera

Kubernetes Security

Authored by Tigera

The World’s Most Modern CI/CD Platform

A next generation CI/CD platform designed for cloud-native applications, offering dynamic builds, progressive delivery, and much more.

Check It Out

How useful was this post?

Click on a star to rate it!

Average rating 4.8 / 5. Vote count: 4

No votes so far! Be the first to rate this post.