How to plan an Argo CD 2.14 to 3.0 upgrade without disrupting deployments
A platform team running Argo CD 2.14 that must move to 3.0 should treat the move as a planning exercise, because the upgrade changes RBAC behavior, resource tracking, where repositories are stored and which SSO subjects Argo CD matches, so each of those needs a decision and a test before cutover. Changing the image tag alone will not show these effects. The project ships a minor release once every three months and gives patch releases only to the three most recent minor versions, so a 2.14 installation is already outside that window once 3.0 and later minors are current. Staying on 2.x is a risk to plan for, not a neutral choice, and the team should confirm the current support window on the release process page before setting a date.
The supported path is the one the official Upgrading 2.14 to 3.0 notes describe, and the plan should start from that document rather than from release announcements. Begin by inventorying every policy.csv rule that grants update or delete, since those now apply only to the Application itself, and every role that needs to read pod logs, which now requires an explicit logs, get permission. Next, list every repository defined in the argocd-cm ConfigMap, because 3.0 no longer reads them there and each must be recreated as a Kubernetes Secret. Record every SSO group mapping that depends on Dex claims so you can rewrite them against the federated_claims.user_id claim. Finally, check the annotation-based tracking default against any tooling that reads label-based tracking. Each item becomes a line in a written change plan with an owner and a test.
Which 3.0 changes affect your installation
This table lists the Argo CD 3.0 breaking changes from the upgrade notes, with the impact on users, automation and monitoring, and the action to take before cutover. Read each row against your current RBAC policy, repository setup, SSO configuration and dashboards, and treat any row that matches your setup as a blocking task for the cutover plan.
| Change in 3.0 | Impact on users, automation and monitoring | Action before cutover |
|---|---|---|
| RBAC update and delete apply only to the application | Policies that granted update or delete on a project or resource pattern may stop working, so users and pipelines can get denied actions they used to perform. | Export the current policy, rewrite update and delete rules to target the application itself, and test each role with a non-production account. |
| Logs access needs logs and get permission | Users who could view pod logs with existing rules may lose access, and dashboards or support tooling using service accounts may fail silently. | Add an explicit logs, get rule for each role or account that reads logs, then confirm access with a test user and the tooling that depends on it. |
| Annotation-based resource tracking is the default | Resources previously tracked by labels may appear OutOfSync or get pruned differently, which affects automation that reads tracking labels. | Decide whether to keep the old tracking method for existing apps, review sync and prune behavior in staging, and update any scripts that read the tracking metadata. |
| Repositories removed from argocd-cm | Repository definitions in the ConfigMap stop being read, so syncs can fail with missing repository errors after the upgrade. | Recreate each repository as a Kubernetes Secret with the labels Argo CD expects, remove the old entries from argocd-cm, and verify repository connections in staging. |
| Dex RBAC uses the federated_claims.user_id claim | Group or user mappings that matched the previous claim may stop matching, locking out SSO users or granting the wrong access. | Check which claim each Dex connector emits, update RBAC subjects to federated_claims.user_id, and test login for admin, read-only and team users. |
| Removed metrics and dashboards | Alerts, scrape rules and Grafana panels that reference removed metrics show no data, so outages can go unnoticed. | List every metric and dashboard in use, compare against the 3.0 upgrade notes, replace removed series in alert rules, and confirm alerts fire in staging. |
| Automation that calls the API or CLI | Scripts that depend on previous permission behavior or repository configuration may return errors or empty results. | Inventory CI jobs, bots and scripts that call Argo CD, run them against a 3.0 test instance, and fix failures before the production window. |
What to inventory and back up before touching the controller
Argo CD keeps its desired state in Kubernetes objects and in Git, so the backup that matters is the set of objects that define how Argo CD behaves. Work through these four areas before anyone changes the controller image, and record what you found so the cutover has a clear rollback point.
Application and AppProject objects
Export every Application and AppProject custom resource, with their namespaces, from the Argo CD control namespace. These objects hold sync policies, destinations and project boundaries, and they are where the 3.0 changes to tracking behavior will show up first. Store the exports outside the cluster and confirm you can re-apply them to a scratch cluster. Because Argo CD is largely stateless, these objects plus the Secrets below are what a rebuild depends on.
Secrets and the argocd-cm and argocd-rbac-cm ConfigMaps
Back up the Secrets that hold cluster and repository credentials, and the argocd-cm and argocd-rbac-cm ConfigMaps that hold settings and policy. Handle the Secrets as sensitive material with restricted access to the backup location. Note every repository entry in argocd-cm, because 3.0 no longer reads repositories from that ConfigMap and each one must be recreated as a Secret before cutover.
Current RBAC policies and repository definitions
Write down every RBAC rule and group mapping in argocd-rbac-cm, and every repository and its credentials. Mark which rules grant update or delete on applications, since 3.0 limits those permissions to the application itself, and which roles read logs, since logs access now needs an explicit logs, get permission. Ask the owners of each team role whether those grants still match their intent before you rewrite them.
Dashboards and alerts that reference removed metrics
Search your Grafana dashboards, Prometheus alert rules and recording rules for metric names tied to the removed items in the 3.0 notes. Each match is a panel or alert that will go silent after the upgrade unless you replace it. Keep a list with the owner and the replacement metric, and confirm the replacement in a test environment before you retire the original.
A non-production instance that mirrors production
Stand up a 2.14 instance in a non-production cluster with the same SSO configuration, projects, repository connections and a representative set of applications. Run the 3.0 upgrade there first, then compare sync status, RBAC decisions and notifications with production. Plan the test around the state that matters: Redis is a disposable cache and can be rebuilt, so spend your effort on the Kubernetes objects and access paths.
Why the path from 2.14 runs through the 3.0 notes first
The Argo CD 2.14 to 3.0 upgrade notes are the first document to read before choosing a target, because they describe the breaking changes that every move into the 3.x line has to absorb. Read them in full before writing any change plan. The notes cover RBAC changes for update, delete and logs, annotation-based resource tracking as the default, the move of repository definitions out of the argocd-cm ConfigMap into Kubernetes Secrets, and the change to Dex-based RBAC that uses the federated_claims.user_id claim. Each of these can break a working installation on its own, so treat the notes as a checklist for your own configuration rather than a summary to skim.
If your installation is still on an earlier 2.x minor, the 2.14 notes are not enough. Read each intervening upgrade note in order, from your current minor forward to 2.14 and then to 3.0, and record which settings each one changes. Later notes often assume the changes in earlier ones have already been applied, so skipping a step can leave you with a configuration that looks valid but behaves differently. The release process also determines how long any starting point remains safe. Argo CD ships a minor release roughly every three months and only the three most recent minor versions receive patch releases, so an older minor line stops getting fixes while you are still planning. Confirm the current supported minor versions on the Argo CD release process page and the argoproj/argo-cd releases page on GitHub before you choose a target, and check the latest patch release for the minor you plan to run.
The upgrade sequence, with checks and rollback points
This sequence moves an Argo CD installation from 2.14 to 3.0 in an order that proves each breaking change in staging before production is touched. Each step ends with a check that must pass and a rollback point that states what returning to the earlier state restores. Production cutover happens only after the staging results and the backups are in hand.
Back up state and freeze changes
Export the Argo CD Application, AppProject and ApplicationSet objects, the argocd-cm and argocd-rbac-cm ConfigMaps, and the repository and cluster Secrets from the Argo CD namespace. Store the export outside the cluster, then announce a change freeze so no one edits Argo CD configuration or manual application state during the upgrade. The check is that the export is complete and readable. Rollback point: restoring the export returns the objects Argo CD stores in Kubernetes to their 2.14 state. It does not revert Git history or changes that syncs already made to target clusters.
Convert repositories from argocd-cm to Secrets
In a staging instance still on 2.14, define each Git and Helm repository as a Kubernetes Secret, using the repository secret type described in the 3.0 upgrade notes, and remove the repository entries from argocd-cm. Confirm that every repository shows as connected and that a test application can still pull its manifests from Git. Rollback point: deleting the new Secrets and restoring argocd-cm from the step 1 export returns repository configuration to its original form. Git content and cluster state are unaffected because only Argo CD's record of repositories changes.
Rewrite RBAC policies for update, delete and logs
Review every policy in argocd-rbac-cm. The 3.0 notes say update and delete now apply only to the application itself, so rules that relied on broader reach need rewriting. Add an explicit logs, get permission to each role that needs pod logs. Test with one account per role in staging: each should sync and read logs for its own applications, and none should gain access it did not have before. Rollback point: restoring the step 1 copy of argocd-rbac-cm returns the 2.14 policy. Keep the rewritten policy in version control so it can be compared later.
Verify SSO subject claims with a test login
If Argo CD signs users in through bundled Dex, the 3.0 RBAC rules use the federated_claims.user_id claim, so user and group subjects in argocd-rbac-cm must match what the identity provider actually sends. Sign in to staging with a test account from each group, and inspect the claims that arrive to confirm the subject value. The check is that each test account receives exactly the role it should. Keep the built-in admin account enabled until every test login passes. Rollback point: reverting argocd-cm and argocd-rbac-cm from the step 1 export restores the 2.14 subject mapping. The identity provider configuration is not changed by this rollback.
Switch tracking to annotations and confirm ownership
Annotation-based resource tracking is the default in 3.0. In staging, switch to annotation tracking and compare the managed resources list for each sample application before and after the change. Look for resources that appear orphaned, resources that another application seems to claim, and resources carrying labels from other tools that Argo CD might misread. The check is that every resource maps to exactly one application. Rollback point: setting tracking back to the previous method in staging and re-syncing returns ownership markers to their 2.14 form. Record the comparison in the change record.
Upgrade the controller and API server in staging
Apply the 3.0 manifests for your installation method with the official Argo CD 2.14 to 3.0 upgrade notes open beside you. Confirm that the application controller, API server, repo server and Redis pods all reach ready state, and that controller logs show no startup errors about removed settings. The check is a healthy control plane with the earlier steps still working. Rollback point: reapplying the 2.14 manifests to staging restores the 2.14 components. Downgrade is clean only if the notes confirm that nothing 3.0 wrote is incompatible with 2.14, so treat the step 1 backup as the real rollback.
Run sync and health checks on sample applications
Choose sample applications that cover your main source types, such as Helm, Kustomize and multi-source applications, plus at least one that deploys to a remote cluster. Sync each one in staging and confirm it reaches Synced and Healthy, that cluster and repository connections show as healthy, and that the RBAC roles from step 3 behave as tested. Record the results per application. Rollback point: if a sample fails and the cause is not a quick fix, revert the staging controller using the step 6 rollback and restore the step 1 backup. Nothing has reached production yet.
Cut over production in a maintenance window
Repeat steps 1 through 7 in production during the approved change window. Start with a fresh backup taken after the freeze began, then apply the upgraded manifests and run the same checks as staging. Watch sync activity through the first sync cycles and confirm one SSO login per team and one application sync. The change owner signs off on the recorded results and lifts the freeze. Rollback point: restoring the fresh backup and reapplying the 2.14 manifests returns production to its prior state. Keep the backups and staging records until the owners confirm the upgrade is stable.
Testing in staging and rolling back safely
Functional testing proves that the 3.0 instance grants and denies the same actions your teams expect after the RBAC policy rewrite. Build a matrix of roles, projects and actions, then run each cell against a staging copy restored from production configuration. In 3.0, update and delete permissions apply only to the Application itself, and reading logs requires an explicit logs, get permission, so a role that previously could see pod logs through a broader grant may now be blocked. Test with real user accounts, not only the admin user.
- RBAC matrix for update, delete and logs: Cover each project role for update, delete and logs, and record expected and actual results.
- Representative application syncs: Sync one simple app, one Helm app, one Kustomize app and one app with hooks or sync waves, and compare resource diffs with the pre-upgrade state.
- Annotation-based tracking: Confirm that resources still show as owned by the right Application after the default tracking change.
- SSO login with the federated subject: Log in through the identity provider and confirm that Dex-based RBAC maps groups using the
federated_claims.user_idclaim, not the previous subject value. - Repository access as Secrets: Confirm that every repository defined in
argocd-cmin the old install is now present as a Kubernetes Secret and can still be fetched.
Before approving cutover, confirm that every denied action in the matrix is an intended outcome and that no team loses access it needs for day-to-day releases. The Argo CD 2.14 to 3.0 upgrade notes are the reference for expected behavior.
Operational testing checks that the platform stays observable and reconciles normally while the upgrade runs. Removed metrics and dashboards are the most common gap: alert rules and dashboards that query a removed series will silently show no data, so an outage can go unnoticed. Inventory every alert and panel your team depends on, compare it with the metrics exposed by a 3.0 instance in staging, and replace or retire each one deliberately. The same staging run should exercise high availability behavior if production uses it.
- Metric inventory: List each alert rule, dashboard panel and scrape job, then mark whether the metric still exists in the 3.0 build you deploy.
- Alert firing tests: Trigger a controlled sync failure and a degraded application in staging, and confirm that the replacement alerts fire and route correctly.
- Controller sharding: If the application controller is sharded, confirm that each shard receives its assignments and that no application is left unreconciled during a rolling restart.
- Redis and repo-server behavior: Restart Redis and the repo-server during testing, since Redis is a disposable cache and the repo-server runs rendering. Measure how long applications take to refresh.
- Replica spread: On an HA install, check that pods still satisfy the pod anti-affinity rules and that the cluster has at least three nodes for those manifests.
Treat the operational checks as passed only when the alert inventory is complete and sharding and restart tests show no lost reconciliation. Ask your platform team to confirm the exact metric names in the target release, because naming changes should be checked against the build you deploy rather than assumed from documentation.
Rollback is planned before cutover, not after a failure. Most of the change can be reversed: the Argo CD workloads, the manifests and the configuration in ConfigMaps and Secrets can be restored from backup. Some effects cannot. Once a 3.0 controller has written the new tracking annotations to managed resources, an older 2.x controller may not recognize ownership the way it did before, so reverting the binary alone is not enough. Decide in advance which state you will restore and how far back the restore goes.
- Backups before the change: Export the Application, AppProject, ApplicationSet and repository definitions, the
argocd-cm,argocd-rbac-cmand related ConfigMaps, and the Secrets for repositories and clusters, and store them outside the cluster. - Reverting manifests: If you deploy Argo CD from Git, revert the commit that bumped the version and let the 2.x manifests reapply with the same sync options you used before.
- Restoring state: Restore the backed-up objects into a clean namespace and verify that the controller reconciles them before routing production traffic back.
- Annotation point of no return: Record the time when the 3.0 controller first synced production apps. Resources touched after that point carry new tracking annotations, so a rollback must include a plan to clean or re-sync them.
- Rehearsal: Run the full rollback in staging, including the annotation cleanup step, and time it against your change window.
Before approving the change, confirm who may trigger rollback, what the decision threshold is, and whether a rollback has been rehearsed end to end. Check the upgrade notes for any other effects that cannot be reversed in your installation method.
What makes this upgrade take longer
This table lists the factors that most change the effort of moving from Argo CD 2.14 to 3.0 and the question to put to a partner before accepting a quote. Read each row as a multiplier on the test and cutover work, not as a separate task. The main takeaway is that the RBAC rewrite, repository migration and dashboard review scale with how much your installation has grown, so ask for those counts to be measured first.
| Driver | Effect on effort | Question to ask in a quote |
|---|---|---|
| Clusters and applications | More applications mean more sync and health checks to compare before and after cutover, and more RBAC subjects to re-verify. | How many clusters and Application resources are in scope, and will the test plan sample each cluster or cover all of them? |
| AppProjects and custom RBAC policies | Each policy line using update or delete on resources must be reviewed, since those rules now apply only to the application itself, and logs access needs a logs, get permission. | How many AppProjects and policy.csv rules exist, and who signs off on the rewritten rules? |
| Repositories defined in argocd-cm | Repository entries must be recreated as Kubernetes Secrets, and each credential must be rotated or re-entered with its own labels. | How many repositories are configured in argocd-cm, which use SSH or GitHub App credentials, and how will secrets be handled during the move? |
| SSO and Dex configuration | Dex-based RBAC subjects must switch to the federated_claims.user_id claim, and each identity provider connector needs a login test. | Which SSO path is in use (bundled Dex or direct OIDC), how many groups map to roles, and is the admin user to be disabled after cutover? |
| Custom dashboards and alerts using removed metrics | Dashboards, alert rules and notifications that query metrics removed in 3.0 must be found, replaced and re-tested. | How many dashboards and alert rules reference Argo CD metrics, and does the quote include an inventory of metric names? |
| Helm or Kustomize plugins and repo-server use | The repo-server runs Helm and Kustomize on repository content, so plugin behavior, tool versions and generated manifests need comparison across the upgrade. | Which config management plugins and tool versions are in use, and will rendered manifests be diffed before and after the upgrade? |
| Self-managed Argo CD instances | If Argo CD deploys its own manifests from Git, the upgrade needs ordered changes and a recovery path if the new controller fails to start. | Is this instance self-managed, and how will the upgrade be sequenced and rolled back if the controller does not start? |
| Teams that must retest | Each team owning projects or applications needs time to confirm syncs, permissions and log access, and that time recurs with each cutover wave. | How many teams must sign off, how many test cycles are included, and who coordinates their availability? |
Questions teams ask before upgrading Argo CD to 3.0
What drives the cost of an Argo CD 2.14 to 3.0 upgrade?
The cost is set mostly by how much of your Argo CD configuration has to change and how much testing you need before cutover. Two components carry the cost: the engineering time to rewrite RBAC policies, move repository definitions into Secrets, and update SSO configuration, and the test effort to prove that applications still sync, prune and roll back as before. Recurring costs are small by comparison, since a retainer for upgrades and support is optional. Ask any provider for a quote that lists each change area from the 3.0 upgrade notes as its own line, with the test environment and the sign-off step named separately. A quote built from the written scope will also show what your team pays for, such as access reviews or change window coordination.
How long does the upgrade take, and what sets the duration?
Duration depends on the number of Argo CD instances, how many AppProjects and RBAC rules exist, how many repositories are defined in argocd-cm, and how many applications rely on annotation-based tracking that will change. The largest variable is the test cycle: a single small instance on a non-production cluster moves much faster than a shared instance serving many teams with different sync windows. Confirm with your provider how the timeline is split between discovery, the change plan, a rehearsal on a non-production instance and the production cutover. No duration figure is given here because none has been researched for this page, so treat any number you hear as something to verify against your own inventory.
What does our internal team need to provide for the upgrade?
Your team needs to provide access, decisions and people who can confirm behavior. Access means read rights to the current Argo CD configuration, the argocd-cm and argocd-rbac-cm ConfigMaps, and the Git repositories behind the applications, plus admin rights on the target clusters during the rehearsal. Decisions include the change windows, rollback criteria and who approves the cutover. People means named test owners for each application group who can confirm that a sync, a log view and a delete action behave as expected after the move. You should also name an approver who signs off the RBAC changes, because the 3.0 notes change which actions users need.
Can our team do the 2.14 to 3.0 upgrade without outside help?
Yes, a team with Kubernetes and Argo CD administration experience can plan and carry out the upgrade internally, provided it reads the 2.14 to 3.0 upgrade notes in full and tests before cutover. The areas that most often need a second pair of eyes are the RBAC rewrite, where update and delete now apply only to the application itself and logs access needs an explicit logs, get permission, and the Dex change that moves RBAC subjects to the federated_claims.user_id claim. Repository definitions moving to Kubernetes Secrets also touches credentials, so confirm that the Secrets are handled under your existing secret controls. Many teams choose a hybrid model: they do the change internally and bring in outside help only for review and testing.
Is a fixed-scope engagement possible for this upgrade?
Yes. Most DeployOpen engagements are fixed-scope, meaning the scope, deliverables and timelines are agreed in writing before work starts. For this upgrade, a written scope would normally name the Argo CD instances in scope, the configuration areas covered (RBAC, SSO, repositories, tracking method and metrics or dashboards), the test environment, the cutover support and the handover documentation. Changes that surface during discovery, such as an unexpected Dex setting or a large number of ApplicationSets, should be recorded as scope changes with their own written terms. Ask for the written scope before you compare offers, so you are comparing the same work.
Which Argo CD 3.0 changes break existing RBAC rules?
The most common breakage comes from the RBAC rewrite. Under the 2.14 to 3.0 upgrade notes, update and delete permissions apply only to the application itself, so policies that relied on broader effects on child resources need to be reviewed. Log viewing also requires an explicit logs, get permission. Review every policy in argocd-rbac-cm against the upgrade notes, and test each team's role with a non-admin account on a rehearsal instance. Keep the rehearsal results with the change record so the approver can see what was tested.
What should we check after the upgrade before we call it complete?
Check that every application syncs and reports the health you expect, that SSO logins map to the right roles through the updated Dex subject, and that repositories defined as Secrets are reachable. Confirm that annotation-based tracking has not left resources marked OutOfSync or orphaned, and that log access and delete actions work only for the users you intended. Metrics and dashboards that the upgrade notes list as removed also need replacements before you retire old panels. Record each check against a named owner and keep the results with your change record.
What this plan does not cover
This page covers the move from Argo CD 2.14 to 3.0 and nothing beyond it. Later minor upgrades, such as 3.0 to 3.1, change different behavior, including the OIDC authorization code flow and its callback redirect URI, and each has its own upgrade notes. Plan them as separate changes with their own testing, and do not assume that a clean 3.0 cutover means the next minor release is safe. Once the cluster is on 3.0, check the current patch and minor support status on the Argo CD release process and cadence page before you schedule the next step.
The plan also does not verify your environment. Confirm the Dex version bundled with the release you install, rather than assuming it matches an older deployment, and check how your identity provider is wired, whether through bundled Dex connectors or a direct OIDC integration. Confirm the claim your Dex RBAC rules depend on, federated_claims.user_id, is actually present in the tokens your provider issues. Confirm the Kubernetes versions on every cluster Argo CD manages, and the versions of Helm and Kustomize your repositories use, since the repo-server runs both. These details differ by organization, and a plan written without checking them will fail at the first login or sync.
Finally, this page does not replace the release notes for the exact patch you install or your own change process. Treat the upgrade notes as the authoritative list of breaking changes, and record which of them your instance hits during the non-production run. Ask your Argo CD owner or implementation partner to confirm the target version and the rollback path in writing before the production window is booked.
How DeployOpen scopes and delivers the Argo CD 2.14 to 3.0 upgrade
DeployOpen is a Chainscore Labs company that plans, implements, hardens, documents and supports self-hosted open-source platforms in infrastructure you control. For the Argo CD 2.14 to 3.0 upgrade, we start from your current RBAC, repository and tracking configuration, then rehearse the move on a non-production instance before any cutover is scheduled.
How we scope
- We inventory your current RBAC policy, SSO setup, repository definitions and resource tracking method before estimating any work.
- The written scope lists each breaking change that applies to your instance, including update, delete and logs permissions.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
How we build
- We rewrite the RBAC policy so update and delete rules target applications and logs access uses an explicit get permission.
- We move repository definitions out of argocd-cm into Kubernetes Secrets and check Dex RBAC against the federated_claims.user_id claim.
- We test the upgrade on a non-production instance, covering sync, rollback, SSO login and any dashboards or metrics you rely on.
How we hand over
- You receive the rewritten RBAC, repository Secret manifests and a record of each change made to your instance.
- We document the cutover runbook, the rollback steps and the list of removed metrics and dashboards your teams must replace.
- Walkthroughs cover what changed, so your platform team can run future Argo CD upgrades without us.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- A retainer can cover reviewing the upgrade notes for later minor releases that your instance will need to take.
- Confirm with us during scoping which post-cutover checks and response arrangements you want written into the retainer.
