Why the Argo CD 3.3 to 3.4 upgrade needs a written plan
If you run Argo CD 3.3 and must decide when and how to move to 3.4, plan the move as a single minor step with a written scope, a rollback path and a named owner. The supported path is one minor hop: 3.3 to 3.4. Argo CD only ships patch releases for the three most recent minor versions, so 3.3 keeps receiving fixes only while it stays in that window. Once it falls out, you carry known defects on your own schedule. Because the project publishes a new minor release four times a year, once every three months, this is not a one-time project. Each cycle brings another upgrade decision, another set of upgrade notes to read and another round of testing against your ApplicationSets, RBAC and SSO settings.
At the time the supplied facts were gathered, the latest published patch lines were v3.5.5, v3.4.11 and v3.3.16, with v3.6.0 in release candidate. Patch versions move faster than this page can track, so confirm the current patch level for each line on the Argo CD releases page before you choose a target. Pick the newest patch of 3.4 that your change window allows, and record that choice in the plan so reviewers can see which build was tested.
Write the plan before you touch the cluster. It should list the breaking changes in the 3.3 to 3.4 upgrade notes that apply to your installation, the settings you must change first, and the owners who will check each one. It should also name the checks that prove the upgrade worked, such as sync status of representative applications, login through your SSO provider and project permissions for a sample team. A plan that names these items up front turns the upgrade into a reviewable change rather than an open-ended maintenance task.
What changes between 3.3 and 3.4 and what each change requires
This table lists the five changes in the Argo CD 3.3 to 3.4 upgrade notes, what each one affects in a running installation, and the action to take before or during the move. Read each row against your ApplicationSets, Dex setup and identity provider configuration, then treat the table as a checklist for the pre-upgrade review.
| Change | Impact | Action needed |
|---|---|---|
| Full cluster version format (vMajor.Minor.Patch) | Cluster version values are reported in the full vMajor.Minor.Patch form, so ApplicationSets that read the old auto-label key may stop matching the labels they expect. | Replace argocd.argoproj.io/auto-label-cluster-info with argocd.argoproj.io/kubernetes-version in every ApplicationSet, then test generator output on a non-production instance. |
| Missing health shown only when all resources are missing | Applications show Missing health only when every resource is absent. Partially missing applications may now show a different health status, which can change alerts and dashboards. | Review health-based alerts, sync gates and dashboards, and confirm which applications were relying on the earlier Missing status. |
| Dex 2.45.0 with ContinueOnConnectorFailure on by default | Dex 2.45.0 ships with ContinueOnConnectorFailure enabled, so Dex keeps running when one connector fails. Failures in one connector may be less visible than before. | Confirm which connectors you use, decide whether continuing past a failed connector is acceptable, and monitor Dex logs after the upgrade. |
| go-oidc v3.17.0 verifies signatures before parsing claims | Tokens are checked for valid signatures before claims are read. Signing keys removed from JWKS soon after rotation can cause unexpected logouts for users with tokens still in use. | Keep rotated signing keys in JWKS for at least the token lifetime, and confirm the rotation schedule with your identity provider before upgrading. |
| gRPC DNS TXT configuration off by default | The gRPC DNS TXT setting is off by default in 3.4. Installations that depended on it may see changed name resolution behavior after the move. | Confirm the exact setting name and its default in the Argo CD 3.3 to 3.4 upgrade notes, and set it explicitly in your configuration if you rely on it. |
How the health and cluster version changes affect your applications
The two changes in this upgrade that matter most for day-to-day operations are the health reporting for partially missing resources and the cluster version label that ApplicationSets read. In Argo CD 3.4, an application shows Missing health only when all of its resources are missing. Before, a partially missing application could report Missing, so any dashboard, alert rule or runbook that treats Missing as a signal of incomplete deployment may now see fewer alerts or a different status for the same application. Before the upgrade, list every alert, Grafana panel and report that filters on the health status, and decide whether an application with some missing resources should still raise a warning. Then compare the health values returned for a sample of applications on a non-production instance.
The cluster version label is the second change, and it fails quietly. Argo CD 3.4 reports cluster versions as vMajor.Minor.Patch, so any ApplicationSet that uses the argocd.argoproj.io/auto-label-cluster-info label to template on the Kubernetes version must switch to argocd.argoproj.io/kubernetes-version. An ApplicationSet that still references the old label may generate applications whose version-based values do not match what you expect, and the sync may succeed without an error that points to the cause. Search every ApplicationSet template and generator in Git for the old label, update them in the same change set as the upgrade, and confirm on a test cluster that the generated Applications carry the values you intend. The Argo CD 3.3 to 3.4 upgrade notes are the reference for the exact field behavior.
Plan the audit as a pre-upgrade task with an owner and a sign-off, not as something to check after the cutover. Record which ApplicationSets template on cluster version, which alerts and dashboards depend on health status, and which teams receive those alerts. Confirm the expected health output for representative applications in staging, and agree with the on-call team whether the new behavior changes any escalation path. Where a rollback is needed, a Git revert of the label change and the Argo CD manifests should restore the earlier behavior, so keep those changes in one reviewable commit. Whether your own alert rules and templates need changes depends on how they were written, so treat this audit as your team's responsibility and confirm it against your environment.
How to sequence the 3.3 to 3.4 upgrade with checks and rollback points
This sequence moves an Argo CD 3.3 installation to 3.4 in an order where each stage ends with a check you can verify and a rollback point you can return to. Production changes only happen after the same steps have passed on a non-production instance.
Read the 3.3 to 3.4 upgrade notes
The platform or Argo CD owner reads the official 3.3 to 3.4 upgrade notes end to end and lists every change that touches your installation. Two items matter most for this release: cluster version reporting moves to the vMajor.Minor.Patch format, and Missing health now appears only when all resources are missing. The notes also cover Dex 2.45.0 defaults and stricter OIDC token verification. Done means each note has an owner and a yes or no answer about whether it affects you.
Inventory ApplicationSets and SSO configuration
Engineers export every ApplicationSet and search for the argocd.argoproj.io/auto-label-cluster-info annotation, since those must switch to argocd.argoproj.io/kubernetes-version. They also record the current Dex or direct OIDC settings, the connector list, the group-to-role mappings and the signing key rotation schedule for the identity provider. Done means you have a written list of affected ApplicationSets and a copy of the SSO configuration that you can compare after the upgrade.
Back up Argo CD and the objects it manages
The platform team backs up the Argo CD namespace, including Application, AppProject, ApplicationSet and repository Secrets, along with the ConfigMaps and RBAC settings, and records the current manifests or Helm values used to install it. Where Argo CD manages workloads, a backup of those Kubernetes objects or the source manifests in Git is also taken. Done means a restore has been tested in a scratch namespace or cluster, not just that files were written. This backup is your primary rollback point.
Upgrade a non-production instance first
Engineers apply the 3.4 manifests or chart values to a non-production Argo CD that mirrors production's SSO, projects and cluster registrations, and they fix the ApplicationSet annotation change before any production work. The team records the exact version, the applied manifests and any manual steps. Done means the non-production instance reports the 3.4 version and the controller and repo-server pods are running. If it does not, the earlier backup and previous manifests let you return the test instance to 3.3 before you change production.
Run sync and sign-in tests
On the non-production instance, the team runs a representative set of syncs, including a manual sync, an automated sync and an ApplicationSet-generated application. They confirm that cluster version labels now appear in the new format and that health reports Missing only where every resource is absent. They then test sign-in through each SSO path, including group mapping to roles and at least one sign-out and sign-in cycle. Done means every test has a recorded result, and any failure is fixed or documented as a blocker before production.
Upgrade production during an agreed window
The platform owner schedules the production change with the teams that depend on Argo CD, confirms that the backup from the earlier step is current and reapplies the tested manifests or chart values. Engineers watch the controller, API server and repo-server rollouts and keep the previous manifests ready to reapply. Done means all Argo CD components report ready and no unplanned sync operations are in progress. If a component fails to start, the team stops and moves to rollback before further changes.
Verify health, sync status and sign-in
After the production rollout, the team checks that every Application reports the expected sync and health status, compares the results with the pre-upgrade inventory and confirms that SSO sign-in works for an administrator and a standard user. They also confirm that signing keys in the identity provider's JWKS remain available beyond the token lifetime, so users are not logged out unexpectedly. Done means the post-upgrade checklist is signed off by the platform owner.
Keep the rollback path until checks pass
The backup, the previous manifests or chart values and the restore procedure stay available until the post-upgrade checks have passed and the owners have accepted the result. Only then does the team remove the temporary rollback resources and close the change record. Done means the change record shows the version before and after, the checks performed and the date the rollback path was retired. Ask the vendor or your support provider which 3.3 patch line you can fall back to if needed, and confirm it against the current release notes.
What to prepare before touching the production instance
Argo CD 3.4 changes how cluster versions are labeled, how Missing health is reported, and how SSO tokens are verified, so each of these needs a known starting point before you change anything. The six items below give you a backup to restore from, an inventory of what the release will affect, a tested environment to prove the change, and named people to decide and communicate.
Back up configuration and Application objects
Export the argocd-cm and argocd-rbac-cm ConfigMaps, the Secrets that hold repository and cluster credentials, and every Application and AppProject object across the namespaces Argo CD manages. Store the export outside the cluster you are upgrading. Confirm that a restore has been rehearsed on a non-production instance, because a backup you have never restored is only a hypothesis. Record the current Argo CD version and the exact manifest source used for the install so you can reapply the same baseline.
Inventory ApplicationSets using cluster labels
Search every ApplicationSet for the argocd.argoproj.io/auto-label-cluster-info annotation. In Argo CD 3.4, cluster versions are reported as vMajor.Minor.Patch, so templates that read the old label format must switch to argocd.argoproj.io/kubernetes-version. List each ApplicationSet, its owning team, and the template fields that reference the version so that a test sync on staging can confirm the generated Applications still match what is running today.
Map SSO connectors and signing key rotation
List every SSO path in use, whether that is the bundled Dex with its connectors or a direct OIDC provider, and record the callback URLs and group-to-role mappings each one depends on. Ask the identity team when signing keys last rotated and how long old keys remain published in JWKS. Argo CD 3.4 verifies signatures before it parses claims, so keys that were retired while tokens were still valid can cause unexpected logouts. Keep rotated keys published for at least the token lifetime.
Run the upgrade on a staging instance
Build a staging Argo CD that mirrors production in version, SSO configuration, RBAC policy, repository credentials, and the set of clusters it manages. Include at least one ApplicationSet and one application that shows Missing health so you can observe the new reporting. Run the Argo CD 3.3 to 3.4 steps there first, then exercise a login through each identity path, a sync, and a rollback. Keep staging on the same release as production until the upgrade is signed off.
Assign a change ticket and rollback owner
Open a change record that names the target version, the maintenance window, the backup location, and the rollback trigger. Assign one named owner who can decide to roll back and who has the access to restore the backup and reapply the previous manifests without waiting for approvals. Agree in advance on which symptoms count as failure, such as failed logins, applications stuck in Progressing, or ApplicationSets generating unexpected output, so the decision is not made under pressure during the window.
Plan communication for login changes
Identify the user groups that sign in through SSO and the automation that uses Argo CD tokens, such as CI pipelines. Tell them when sessions may end, what to do if their login fails, and who to contact. Give the platform team a short script for the service desk and a point of contact for pipeline owners whose tokens may need to be reissued. Confirm the timing with the identity team, since the JWKS and signing key changes can affect sign-in outside the Argo CD window.
Questions teams ask before upgrading Argo CD from 3.3 to 3.4
Can our own team do the Argo CD 3.3 to 3.4 upgrade without a partner?
Yes, if your team already runs Argo CD in production and has someone who can read the upgrade notes against your own configuration. The changes in this release are specific: cluster version format in ApplicationSets, the Missing health rule, Dex 2.45.0 defaults, gRPC DNS TXT configuration and OIDC token verification. Your team needs to find every place these touch your installation, test each one, and roll back cleanly if a check fails. Teams without an Argo CD owner, or with many ApplicationSets and SSO connectors, often find the review and test work takes more time than the upgrade itself. A partner can take that review on under a fixed scope, but the decision depends on your skills and calendar.
What drives the cost and effort of an Argo CD 3.4 upgrade?
The main driver is how much of your Argo CD configuration touches the changed behavior. Cost rises with the number of ApplicationSets that use cluster info labels, the number of SSO connectors and OIDC clients, whether Dex is in use, whether gRPC DNS TXT configuration is set, and how many clusters and environments Argo CD manages. Cost also depends on whether you run HA manifests, whether you need a staging copy to test against, and how much evidence your change process requires. One-time costs are the review, test and cutover work. Recurring costs are the patch releases you must apply as versions age. When requesting a quote, ask for the list of items reviewed, the test environments included and who performs each rollback step.
How long does an Argo CD 3.3 to 3.4 upgrade take?
Duration depends on the same factors as effort: the size of your ApplicationSet estate, the number of identity connectors, the number of clusters, and how many non-production environments you must move through first. Teams with one instance, a few clusters and standard OIDC usually finish faster than teams with many tenants and change approval steps. Calendar time also depends on your change windows and on how long your owners need to sign off test results. Ask any provider for a timeline that names the phases, such as inventory, staging test, production window and post-upgrade checks, and for the assumptions behind each phase. Any duration you are given should be checked against your own change calendar.
What access, owners and test windows does the upgrade need from us?
The work needs four things from your side. First, read access to the Argo CD configuration in Git, including ApplicationSets, the argocd-cm and argocd-rbac-cm settings, and any Dex or OIDC settings. Second, administrative access to the Argo CD namespace and the clusters it manages, so changes can be applied and verified. Third, named owners for identity, platform and application teams who can confirm login behavior and sync results. Fourth, a non-production instance and a window in which production sync can be paused or watched. Confirm with your change board whether a rollback plan and a backup of the Argo CD resources must be filed before the window opens.
Should we upgrade to Argo CD 3.4 now or wait for a later patch?
Argo CD's release process ships a minor release four times a year and supports only the three most recent minor versions with patch releases. Because of that, a version that is no longer among the three most recent will stop receiving fixes, so waiting has a cost of its own. Check the current patch versions on the release page before deciding, and confirm whether your team is already on a supported line. If you run 3.3 today, plan the move to 3.4 on your own schedule, and make sure the path to the next minor version is also planned. Waiting is reasonable only if you have a dated plan that keeps you on a supported release.
How do we avoid unexpected logouts after upgrading to Argo CD 3.4?
The release notes say Argo CD 3.4 ships go-oidc v3.17.0, which verifies signatures before it parses claims. If your identity provider rotates signing keys, tokens signed with an older key can fail verification once that key leaves the JWKS endpoint. Keep rotated signing keys published in JWKS for at least as long as the longest token lifetime, so users do not get logged out. Before the upgrade, record your identity provider's key rotation schedule and token lifetimes, and confirm both with the identity owner. After the upgrade, test a login from each SSO path, including Dex connectors if you use them, and watch for failed token errors in the Argo CD server logs.
What does a partner's fixed-scope quote for this upgrade cover?
A fixed-scope quote follows from a written scope agreed before work starts. Ask that it name the Argo CD instances covered, the clusters and environments in scope, the review of the 3.3 to 3.4 changes against your configuration, the staging test, the production cutover, the post-upgrade checks and the rollback steps. It should also state what is excluded, such as application code changes, identity provider changes or work on other upgrade paths. Ask who is responsible for each deliverable, what documentation you receive at the end, and how any change to scope is handled in writing. DeployOpen does not publish a price list, so a quote is produced from that written scope.
Which Argo CD 3.4 changes are most likely to break our ApplicationSets?
The first change to check is the cluster version format. Argo CD 3.4 reports cluster versions as vMajor.Minor.Patch, so ApplicationSets that use argocd.argoproj.io/auto-label-cluster-info must switch to argocd.argoproj.io/kubernetes-version. Search your Git repositories for the old annotation and every generator or template that reads it, then update them in a branch and test the generated Applications in staging. The second change is that Missing health now appears only when all resources are missing, so check any health logic or alerts that depend on the old wording. Confirm each item against the official 3.3 to 3.4 upgrade notes.
What makes this upgrade take longer or shorter
This table compares the factors that expand or shrink the 3.3 to 3.4 move and what to check for each. Read it against your own estate: the more rows that describe your installation, the more of the upgrade notes you need to work through before a change window. The main takeaway is that the cluster label rewrite, Dex and OIDC token handling, and the availability of a staging instance usually decide the effort more than the version jump itself.
| Driver | Effect on effort | What to check |
|---|---|---|
| ApplicationSets using cluster version labels | Each ApplicationSet that reads the auto-label-cluster-info annotation needs its label source switched to kubernetes-version before or during the upgrade | Search all ApplicationSet manifests for argocd.argoproj.io/auto-label-cluster-info and list every generator that depends on the old format |
| Number of SSO connectors and clients | More connectors and OIDC clients mean more login paths to test after Dex 2.45.0 becomes the default | Inventory each connector and client, then log in once per path on the staging instance and record group mappings |
| Dex versus direct OIDC | Dex installs carry the new connector failure default and the token verification change, so they need the most login testing; direct OIDC setups still need signing key checks | Confirm which mode is in use in argocd-cm, and check whether signing keys rotate faster than the token lifetime |
| Custom health checks and alerts keyed on health status | Because Missing health appears only when all resources are missing, dashboards, alerts and automation that read health values may change meaning | Review health-based alerts, sync scripts and custom Lua health checks, and compare their output on staging before cutover |
| Number of clusters and namespaces managed | A larger estate means more applications to verify after the controller restarts and more time for reconciliation to settle | Count managed clusters and applications, and decide which sample applications represent each team's workload |
| HA topology | A three-node HA install with sharded controllers allows a rolling change, while a single-replica install means a short reconciliation pause | Check replica counts, pod anti-affinity placement and whether Redis runs in HA mode, following the high availability documentation |
| Quality of existing backups | Restores of Argo CD state are straightforward only when a recent backup exists and has been tested, so weak backups add a preparation step | Confirm that a recent export of Argo CD resources exists and that someone has restored it into a test cluster |
| Availability of a staging instance | A staging instance that mirrors production settings lets the team find SSO, label and health differences before users see them, and its absence moves that work into the change window | Ask whether staging uses the same Dex or OIDC mode, the same ApplicationSets and comparable cluster registrations |
How to test 3.4 and roll back safely
Run the 3.4 tests in a staging instance that mirrors production's SSO connector, RBAC policy and ApplicationSet inventory before any production change, because the three behavior changes in this release are the ones that break quietly. Start with ApplicationSet generation: any ApplicationSet that reads argocd.argoproj.io/auto-label-cluster-info must now read argocd.argoproj.io/kubernetes-version, so confirm the generated Applications carry the new label value and that no template selects on the old one. Next, deploy a test Application with some resources deliberately missing and confirm it reports Missing health only when every resource is absent, since partially present workloads should show their true state. Check these results against the Argo CD 3.3 to 3.4 upgrade notes rather than relying on memory of earlier behavior.
Test each login path separately: the bundled Dex connector flow, a direct OIDC provider, and the local admin account if it is still enabled. For Dex, simulate one connector being unavailable and record whether login succeeds through the remaining connectors, since ContinueOnConnectorFailure is on by default in this release and changes what your team sees during an outage. For token lifetime, rotate the signing key in the staging provider, keep the old key in JWKS for longer than the token lifetime, and confirm sessions stay valid and that RBAC groups still map to the expected roles. Then run an RBAC matrix for each team and automation account, covering sync, logs and deletion, because the 3.0 rules that limit update and delete to the Application itself and require the logs permission are where access regressions most often appear.
Set the rollback decision point before the upgrade window opens: once the production controller has reconciled Applications on 3.4 and writes from the new version have occurred, returning to 3.3 is a restore decision, not a simple image change. A backup of the Argo CD namespace resources and Secrets, taken before the upgrade, covers Applications, AppProjects, repository and cluster Secrets and the ConfigMaps that hold settings; Redis is a cache and is not restored. Ask your team to confirm exactly which objects its backup tool captures and to test one restore on a scratch cluster. Because the official notes define the supported downgrade steps, confirm them against the topology you run, whether single instance, HA manifests or a self-managed Argo CD, and do not improvise a downgrade order during an incident.
How DeployOpen scopes and delivers an Argo CD upgrade
DeployOpen plans the move from Argo CD 3.3 to 3.4 as a written, fixed-scope engagement inside your own infrastructure. The work starts from your current ApplicationSets, Dex or OIDC settings and cluster inventory, then tests each change that the upgrade notes call out before anything reaches production.
How we scope
- Inventory every ApplicationSet that uses the cluster info auto-label annotation and list the kubernetes-version replacements needed.
- Confirm which identity path you use, bundled Dex or direct OIDC, and record the token and JWKS settings it depends on.
- Agree in writing which environments, clusters and Argo CD instances are in scope, plus the rollback and acceptance criteria.
How we build
- Update manifests and ApplicationSet templates in Git, then review the diff against the 3.3 to 3.4 upgrade notes item by item.
- Stage the upgrade on a non-production instance that mirrors your SSO connector, RBAC policy and cluster registrations.
- Check health reporting for Missing and Degraded applications, and confirm signing key rotation keeps old keys in JWKS longer than token lifetime.
How we hand over
- Deliver a written runbook covering the change order, verification steps, backup restore point and rollback procedure.
- Document each ApplicationSet and configuration change with its reason, so your platform team can audit the upgrade later.
- Walk your operators through post-upgrade checks, including login flows, sync status and Dex connector failure behavior.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped in writing alongside the upgrade.
- Patch releases for supported minor lines are tracked, so the next maintenance window can be planned against a known target.
- Confirm with your team which Argo CD minor version you will run next, since the upgrade path beyond 3.4 is a separate written scope.
