> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/use-gitops/argo-rollouts/argo-rollouts-overview.md).

# Argo Rollouts Overview

[Argo Rollouts](https://argoproj.github.io/rollouts/) is a progressive delivery controller for Kubernetes that provides advanced deployment capabilities such as blue-green, canary, and analysis-driven rollouts. When integrated with Harness GitOps, Argo Rollouts enables you to execute sophisticated deployment strategies declaratively while maintaining the GitOps workflow.

### Overview of Argo Rollouts and its benefits <a href="#overview-of-argo-rollouts-and-its-benefits" id="overview-of-argo-rollouts-and-its-benefits"></a>

Argo Rollouts extends Kubernetes Deployments with a new custom resource called a Rollout. This custom resource provides additional deployment strategies and features that aren't available with standard Kubernetes Deployments.

#### Key benefits <a href="#key-benefits" id="key-benefits"></a>

**Safer deployments:** Progressive rollout strategies minimize the blast radius of problematic releases by gradually shifting traffic to new versions while monitoring their health.

**Advanced deployment strategies:** Native support for canary and blue-green deployments without complex scripting or third-party service mesh requirements.

**Traffic management:** Fine-grained control over traffic shifting between different versions of your application, allowing you to test new releases with a subset of users.

**Automated analysis:** Integration with monitoring and observability tools to automatically promote or roll back deployments based on metrics and health checks.

**Declarative configuration:** Define your deployment strategies in YAML manifests that can be version-controlled alongside your application code.

**GitOps-friendly:** Works seamlessly with Argo CD and Harness GitOps to maintain a declarative, Git-based workflow for all your deployments.

#### How Argo Rollouts works with Harness GitOps <a href="#how-argo-rollouts-works-with-harness-gitops" id="how-argo-rollouts-works-with-harness-gitops"></a>

Harness GitOps integrates Argo CD with Argo Rollouts to provide a complete progressive delivery solution:

1. Rollout resources are defined in your Git repository alongside other Kubernetes manifests
2. Harness GitOps Agent syncs these resources to your cluster using Argo CD
3. Argo Rollouts controller executes the deployment strategy defined in your Rollout manifest
4. Harness pipelines can orchestrate and control rollout progression with built-in approval gates and monitoring

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before installing Argo Rollouts, ensure you have the following:

#### Harness requirements <a href="#harness-requirements" id="harness-requirements"></a>

* A Harness account with GitOps module enabled
* Appropriate permissions to create and manage GitOps applications
* A configured Harness GitOps Agent connected to your cluster

#### Kubernetes requirements <a href="#kubernetes-requirements" id="kubernetes-requirements"></a>

* Access to a Kubernetes cluster (version 1.19 or later recommended)
* Cluster admin permissions to install Custom Resource Definitions (CRDs)
* kubectl installed and configured to access your cluster

#### Optional requirements <a href="#optional-requirements" id="optional-requirements"></a>

For advanced features, you may also need:

* A service mesh (Istio, Linkerd, or SMI) for advanced traffic management
* Ingress controller (NGINX, ALB, etc.) for traffic splitting
* Monitoring tools (Prometheus, Datadog, New Relic) for analysis templates

### Installation <a href="#installation" id="installation"></a>

Argo Rollouts can be installed in your Kubernetes cluster using the CLI. This method installs the Argo Rollouts controller and its associated Custom Resource Definitions.

#### Install using the CLI <a href="#install-using-the-cli" id="install-using-the-cli"></a>

This is the quickest method to get Argo Rollouts running in your cluster.

**Step 1:** Create a dedicated namespace for Argo Rollouts:

```bash
kubectl create namespace argo-rollouts
```

**Step 2:** Apply the Argo Rollouts manifest:

```bash
kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/latest/download/install.yaml
```

This command installs:

* The Rollout Custom Resource Definition (CRD)
* The Argo Rollouts controller deployment
* Required RBAC permissions
* Service accounts and config maps

**Step 3:** Verify the installation:

```bash
kubectl get pods -n argo-rollouts
```

You should see the `argo-rollouts` controller pod running:

```
NAME                             READY   STATUS    RESTARTS   AGE
argo-rollouts-5d5b6b8c7d-xk9zt   1/1     Running   0          30s
```

### Verification steps <a href="#verification-steps" id="verification-steps"></a>

After installation, verify that Argo Rollouts is properly configured and ready to manage your deployments.

#### Verify the controller is running <a href="#verify-the-controller-is-running" id="verify-the-controller-is-running"></a>

Check that the Argo Rollouts controller pod is running and healthy:

```bash
kubectl get pods -n argo-rollouts
```

Expected output:

```
NAME                             READY   STATUS    RESTARTS   AGE
argo-rollouts-5d5b6b8c7d-xk9zt   1/1     Running   0          2m
```

#### Verify the CRDs are installed <a href="#verify-the-crds-are-installed" id="verify-the-crds-are-installed"></a>

Confirm that the Rollout custom resource definitions are registered:

```bash
kubectl get crd rollouts.argoproj.io
```

Expected output:

```
NAME                      CREATED AT
rollouts.argoproj.io      2024-01-04T10:30:00Z
```

You can also verify other related CRDs:

```bash
kubectl get crd | grep argoproj.io
```

#### Check controller logs <a href="#check-controller-logs" id="check-controller-logs"></a>

Review the controller logs to ensure there are no errors:

```bash
kubectl logs -n argo-rollouts deployment/argo-rollouts
```

Look for a log line similar to:

```
time="2024-01-04T10:30:00Z" level=info msg="Argo Rollouts starting" version=v1.6.0
```

#### Verify RBAC permissions <a href="#verify-rbac-permissions" id="verify-rbac-permissions"></a>

Ensure the controller has the necessary permissions:

```bash
kubectl get clusterrole argo-rollouts
kubectl get clusterrolebinding argo-rollouts
```

Both commands should return the respective resources without errors.

#### Install the kubectl plugin (optional) <a href="#install-the-kubectl-plugin-optional" id="install-the-kubectl-plugin-optional"></a>

For easier management of rollouts from the command line, install the Argo Rollouts kubectl plugin:

**For Linux/Mac:**

```bash
curl -LO https://github.com/argoproj/argo-rollouts/releases/latest/download/kubectl-argo-rollouts-linux-amd64
chmod +x kubectl-argo-rollouts-linux-amd64
sudo mv kubectl-argo-rollouts-linux-amd64 /usr/local/bin/kubectl-argo-rollouts
```

**For Mac (using Homebrew):**

```bash
brew install argoproj/tap/kubectl-argo-rollouts
```

Verify the plugin installation:

```bash
kubectl argo rollouts version
```

### Quick start example <a href="#quick-start-example" id="quick-start-example"></a>

Let's deploy a simple canary rollout to see Argo Rollouts in action. This example uses a demo application that will help you understand the basic workflow.

#### Step 1: Fork the demo repository <a href="#step-1-fork-the-demo-repository" id="step-1-fork-the-demo-repository"></a>

Fork or clone the Harness Rollouts demo repository:

```bash
git clone https://github.com/harness-community/Gitops-Samples
```

This repository contains several example rollout configurations in the examples/ directory.

#### Step 2: Create a GitOps application for the demo <a href="#step-2-create-a-gitops-application-for-the-demo" id="step-2-create-a-gitops-application-for-the-demo"></a>

In Harness, navigate to Deployments > GitOps > Applications

Click **+ New Application**

Configure the application:

* **Name:** `rollouts-canary-demo`
* **GitOps Agent:** Select the same agent where you installed Argo Rollouts
* **Service (optional):** Create or select a service to track this deployment
* **Environment (optional):** Create or select an environment

![](/files/v1kk8F4keRuIdeUSYGxf)

#### Step 3: Configure the application source <a href="#step-3-configure-the-application-source" id="step-3-configure-the-application-source"></a>

On the Source page:

* **Repository Type:** Git
* **Repository URL:** <https://github.com/harness-community/Gitops-Samples>
* **Target Revision:** master
* **Path:** examples/canary

The repository uses Kustomize for configuration. You can leave the Kustomize options at their defaults.

Click Continue.

![](/files/Gfx8ciSmgPMNSGvV0mkk)

#### Step 4: Configure the destination <a href="#step-4-configure-the-destination" id="step-4-configure-the-destination"></a>

* **Cluster:** Select your target cluster
* **Namespace:** Enter an existing namespace or create a new one (e.g., rollouts-demo)

Click Create.

![](/files/73vSt43Qf7msxmqQ9QaF)

#### Step 5: Monitor the initial deployment <a href="#step-5-monitor-the-initial-deployment" id="step-5-monitor-the-initial-deployment"></a>

Navigate to **Deployments > GitOps > Applications** and click on rollouts-canary-demo

Wait for the application to sync and reach a **Healthy** state

In the **Resources** tab, you'll see:

* A Rollout resource (instead of a standard Deployment)
* Two Service resources (stable and canary)
* A ReplicaSet created by the Rollout

![](/files/QNVQApErHwpeIvsivReG)

#### Step 6: Understand the canary configuration <a href="#step-6-understand-the-canary-configuration" id="step-6-understand-the-canary-configuration"></a>

The demo rollout uses a basic canary strategy. View the rollout details:

```bash
kubectl argo rollouts get rollout rollouts-demo -n rollouts-demo
```

* 20% of traffic → canary version
* Pause for manual promotion
* 40% of traffic → canary version
* Pause for manual promotion
* 60% of traffic → canary version
* Pause for manual promotion
* 80% of traffic → canary version
* Pause for manual promotion
* 100% of traffic → canary version (promotion complete)

#### Step 7: Trigger a new rollout <a href="#step-7-trigger-a-new-rollout" id="step-7-trigger-a-new-rollout"></a>

Update the image tag in your Git repository to trigger a new rollout. If you're using the demo repository, you can modify the examples/canary/kustomization.yaml file:

```yaml
images:
  - name: argoproj/rollouts-demo
    newTag: blue  # Change this to 'green', 'yellow', 'orange', etc.
```

Commit and push this change. Harness GitOps will detect the change and sync it to your cluster.

#### Step 8: Observe the canary rollout <a href="#step-8-observe-the-canary-rollout" id="step-8-observe-the-canary-rollout"></a>

1. In Harness, navigate to your application's **Resources** tab
2. Watch as the Rollout progresses through the canary stages
3. You'll see the rollout pause at each stage, waiting for manual promotion

![](/files/djsRBCAkD3BbKJfzHbQA)

To manually promote the rollout using kubectl:

```bash
kubectl argo rollouts promote rollouts-demo -n rollouts-demo
```

Repeat this command at each pause to progress through all canary stages.

#### Step 9: Access the demo application <a href="#step-9-access-the-demo-application" id="step-9-access-the-demo-application"></a>

If the demo includes a service of type LoadBalancer or you've configured an Ingress, you can access the application to see the color change as traffic shifts between versions.

Get the service endpoint:

```bash
kubectl get svc -n rollouts-demo
```

### What's next? <a href="#whats-next" id="whats-next"></a>

Now that you've seen a basic canary rollout in action, you can:

* **Configure automated promotions:** Learn how to automatically promote rollouts based on analysis
* **Set up blue-green deployments:** Explore instant traffic switching strategies
* **Integrate with Harness Pipelines:** Use pipeline steps to control rollout progression
* **Add analysis templates:** Implement automated validation with your monitoring tools

Continue to the next section to learn how to configure different rollout strategies for your applications.

#### Related resources <a href="#related-resources" id="related-resources"></a>

* [Argo Rollouts Official Documentation](https://argo-rollouts.readthedocs.io/)
* [Managing Rollouts in Harness Pipelines](/continuous-delivery/use-gitops/argo-rollouts/managing-rollouts-in-harness-pipelines.md)