How to Install Argo Rollouts on Your Kubernetes Cluster (Step‑by‑Step)

Introduction

Deploying applications safely in a Kubernetes environment can be challenging, especially when you need zero downtime, controlled releases, and quick rollbacks. Argo Rollouts helps address these challenges by enabling advanced deployment strategies such as canary releases, blue-green deployments, and automated analysis. If you’re running workloads on Kubernetes, installing Argo Rollouts is one of the smartest ways to improve release reliability and reduce production risks.

In this step-by-step guide, you’ll learn how to install Argo Rollouts on your Kubernetes cluster, configure the controller, and verify that everything is running correctly. Whether you’re setting up Rollouts for the first time or preparing for production deployments, this guide will walk you through the entire process in a clear and practical way.

What Argo Rollouts Is and Why It Matters

Modern teams rarely want to ship a new version of an application all at once. A single bad deployment can introduce downtime, break key user flows, or quietly damage performance until someone notices. Kubernetes’ built‑in Deployment resource is great for basic rollouts, but it does not natively support the kind of careful, metrics‑driven progressive delivery that most production teams now expect.

Argo Rollouts fills that gap. It is a Kubernetes controller plus a set of Custom Resource Definitions (CRDs) that extend your cluster with advanced deployment strategies such as canary, blue‑green, and progressive delivery backed by real‑time analysis. Instead of flipping traffic from old to new in one step, you can move traffic in stages, observe how the new version behaves, and automatically pause, promote, or roll back.

To unlock these capabilities, you first need Argo Rollouts itself running inside your cluster. That means installing its CRDs so the Kubernetes API understands new resource types like Rollout and AnalysisRun, and deploying the controller to watch those resources and make decisions.

Prerequisites for Installing Argo Rollouts on Kubernetes

Before you start applying manifests to a cluster, it is worth pausing to confirm a few essentials. Many of the classic “it does not work” installation problems stem from basic connectivity, permissions, or version mismatches rather than from issues with Argo Rollouts itself.

Kubernetes and kubectl versions

You should have access to a functioning Kubernetes cluster and a reasonably recent version of kubectl installed on your machine. For most production environments, Kubernetes 1.21 or newer is a safe baseline, and you should aim to keep kubectl in sync with your cluster’s minor version.

Run a quick sanity check:

kubectl version --short

kubectl config current-context

kubectl get nodes

If these commands fail, or if you do not see the cluster you expect, fix that first. Argo Rollouts deploys as a controller in Kubernetes; if you cannot consistently reach the API server, you will not get a reliable installation.

Access and permissions

Installing Argo Rollouts is not something you should do as a tightly restricted application user. The controller requires CRDs, cluster roles, role bindings, and a dedicated namespace. Typically, you will need at least cluster‑admin privileges during installation, or you will need a platform or SRE team to apply the manifests for you.

If you are working on a local cluster such as Kind, Minikube, or Docker Desktop, your default kubectl context is often already sufficient. In multi‑tenant or production environments, double‑check that you are using a context with adequate rights and that your organization is comfortable with you installing cluster‑wide components.

Cluster types and where to install

Argo Rollouts works across a wide range of Kubernetes distributions: managed services such as GKE, EKS, and AKS; self‑managed clusters on virtual machines; and local development clusters. It is helpful to decide up front whether you are installing into:

• A local or sandbox cluster where you can freely experiment.
• A shared staging or pre‑production environment.
• A production environment running real user traffic.

For your very first installation, a non‑production cluster is ideal. You can learn the basic commands, verify the controller’s behavior, and, once you are comfortable, repeat the process in staging and production.

Choose Where to Deploy Argo Rollouts in Your Cluster

The first practical step is deciding exactly where in your ecosystem you want the Argo Rollouts controller to live. In most setups, you deploy one controller per cluster and let it manage rollouts across multiple application namespaces.

If you already separate your workloads by environment, perhaps one cluster for staging and one for production, you will usually install Argo Rollouts in each cluster separately. Keeping each environment isolated in this way avoids unexpected cross‑environment interactions and aligns with how Kubernetes itself is typically managed.

Within each cluster, it is a common pattern to give Argo Rollouts its own dedicated namespace. In this guide, you will use the namespace argo-rollouts. This keeps the controller’s pods, service accounts, and configuration clearly separated from application namespaces like default or production.

Before you proceed, confirm your current context so you do not accidentally install into the wrong cluster:

kubectl config current-context

If the name does not match the cluster you intend to use, switch it explicitly:

kubectl config use-context <your-context-name>

It is worth taking this extra moment, especially when your kubeconfig contains both experimental clusters and critical production environments.

Create the argo-rollouts Namespace

Once you have confirmed the cluster and context, create the namespace that will host the controller. Namespaces give you a natural way to group related resources, apply policies, and keep your mental model tidy.

Create the namespace with a single command:

kubectl create namespace argo-rollouts

If the namespace already exists from a previous attempt or from a GitOps tool, Kubernetes will respond with an “AlreadyExists” error. That is not a problem; it simply means you can move on to the next step.

Verify that the namespace is present and active:

kubectl get namespace argo-rollouts

You should see Active in the STATUS column. If the namespace is stuck in a terminating state, investigate any finalizers or controllers that might be blocking deletion or recreation before you proceed.

Install the CRDs and Controller Using the Official Manifest

With the namespace in place, you are ready to install the actual Argo Rollouts components. The project publishes an official manifest file, often named install.yaml, that bundles the CRD definitions, service accounts, roles, role bindings, and the controller deployment.

Using the official manifest keeps the initial experience straightforward. Instead of hunting down separate YAML files, you apply a single URL and let Kubernetes create all the required pieces in one go.

Getting the install manifest

You will typically find the latest installation command in the Argo Rollouts documentation or release notes. It usually looks something like this, with the exact version adjusted for the current release:

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

This command does two important things. First, it targets the argo-rollouts namespace you created earlier using the -n flag. Second, it applies the contents of install.yaml directly from the remote URL, so you do not have to download and manage the file locally for a quick start.

If your organization prefers strict version pinning, you can replace latest with a specific version, store the YAML in version control, and apply that file instead. The overall mechanics remain the same.

Applying the manifests safely

When you run the kubectl apply command, Kubernetes will create or update all the objects defined in the manifest. On a new cluster without a previous Argo Rollouts installation, you should see a sequence of “created” messages for CRDs, roles, role bindings, and the deployment.

If you are upgrading from a previous version, the messages will often show “configured” instead. In that case, pay extra attention to the release notes for any recommended upgrade steps, particularly those related to CRDs, but the installation flow is otherwise very similar.

Understanding what gets created

After the apply completes, you can inspect the argo-rollouts namespace to see what is now running there. The key component is a deployment named argo-rollouts or argo-rollouts-controller that manages one or more controller pods.

List the key resources:

kubectl get all -n argo-rollouts

You should see at least one pod in a Running state, backed by a deployment and potentially a service that other components can use to reach the controller. The manifest also installs CRDs such as rollouts.argoproj.io and analysisruns.argoproj.io, which extend the Kubernetes API to create new object types.

If any pods are stuck in Pending or CrashLoopBackOff, make a note of that, you will use logs in the verification step to understand what is going wrong.

Verify the Argo Rollouts Installation

Once the manifests are applied, do not assume everything is fine just because there were no obvious errors. A short verification pass helps you catch permission issues, image problems, or CRD registration delays before they surface as rollout failures later.

Checking that CRDs are registered

The first check confirms that the Kubernetes API server recognizes the new Argo Rollouts resource types. You can do this by listing the CRDs and looking for the ones associated with the project:

kubectl get crds | grep rollouts.argoproj.io

You should see entries like rollouts.argoproj.io and analysisruns.argoproj.io. If the command returns nothing, the CRDs were not created correctly. That can happen if the manifest failed partway through, if your user did not have permission to create CRDs, or if another tool is blocking cluster‑wide changes.

Confirming the controller pod is healthy

Next, confirm that the controller pod is up and running in the argo-rollouts namespace:

kubectl get pods -n argo-rollouts

You should see at least one pod with status Running and a READY column like 1/1. If the pod is restarting repeatedly, describe it to see more details:

kubectl describe pod <pod-name> -n argo-rollouts

• Look for clues around image pull errors, missing permissions, or resource limits. If the pod is running but you are curious about what it is doing, view the logs:

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

• You should see messages that indicate the controller has started, registered informers, and is watching the cluster for Rollout resources.

Running a quick API check

As a final API‑level check, you can ask Kubernetes to list Argo Rollouts resources even if you have not created any yet. The command should succeed, even if it returns an empty list:

kubectl get rollouts --all-namespaces

If this command fails with an error like “the server doesn’t have a resource type rollouts,” then the CRDs are still not registered correctly, and you will need to revisit the installation step.

Optionally Install the Argo Rollouts Dashboard

Many teams like to start with CLI‑only workflows, but the Argo Rollouts project also ships a simple web dashboard that lets you visualize rollouts, examine steps, and trigger promotions or rollbacks through a browser.

If your installation manifest already included the dashboard service and deployment, you may only need to expose it. In other cases, you can apply an additional manifest provided in the official documentation.

A common way to access the dashboard without exposing it to the internet is to use kubectl port-forward. Once the dashboard is installed, you can run a command such as:

kubectl port-forward -n argo-rollouts svc/argo-rollouts-dashboard 3100:3100

With that command running, you can open a browser and visit http://localhost:3100 to interact with the dashboard. This keeps access tightly scoped to people who have kubectl access to the cluster while still giving you a visual view of rollout activity.

Deploy a Sample Rollout to Test Installation

At this point, Argo Rollouts is installed, but you have not yet seen it do any real work. Creating a small sample rollout is a good way to validate your understanding and confirm that the controller responds to new resources as you expect.

• Start by choosing or creating a namespace for your sample application. Using a clearly named sandbox namespace keeps test resources away from production workloads. For example:

kubectl create namespace rollouts-demo

• Next, apply a simple example Rollout resource along with any required services. The official documentation provides examples you can copy, but conceptually, you are creating a resource that looks similar to a Deployment with a few extra fields that describe your rollout strategy.
• Once the sample Rollout is applied, list it:

kubectl get rollouts -n rollouts-demo

• You should see a rollout object with a status that reflects its progress. As it moves through steps, the controller will update the status field to show how much traffic is on each version and whether it is paused, progressing, or completed.
• You can then test a basic update by changing the container image tag in the rollout spec and applying the change. Watching how the status evolves will give you a feel for how Argo Rollouts behaves before you connect it to a real production service.

Operational Tips and Best Practices

Once Argo Rollouts is up and running, a few simple habits will make ongoing operations smoother and safer.

Keep installation manifests under version control

Even if you start with the convenience of applying a remote install.yaml, it is wise to bring that file under version control as soon as possible. Storing it in a Git repository alongside your infrastructure or platform configuration gives you a clear history of which version is installed in which environment.

With version control in place, upgrades become more deliberate. You can review diffs between manifest versions, test changes in a staging cluster, and roll them out to production only then.

Align environments and rollout strategies

Because Argo Rollouts is installed per cluster, make sure your environments stay aligned. If you test a particular canary or blue‑green pattern in staging using one version of the controller, aim to keep production close to that version so behaviors match. This alignment reduces surprises when a rollout that behaved one way in staging acts differently in production due to subtle changes between releases.

Monitor the controller like any critical service

Treat the Argo Rollouts controller as a first‑class part of your platform. Expose its metrics if available, set up alerts on crash loops or prolonged unavailability in the argo-rollouts namespace, and document the basic troubleshooting steps for your team.

A small amount of platform‑level monitoring goes a long way. If the controller is unhealthy, your rollouts may hang in unexpected states or fail to respect the strategies you have carefully defined in YAML.

Common Installation Pitfalls and How to Avoid Them

Most installations of Argo Rollouts are straightforward, but a few recurring patterns can trip people up. Being aware of these issues will save you time later.

Missing or unregistered CRDs

If you run kubectl get rollouts and receive an error stating that the resource type does not exist, the underlying problem is usually that the CRDs were never created or were blocked due to insufficient permissions. Re‑apply the installation manifest with a sufficiently privileged user and then re‑check the CRDs. In locked‑down environments, coordinate with the platform team so CRD creation is part of an approved change.

Insufficient permissions for the controller

Another class of issues arises when the controller pod starts but quickly begins logging authorization errors. In these cases, the service account used by the controller may not have the roles and bindings required to watch or update certain resources. Reviewing the role and role binding definitions in the manifest, and comparing them against your organization’s RBAC policies, will usually reveal what is missing.

Resource constraints and scheduling problems

On very small clusters, the controller pod may be unscheduled due to insufficient node capacity, or it may be repeatedly killed because of tight CPU or memory limits. If you see pods stuck in Pending or CrashLoopBackOff due to resource constraints, adjust the resource requests and limits in the deployment specification, and make sure at least one node can satisfy them.

Conclusion and Next Steps

From here, the next steps are to deepen your hands‑on experience. Experiment with simple canary and blue‑green strategies in a non‑production environment, connect Argo Rollouts to your preferred metrics provider, and gradually bring more critical services under its management. As you grow more comfortable, you will find that progressive delivery becomes less about manual heroics and more about reliable, repeatable workflows built on the installation you just completed.

FAQ: Installing Argo Rollouts on Your Kubernetes Cluster

Latest Post:

• How Argo Rollouts Works: Canary & Blue-Green Strategies
• Argo Rollouts Features: Blue-Green, Canary & Traffic Control
• Argo Rollouts vs Kubernetes Deployments: Key Differences & Benefits
• Is Argo Rollouts Safe? Security & Production Readiness Explained
• Business Use Cases for Argo Rollouts: Safe Deployments, KPIs & Continuous Delivery