How to Upgrade Argo Rollouts Without Downtime

Table of Contents

Introduction

Upgrading deployment tools in production environments can be risky, especially when availability and stability are critical. Fortunately, Argo Rollouts is designed to support seamless upgrades with minimal disruption. When managed correctly, you can upgrade Argo Rollouts without downtime, ensuring your applications continue running smoothly while benefiting from new features, performance improvements, and security updates.

In this guide, you’ll learn how to safely upgrade Argo Rollouts in your Kubernetes cluster using best practices for zero-downtime operations. We’ll walk through preparation steps, upgrade strategies, and validation checks to help you maintain reliability throughout the process.

Why Upgrading the Controller Safely Matters

Argo Rollouts often sits at the heart of your progressive delivery strategy. When your rollout controller misbehaves, the impact ripples across every application that depends on canary or blue‑green deployments. At the same time, new releases of Argo Rollouts bring important bug fixes, security patches, and new features you likely want.

The challenge is obvious: how do you upgrade the Argo Rollouts controller and its Custom Resource Definitions (CRDs) without disrupting existing Rollout objects or causing downtime for in‑flight deployments? This guide walks through safe patterns, practical commands, and the mental model you should keep in mind before, during, and after an upgrade.

Understanding What Changes During an Upgrade

An Argo Rollouts upgrade typically involves two main components:

CRDs that define the schema for resources such as Rollout, AnalysisRun, and related types.
The controller deployment that runs the control loop responsible for reconciling those resources.

In many releases, both of these evolve together. New fields might be added to the schema, behavior may change in subtle ways, and default settings can shift. A safe upgrade strategy always accounts for both CRDs and the controller, so your cluster never ends up with an incompatible mix.

Pre‑Upgrade Checklist

Before touching any manifests, spend time preparing. A short pre‑flight checklist can save hours of troubleshooting.

Inventory your environments

List the clusters and environments where Argo Rollouts runs today: development, staging, production, and any special test clusters. For each, note the current Argo Rollouts version and how it was installed (for example, Helm chart version, manifest URL, or GitOps path in Argo CD).

Review the release notes

Head to the Argo Rollouts release notes for the version you plan to install. Pay particular attention to breaking changes, CRD migration notes, and any deprecations that might affect your current Rollout specs. If a release introduces new default behaviors, plan how you will validate them.

Confirm backups and observability

While upgrades should be non‑disruptive, it is wise to ensure you have adequate visibility and rollback options. Confirm that:

You can see controller logs easily, either through kubectl logs or your logging stack.
Metrics or alerts exist for rollout health so regressions are visible.
Your manifests are stored in Git, so you can quickly revert to a previous configuration if needed.

Upgrading CRDs Safely

CRDs live at the cluster level and affect all namespaces. Because they define the shape of your Rollout and Analysis resources, changes here must be handled with care. Fortunately, most Argo Rollouts upgrades ship with safe, additive CRD changes.

If you installed Argo Rollouts via a published manifest, upgrading CRDs is often as simple as re‑applying the latest version of that manifest:

kubectl apply -f https://github.com/argoproj/argo-rollouts/releases/<version>/install.yaml

This command updates CRDs in place. Kubernetes preserves existing objects whenever possible, and new fields default in according to the schema. In environments where GitOps manages your manifests, you would instead update the manifest reference in Git and let the GitOps controller apply the change.

The key rule is to avoid deleting CRDs during an upgrade. Deletion can cascade into removing existing Rollout objects, which is rarely what you want.

Upgrading the Controller Deployment

Once CRDs are aligned with the target version, turn your attention to the controller deployment itself. The exact commands depend on how you installed Argo Rollouts.

Helm‑based upgrades

If you rely on Helm, the upgrade typically looks like:

helm repo update

helm upgrade argo-rollouts argo/argo-rollouts \

  --namespace argo-rollouts \

  --version <chart-version>

Helm will roll the controller deployment in place, respecting your configured strategy and resource settings. Because the CRDs are already updated, the new controller can immediately understand all existing objects.

Manifest‑based upgrades

For teams using raw manifests, upgrading the controller is usually accomplished by re‑applying an updated deployment spec. That might come from a new install.yaml or from a more granular manifest that only tweaks the image field in the Deployment.

A minimal example would be:

kubectl apply -n argo-rollouts -f controller-deployment.yaml

Kubernetes will perform a rolling update of the controller pods. If you are upgrading across several versions at once, consider doing it in stages rather than jumping directly from a very old version to the latest.

Ensuring Ongoing Rollouts Are Not Disrupted

A common concern is what happens to in‑flight rollouts while the controller restarts. The good news is that rollouts are represented as normal Kubernetes resources; their desired state persists in etcd even if the controller briefly goes down.

During a controller restart, rollouts may pause progression momentarily, but traffic routing and pod health are still managed by Kubernetes and your ingress or service mesh. Once the new controller pod is running and healthy, it resumes reconciliation where the previous one left off.

To further reduce perceived risk, you can schedule upgrades during periods of lower deployment activity or temporarily pause initiating new rollouts until the upgrade completes.

Post‑Upgrade Verification Steps

After the upgrade, spend a few minutes verifying that everything behaves as expected.

First, confirm that the controller pod is running the new version. With Helm, helm status often exposes the image tag; with plain manifests, you can inspect the Deployment:

kubectl get deploy argo-rollouts -n argo-rollouts -o wide

Next, check that CRDs show the expected versions and that existing Rollout objects are still present:

kubectl get crd | grep rollouts.argoproj.io

kubectl get rollouts --all-namespaces

Finally, run a small, controlled deployment in a non‑production environment using your usual progressive strategy. Watch it with kubectl argo rollouts or the dashboard to confirm that pausing, promoting, and rollback behaviors still match expectations.

Handling Problems and Rolling Back

Even with preparation, upgrades can occasionally surface unexpected issues: a new validation rule might reject certain manifests, or a behavior change could conflict with existing assumptions. When this happens, having a rollback plan keeps you calm.

In Helm environments, you can quickly revert to the previous chart version:

helm rollback argo-rollouts <previous-revision> -n argo-rollouts

With manifest‑based installs, rolling back might mean re‑applying the prior deployment spec or image tag. Because CRDs tend to evolve in a mostly forward‑compatible way, rolling the controller back by one or two versions is usually safe in the short term while you adjust manifests.

The most important thing is to treat rollback as a conscious, documented step rather than an improvisation. Capture the reason for the rollback, the scope of impact, and any follow‑up tasks so you can address root causes before attempting the upgrade again.

Making Upgrades a Routine Practice

Over time, upgrading Argo Rollouts should feel like a routine part of maintaining your Kubernetes platform, not a high‑risk event. By understanding which components change, preparing carefully, and validating after each upgrade, you can enjoy new features and fixes without introducing downtime.

Document your upgrade procedure, including commands and verification steps, in your internal runbooks. Run through that procedure in lower environments before touching production. With that discipline in place, Argo Rollouts upgrades become just another well‑understood, low‑drama operation in your cluster’s lifecycle.

Conclusion: Upgrades as a Non-Event

Look, we’ve all been there, hovering over the Enter key, praying that a controller update doesn’t turn into a 2:00 AM post-mortem. But here’s the reality for 2026: Argo Rollouts is built to be resilient. Because it follows the Kubernetes controller pattern, the “brains” of your deployments can blink out for a few seconds during an upgrade without your applications losing a single packet of traffic.

The secret to a “boring” upgrade isn’t luck; it’s sequencing. By treating the CRDs and the Controller as two separate but related steps, you ensure the cluster always knows how to “read” your data before the new “engine” starts running. When you make upgrades a monthly habit rather than an annual emergency, the risk drops to near zero. You aren’t just updating software; you’re refining your safety net.

FAQ: Upgrading Argo Rollouts Without Downtime

1. Will my active Canary rollout fail if I upgrade the controller mid-flight?

No. Your pods and traffic routing are handled by the Kubernetes ReplicaSets and your Service Mesh/Ingress. The Argo Rollouts controller is only responsible for the logic of the next step. If the controller is restarting, the rollout simply “pauses” in its current state for a few seconds. Once the new controller pod is live, it picks up exactly where the old one left off.

2. Should I upgrade CRDs before or after the Controller?

Always upgrade CRDs first (or simultaneously). The Reason: If you upgrade the controller to a version that expects a new field in the Rollout spec, but the CRD hasn’t been updated to allow that field, the controller might crash or throw errors.
In 2026: Most Helm charts and manifests handle this for you, but if you are doing it manually, always ensure the “schema” (CRD) is ready for the “logic” (Controller).

3. How do I know if an upgrade requires a “Breaking Change” fix?

Check the Official Argo Rollouts Release Notes. In 2026, the project uses Semantic Versioning.
Patch (1.7.x to 1.7.y): Safe, bug fixes only.
Minor (1.7.x to 1.8.0): New features, usually safe but check notes.
Major (1.x to 2.x): Potential breaking changes; test thoroughly in staging!

4. Can I skip versions (e.g., v1.2 to v1.7) in one jump?

It is not recommended. Jumping across multiple minor versions increases the risk that a deprecated field was removed in the middle. The safest path is to upgrade one minor version at a time (e.g., 1.2 $\rightarrow$ 1.3 $\rightarrow$ 1.4) and run a quick smoke test between each upgrade.

5. What is the fastest way to roll back if the new version is buggy?

If you used Helm, it’s a single command:
$$helm\ rollback\ argo-rollouts\ -n\ argo-rollouts$$
If you used kubectl, you should re-apply the previous version’s install.yaml. Because Argo Rollouts is declarative, the controller will immediately “re-adopt” the existing resources and stabilize.

Latest Post: