Upgrading Argo CD across several minor versions

Upgrading Argo CD across several minor versions starts with the upgrade notes you skipped

If your Argo CD instance is on an unsupported 2.x line, the work is a planned jump across several minor releases, and the first task is reading every upgrade notes page between your version and the target. Skipping minor versions means reading every intermediate upgrade notes page, because a change introduced in an early release can still break your installation after you move past it. This page covers planning that jump, not a generic install. The target is a decision your team makes from the current release list on the Argo CD releases page, choosing a version that the project still patches.

The project only patches the three most recent minor versions, so an unsupported line receives no security or bug fixes and the gap widens every few months. The release process states that a minor release ships four times a year. Patch releases need no special steps according to the upgrade overview, but minor releases may include changes that need a workaround, so each intermediate page can add a task to your plan. Confirm the current list of supported minor lines before you pick a target, because the set changes with each release. Record which notes pages apply to your configuration, such as RBAC policy, repository definitions and resource tracking, and assign an owner for each.

Which breaking changes hit a multi-version jump

This table lists the breaking changes from the Argo CD 2.14 to 3.0 notes that a jump across several minor versions is most likely to hit, with the impact on existing installations and the action to take before cutover. Read each row against your current RBAC, repository and SSO setup, then confirm the list against every intermediate upgrade page before you start.

Change	Impact	Action needed
Update and delete RBAC apply only to the application	Policies that granted update or delete on project-level or broader resources may stop working, so users and automation can lose access they relied on.	Audit every RBAC policy line, rewrite update and delete rules to target applications, and test with a non-admin account.
Logs access needs explicit logs, get permission	Users who could view pod logs before the upgrade may see errors or empty log views afterward.	Add the logs, get permission to each role that needs log access, then confirm with a test user.
Repositories moved from argocd-cm to Secrets (3.0)	Repository entries defined in the argocd-cm ConfigMap are no longer read, so applications may fail to sync after cutover.	Convert each repository definition to a Kubernetes Secret, then verify every application can still fetch its source.
Dex RBAC uses the federated_claims.user_id claim (3.0)	SSO role mappings that match on the older subject value may stop matching, so SSO users can lose their roles.	Review Dex RBAC subjects, update them to the federated_claims.user_id claim, and test an SSO login for each role.
Annotation-based resource tracking is the default	Resources tracked with the older label method can appear out of sync or be pruned unexpectedly after the default changes.	Check how existing applications track resources and plan the tracking method before the first sync on the new version.
Intermediate minor steps each have their own notes	Changes between your current version and the target are not covered by the 2.14 to 3.0 notes, so skipped steps can hide breaking changes.	Read the upgrade notes for every minor version in order, record each change, and build one combined checklist before testing.

Choosing the target: patch line, minor hop or major hop

If your instance already runs a supported minor version and you are moving to a newer patch within that minor, the upgrade is the lowest-risk case. The upgrading overview states that patch releases need no special steps, so the main work is confirming that your version is still on the list of supported lines and that the patch does not change anything your installation depends on.

Reading: the release notes for the specific patch on the GitHub releases page, not a full set of upgrade notes.
Backup: not required by the overview for patch releases, though a settings backup costs little and is a sound habit.
Decide before starting: who approves the change, the maintenance window, and the rollback owner.
Confirm: that your current minor is one of the three most recent minor versions that still receive patches, according to the release process.
Check the day of planning: the latest patch numbers on the GitHub releases page change often, so confirm the exact target then.

Before you schedule the change, check that the patch line you plan to move to is still receiving fixes and that your instance is not on a minor line that has already left the patch window.

What to prepare before the first cluster is touched

Each card is a artifact or decision the team must have in hand before any upgrade step runs on a cluster that matters. Together they let you move back to a known state, test the jump on realistic data and decide, in writing, whether the upgrade should proceed. Skipping one of them usually shows up later as a stalled sync or a locked-out administrator.

Backup of Argo CD settings

Before any major version, take a backup of Argo CD settings by following the disaster recovery guide. The backup should cover the resources that hold Argo CD's configuration, including ConfigMaps, Secrets and the Application and AppProject objects, and it must be stored outside the cluster being upgraded. Confirm that you can restore it into a scratch namespace, because a backup you have never restored is only an assumption. Record the Argo CD version and chart version the backup came from.

Inventory of configuration and access

Produce a written inventory of Applications, AppProjects, repository Secrets, RBAC policy, SSO settings and any custom plugins or CMP sidecars. For each item, note the owner, the source repository and whether it depends on a setting the upgrade notes change, such as repository definitions moving to Secrets or RBAC rules for update, delete and logs. Keep the list in version control so the reviewer can compare it with what the test instance reports after each step.

Non-production Argo CD instance

Stand up a non-production Argo CD instance that holds copies of representative Applications and targets at least one cluster that resembles production in its CRDs, plugins and network paths. Point it at forked or read-only copies of the Git repositories so test syncs cannot change production state. Run every intermediate upgrade on this instance in order, and keep a log of which upgrade notes were applied at each step. Ask the team who owns the test cluster and how it is refreshed between runs.

Rollback owner and go or no-go checklist

Name one person who holds the rollback decision and can stop the cutover without waiting for a committee. Write a go or no-go checklist that covers the backup restore test, the inventory review, the results from the non-production run, open sync failures and the support window for the target minor release. The owner signs the checklist before the first production cluster is touched, and the same checklist records the reason if the answer is no.

The upgrade sequence with checks and rollback points

This sequence moves an Argo CD instance across several minor versions in a controlled order, so each intermediate change is read, tested and reversible before production is touched. Each step ends with a check that confirms it is safe to continue.

Read every intermediate upgrade notes page
Start by listing each minor version between your current release and the target, then read the upgrade notes for every one of them. Skipping minor versions means the intermediate breaking changes still apply, so the notes for each step matter, not only the final target. Record each change that touches your setup, such as RBAC policy syntax, repository configuration, resource tracking, SSO settings or CRD requirements. The output is a written list of required changes per version, reviewed by the platform owner and the team that writes Argo CD RBAC rules. Start from the upgrading overview to confirm the process before reading individual pages.
Fix configuration breaks in a branch
Apply the required configuration changes to the Git repository that holds your Argo CD manifests, RBAC policy and settings, working in a branch rather than directly on the live instance. Typical changes include moving repositories into Secrets, rewriting RBAC rules for the new permission model and updating SSO subject claims. Review the diff with the people who own access control, then merge only after a second reviewer confirms that every intermediate change is covered. The check is that the branch renders cleanly and the RBAC and settings files validate in a non-production environment.
Back up Argo CD settings before the major version
Before any change that crosses a major version boundary, take a backup of Argo CD settings using the disaster recovery guide. Export the Application, AppProject, ApplicationSet and repository and cluster Secrets, along with the ConfigMaps and RBAC settings, and store the copy outside the cluster being upgraded. Confirm the backup can be read back by restoring it into a scratch namespace or a separate test cluster. The rollback point is this backup, together with the Git commit of the manifest set currently running. Record both identifiers in the change ticket.
Upgrade the non-production instance one minor at a time
On a non-production instance built from the same manifests as production, apply the release for the first intermediate minor version, then move to the next one only after the previous step passes. After each minor version, run the checks that matter for your estate: confirm the application controller and repo-server are healthy, sync a representative set of applications, and confirm applications reach Healthy and Synced states. Note any application that changes state and investigate before continuing. The rollback point at each step is the previous minor version's manifest set, reapplied from Git, plus the backup if data was altered.
Apply the full manifest set with server-side apply
For each release, apply the complete manifest set rather than only the image change, using kubectl apply --server-side --force-conflicts. The upgrading overview explains that some CRDs exceed the client-side apply size limit, and it recommends applying the whole set even when a release seems to need only an image change. Run the apply from the same Git revision that holds your configuration fixes, then confirm the CRDs and deployments report the new version. The rollback point is reapplying the prior manifest set from its Git revision, which restores the earlier controller and CRD definitions.
Verify logins, RBAC and syncs
After the final minor version on the non-production instance, test the behavior people and automation depend on. Sign in through each configured SSO path and through the local admin account if it is still enabled, then check that each role can perform only the actions its policy grants, including update, delete and log access where those rules changed. Run a sync for a set of applications across projects and confirm that deletions, rollbacks and log viewing behave as expected. The completion check is a written test record with pass or fail results for each path. Any failure stops the change and returns the instance to the previous state.
Repeat on production in a change window
Schedule the production upgrade for a defined change window agreed with the teams that depend on Argo CD. Take a fresh backup immediately beforehand, then repeat the same minor-by-minor sequence, applying the full manifest set at each version and running the same sync, health and access checks. Keep the non-production record open so each production check is compared with the earlier result. If a check fails, reapply the last known good manifest set and restore from the pre-upgrade backup if state was changed. Close the change only when production checks match the non-production record and the rollback path has been documented.

Testing and rollback on a non-production instance

The test instance has to match production in the places where an upgrade across several minor versions can break things: the Argo CD version path, the CRDs, SSO configuration and repository access. If the test instance runs a different starting version, a different set of CRDs or a simpler login setup, a passing test proves little. Build the test instance from the same manifests and the same values as production, then move it through every intermediate minor version in order, not directly to the target. Confirm that the Dex or direct OIDC settings, the admin.enabled setting and the repository Secrets match production before the first upgrade step, since the 2.14 to 3.0 change to repository definitions and the Dex RBAC claim rules will fail silently if the test copy is different.

Test the behaviors that the intermediate upgrade notes changed. Log in through SSO with a user from each group that maps to an Argo CD role, and confirm the role grants what it should. Check update, delete and logs permissions separately, because logs access now needs an explicit logs, get permission and update and delete apply only to the application itself. Sync at least one application from each repository type in use, including a Helm or Kustomize source, since the repo-server runs those tools on repository content. Confirm that each destination cluster still connects and that applications report the expected sync and health status, and compare the results with the pre-upgrade run. Record every difference, because a status change after an upgrade step is usually the first sign of a removed setting or a new default.

Rollback means restoring the Argo CD settings from the backup taken with the disaster recovery guide, then reapplying the prior manifests with the same server-side apply command used for the upgrade. Rollback success depends on that backup having been restored and tested in advance on the test instance, not on the backup existing. Ask your team to confirm that the backup contains the ConfigMaps, Secrets and Argo CD objects the target environment needs, and that the restore procedure works on a cluster that is not the one that failed. Also confirm that a CRD downgrade is handled in your plan, because the prior manifests may not reapply cleanly over the newer CRDs. The Argo CD upgrading overview is the source to check against when you write this procedure.

What makes a multi-version upgrade take longer

This table lists the factors that add effort to a jump across several Argo CD minor versions and what each one changes in the work. Read each row as a question to answer about your installation before asking for a quote. The main takeaway is that the number of intermediate upgrade notes and your RBAC, repository and plugin setup usually matter more than the target version number alone.

Driver	Why it adds effort	What to ask for in a quote
Intermediate minor versions and their notes	Skipping minor versions means reading and applying every intermediate upgrade notes page, so each release adds review and test cycles.	A list of every upgrade notes page in scope and which changes are mapped to your installation.
Custom RBAC and SSO mappings	Policy rules and Dex or OIDC group mappings may need rewriting when subject claims, logs access or update and delete semantics change between releases.	A review of current RBAC policy and SSO configuration with the changes each release requires, and a test login matrix.
Repository configuration still in argocd-cm	Repositories defined in the argocd-cm ConfigMap must move to Kubernetes Secrets before the 3.0 line, which touches credentials and every Application that uses them.	An inventory of repository definitions and credentials, and the migration steps for each one.
Number of clusters and Applications	More Applications and clusters mean more sync checks, more health states to compare before and after, and a larger rollback surface.	The count of clusters and Applications in scope and a plan for sampling or full comparison of sync and health status.
Custom plugins or Helm and Kustomize tooling in the repo-server	The repo-server runs Helm and Kustomize on repository content, so plugins and tool versions can change rendering results and need explicit testing.	A list of plugins, tool versions and sample renders, with a comparison of output before and after each step.
HA topology	HA manifests need at least three nodes for pod anti-affinity, and the controller and Redis behavior during rollout must be planned, which adds checks on replicas and node placement.	Confirmation of the current topology, the target manifests and the post-upgrade checks for replicas and anti-affinity.
Absence of a tested backup	Major version steps call for a backup of Argo CD settings first, and without a tested restore path the rollback plan is weaker and review takes longer.	A backup procedure using the disaster recovery guide, a restore test record and the owner of each step.
Availability of a non-production instance	Without a non-production instance that mirrors your SSO, repositories and clusters, most verification has to happen in production.	Whether the partner builds the test instance, what data is used, and how results are recorded before cutover.

Questions teams ask before upgrading Argo CD across several versions

How much does an Argo CD multi-version upgrade cost?

The cost depends on the written scope, and no fixed figure applies to every installation. Most of the cost is labor: reading each intermediate upgrade notes page, mapping your RBAC, SSO and repository settings to the new format, testing on a non-production instance, and running the cutover. Argo CD itself is licensed under Apache-2.0 with no paid edition from the project, so license cost is not a line item. Costs recur only if you keep a support or patching arrangement afterward. Ask for a quote that separates one-time migration work from any recurring support, lists the number of versions covered, and names the clusters, Applications and SSO setup in scope.

How long does a multi-version Argo CD upgrade take?

Duration depends on how many minor versions you cross, how many Applications and clusters you manage, and how much of your configuration uses features that changed. The number of intermediate upgrade notes you must read grows with the version gap, and each breaking change adds a test cycle. Your team's change windows and review rules also set the pace. Ask the provider for a timeline tied to the written scope, with separate phases for planning, the non-production test run, the production cutover and post-upgrade checks.

What does the upgrade need from our team?

Plan for time from people who own the Git repositories, the Argo CD RBAC policy, the SSO provider and the target clusters. Someone must approve the change and be available during cutover. Your team also needs access to the Argo CD namespace, the ability to take and restore a backup, and a non-production instance that resembles production. Ask the provider which decisions they expect you to make, such as rollback criteria and maintenance windows, and which artifacts they will hand back, such as a runbook and test results.

Can our own team run a multi-version Argo CD upgrade?

Yes, if your team can read the official upgrade notes for every intermediate version, test changes on a non-production instance, and apply the full manifest set with server-side apply. The overview recommends applying the whole manifest set, using kubectl apply --server-side --force-conflicts, even when a release seems to need only an image change. Teams that lack Kubernetes operations depth, or that run many clusters with custom RBAC, often choose a partner for planning and testing. Compare the internal effort with the written scope before deciding.

Do we need downtime to upgrade Argo CD?

Downtime depends on your installation and the version path. Argo CD manages your workloads from its controller, so a short interruption to the Argo CD UI and API is possible during the rollout, while deployed workloads keep running. The overview does not promise zero interruption for every topology. High availability installs, and installs with sharded controllers, need a separate rollout plan. Confirm the expected impact on sync operations during cutover with the provider and your application owners before the change window is set.

What happens if the upgrade fails partway through?

Recovery depends on the backup you take before starting. For major releases, the upgrade overview recommends backing up Argo CD settings with the disaster recovery guide first, so you can restore configuration if the new version does not start cleanly. Ask for a written rollback procedure that covers restoring the backup, reapplying the prior manifests, and confirming that Applications resume syncing. Test the rollback on the non-production instance before the production cutover, and agree on the criteria that trigger it.

Which upgrade notes must we read before a multi-version jump?

Read every intermediate upgrade notes page between your current version and the target, not only the final one. The overview states that skipping minor versions means reading each intermediate page. Breaking changes that often need attention include the 2.14 to 3.0 changes to RBAC for update, delete and logs, the move of repositories from argocd-cm into Kubernetes Secrets, and the Dex RBAC claim change. Confirm the current patch line too, since only the three most recent minor versions receive patch releases.

What should we request in a written quote for this upgrade?

Ask for the scope in writing before work starts: the starting and target versions, every intermediate version covered, the installation type (manifests, Helm or self-managed), the number of clusters and Applications, the SSO and repository configuration to migrate, and the non-production test plan. Also request the deliverables, including backup verification, updated runbooks, rollback steps and post-upgrade checks. Finally, ask which items are one-time and which recur, and what changes the price if the scope grows during testing.

How DeployOpen scopes, delivers and supports the upgrade

DeployOpen plans a multi-minor Argo CD upgrade as a written, fixed-scope engagement inside your own clusters. We start from the upgrade notes for every intermediate minor version, then test the full path on a non-production instance before any change reaches production.

How we scope

Inventory your current Argo CD version, every installed component and the clusters and applications it manages.
List each intermediate upgrade notes page to read, with the breaking changes that touch your RBAC, repositories and SSO setup.
Agree in writing whether the upgrade covers the production instance, the non-production test instance or both.
Confirm backup location, rollback expectations and who signs off each cutover step before work starts.

How we build

Stand up a non-production Argo CD instance that mirrors your production configuration and a representative set of applications.
Rehearse the step-by-step path, applying the full manifest set with server-side apply and force-conflicts as the upgrade notes direct.
Take a settings backup using the disaster recovery guide before the first major version step and record the restore procedure.
Verify application sync status, RBAC access, SSO login and repository connections after each intermediate version.

How we hand over

Deliver a runbook listing each intermediate version, its upgrade notes, the commands used and the observed results.
Document the production cutover checklist, rollback steps and the post-upgrade checks your operators should repeat.
Record configuration changes made to your Git repositories, RBAC policy, Secrets and SSO settings for your change records.
Walk your platform team through the runbook so they can repeat the path on the next upgrade.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after the fixed-scope upgrade is complete.
Confirm with your team which Argo CD minor line you will stay on, since only the three most recent minor versions receive patch releases.
Ask for a quote that separates the one-time upgrade work from any recurring patching, testing or on-call support.
Plan the next cadence review so each new minor release is assessed against its upgrade notes before it is adopted.

Upgrading Argo CD across several minor versions