Why a self-managed Argo CD upgrade needs its own plan
An Argo CD instance that deploys its own manifests from Git can stop the tool that would repair it. If the new version fails to start, the controller that normally reconciles the argocd Application may be the component that is broken, so the upgrade needs a rollback path before it begins. This page covers only what changes when Argo CD manages itself: bumping the version in the Kustomize base, the ServerSideApply=true sync option, the order of CRD changes and recovery when the new controller does not start. General upgrade steps for each version pair are covered on the sibling pages.
Upgrades are unavoidable because the project's support window is short. The Argo CD release process ships a minor release four times a year, once every three months, and only the three most recent minor versions receive patch releases. On October 12, 2026, the GitHub releases page published patch releases v3.5.5 (marked latest), v3.4.11 and v3.3.16, with v3.6.0 in release candidate. Confirm which line your instance runs before planning, because an older line may no longer receive fixes. Read the Argo CD release process and cadence page for the current policy.
The supported path runs through each upgrade note in order, not directly to the newest release. Each minor step can change RBAC, CRDs or sync behavior that the self-managed Application depends on, so a jump that skips a note can leave the controller unable to reconcile its own resources. Before you start, confirm the current version, the target version and every upgrade note in between, and record who approves the cutover. DeployOpen works inside your own clusters, cloud accounts or air-gapped networks, and can plan and carry out this sequence with your team.
Which release changes affect a self-managed upgrade
This table lists the release changes that touch an Argo CD instance deploying its own manifests from Git, with the impact of each and the action to take before the upgrade. Read it as a pre-upgrade checklist, and confirm each action against the official upgrade notes for the exact versions you pass through.
| Change | Impact on a self-managed upgrade | Action needed |
|---|---|---|
| Argo CD 3.3 requires ServerSideApply=true for the ApplicationSet CRD | The ApplicationSet CRD is too large for client-side apply, so a self-managed Application that syncs without this option can fail to apply the upgraded manifests. | Add ServerSideApply=true to the Application's sync options before bumping the version in the Kustomize base. |
| Update and delete RBAC apply only to the application itself (2.14 to 3.0) | Policies that granted update or delete on projects or wider scopes stop working, which can block the Argo CD Application from managing its own resources. | Rewrite RBAC policy rows for update and delete so they target the application, and test the policy on a non-production instance. |
| Logs access requires an explicit logs, get permission (2.14 to 3.0) | Users and automation that read pod logs through Argo CD lose access after the upgrade, which can slow troubleshooting of a failed controller start. | Add a logs, get grant to each role that needs log access and verify it before cutover. |
| Repositories moved from argocd-cm to Kubernetes Secrets (3.0) | Repository entries left in argocd-cm are no longer read, so the Application that defines Argo CD itself may stop resolving its Git source. | Recreate each repository as a Kubernetes Secret and confirm the Application still syncs from Git after the change. |
| Dex RBAC uses the federated_claims.user_id claim (3.0) | Role mappings keyed on the older subject format stop matching, so SSO users may lose access to the instance that manages the upgrade. | Update Dex RBAC subjects to federated_claims.user_id and sign in with a test account before the cutover. |
| Annotation-based resource tracking is the default (2.14 to 3.0) | Resources that were tracked by label may appear OutOfSync or be pruned if tracking changes during the upgrade. | Review the resource tracking setting in the Argo CD configuration and check sync status of Argo CD's own resources after the change. |
| Sibling upgrade notes cover each minor step | Each minor release has its own breaking changes, so a jump across several versions can miss changes that appear in intermediate notes. | Read the notes for every minor version you pass through in order, and list the actions for each step before starting. |
How to upgrade Argo CD that deploys itself, step by step
This sequence moves a self-managing Argo CD to a new minor version in Git, with a recorded rollback point at each stage so a failed controller start can be reverted without losing applications.
Confirm the current version and read the upgrade notes
The platform owner records the Argo CD version the running instance reports, identifies the target version, and reads every official upgrade note between the two, not only the last one. Confirm the version against the release list on the project's GitHub releases page and check whether your current minor line still receives patch releases under the project's release process. The step is done when you have a written list of breaking changes that apply to your RBAC, SSO, repositories and sync settings, each with an owner. Upgrade notes for the 3.2 to 3.3 move (where the ApplicationSet CRD now requires server-side apply) and for any earlier major changes you cross must all be on that list. Rollback point: none yet, because nothing has changed.
Back up Application, AppProject, Secret and ConfigMap objects
Export the cluster state Argo CD depends on from the namespace it runs in: Application and AppProject resources, repository and cluster Secrets, the argocd-cm and argocd-rbac-cm ConfigMaps, and any custom settings. Store the exports outside the cluster, and confirm the Secret exports are encrypted at rest under your own key management. Verify that each export file is readable and that the object counts match what the cluster reports. This is the restore path if a later stage leaves the instance without its definitions. Rollback point: the exported set, which you restore with a standard apply if the controller cannot be recovered from Git alone.
Confirm the self-management Application setup
Check that the Application that manages Argo CD points at the Git path holding the Kustomize base, that it has automated sync enabled, and that its sync options include ServerSideApply=true. The declarative setup guide describes this layout, and the 3.3 notes state the option is required for the ApplicationSet CRD, which exceeds the client-side apply size limit. Run a dry render of the base locally to confirm the output matches the live manifests. Mark this as a risk point: with automated sync on, any partial change you push will be reconciled by the instance immediately, so a half-finished edit is applied without a pause. The step is done when the Application shows the expected path and sync options in its spec.
Bump the version in the Kustomize base
In a dedicated branch, change the Argo CD version reference in the Kustomize base to the target release, and update any image tags or pinned manifest URLs the base uses. Keep the change to the version and the adjustments required by the upgrade notes, so the commit is easy to review and revert. Open a pull request that lists the breaking changes from step one and the owner of each. Merging the commit is the point where automated sync will act, so merge only after review and after the backup from step two is confirmed. Rollback point: the commit to the previous base, which you can revert in Git if the rollout fails.
Let CRDs apply before controllers and check ApplicationSet
Watch the sync as Argo CD applies the new manifests. CRD definitions should be established before the controller Deployments roll, and the ApplicationSet CRD should apply cleanly under server-side apply. Confirm with kubectl that the CRDs report as established and that the ApplicationSet CRD carries the new schema version. If the CRD apply stops partway, the cluster may hold a mix of old and new definitions, and automated sync can keep retrying against that state, so pause automated sync on the self-management Application before you investigate. Done when every CRD in the release reports established and the sync result for CRDs shows no errors. Rollback point: revert the commit so the previous CRD and controller set is re-applied.
Watch the controller rollout and check health
Follow the rollout of the application controller, API server and repo server, and confirm each new pod reaches Ready. Check the Argo CD Application that manages itself for Healthy and Synced status, and check a sample of other Applications to confirm reconciliation resumes. Look for stuck Progressing states, repeated sync retries and errors in controller logs. If a new controller fails to start, do not force sync; the controller cannot reconcile its own fix, so recover from outside the loop. Done when the controller pods are Ready, the self-management Application is Healthy and Synced, and a test Application reports the expected revision.
Define and use a rollback point at each stage
Record the rollback option for each stage before you proceed: the reverted Git commit for manifest changes, the restored backup from step two for lost objects, and the previous base re-applied with server-side apply if the Git revert itself is blocked. If the controller cannot start, first disable automated sync on the self-management Application so the cluster stops retrying the broken state, then apply the previous base directly, and reconcile Git back to match. Confirm that the instance reports the old version and that applications are Healthy before you close the change. Rollback is complete only when the version, CRDs, controller pods and Application status all match the previous known-good state.
Close the change and confirm the next upgrade path
After the new version is stable, re-enable automated sync if you paused it, record the final version, the backup location, the list of upgrade notes applied and the names of the people who reviewed the change. Confirm the instance is on a minor line that still receives patch releases under the project's release process, and schedule the next upgrade review against the release cadence. Keep the backup until the change record is accepted by your change board. Done when the change record lists the version, backup location and open follow-ups, and the self-management Application shows the expected state.
What to prepare before changing the version in Git
When Argo CD manages its own manifests, the version change is a Git commit that Argo CD then applies to the controller that is making the change. Preparation has to cover the state you could restore, the settings a new version might reset, a place to rehearse the change, a quiet window, and a recovery path that does not depend on the instance being upgraded.
Back up cluster objects and Git
Export the argocd namespace objects, including the Application that manages the instance, AppProjects, ApplicationSets, the argocd-cm, argocd-rbac-cm and argocd-secret objects, and repository Secrets. Take a mirror or bundle of the Git repository that holds the Kustomize base and overlays. Confirm you can restore both without a live Argo CD, since the backup is only useful if it works during a failed upgrade.
Inventory local customizations
List every patch, plugin, custom health check, resource customization and RBAC policy that sits in the base or overlays. Note each SSO setting and the Dex or OIDC configuration it depends on. Check each item against the upgrade notes for the target version, because a setting that was valid in one minor release may be renamed, moved or removed in the next.
Rehearse on a mirror instance
Stand up a non-production Argo CD that uses the same Kustomize base structure, the same Application sync options and a copy of the same repository layout. Point it at a test cluster or a separate namespace. Run the version bump there first and observe whether the controller starts, the ApplicationSet CRD applies, and the self-managed Application stays Synced and Healthy.
Freeze sync-affecting changes
Pause merges to the Argo CD repository and to the repositories that feed application manifests during the upgrade window. Disable automated sync on the self-managed Application only if your change process requires it, and record who holds the freeze. A change to an app manifest made mid-upgrade can be applied by a controller that is already in a partial state, which makes the failure harder to read.
Keep a recovery path outside Argo CD
Name one or more people who can reach the cluster API with cluster-admin rights and apply manifests directly with kubectl, without going through Argo CD. Verify their access before the window opens. If the new controller cannot start, it cannot roll itself back, so the recovery steps and the previous image or manifest revision should be written down and reachable from outside the cluster.
What to do when the new controller does not start
If the new application controller or repo-server cannot start, Argo CD cannot repair itself through its own sync. The Application that manages Argo CD is reconciled by the very components that failed, so waiting for automated sync to correct the problem will not work. Before changing anything, decide which of two recovery paths fits your setup: reverting the Git change so the previous manifests are re-applied, or applying the previous manifests directly to the cluster from outside the GitOps loop. Either way, the goal is to restore a working controller first and investigate the failed version afterwards.
Start with the checks that cost nothing. Confirm which Custom Resource Definitions the cluster now holds, especially the ApplicationSet and Application CRDs that the upgrade changed, and whether the older controller can still read them. Confirm that someone can still log in with an account that does not depend on the failed pods, such as a local admin or a directly reachable identity provider session, and that your kubeconfig still works against the cluster. If the failed release relies on SSO and the login path breaks with it, you will need a way to reach the UI or the argocd CLI that bypasses it. Record the current state of the Argo CD Deployment, StatefulSet and ConfigMaps so you can compare against them later.
Once you have a restore path, use the release notes for the exact version you are moving from and to to confirm each command, including any CRD ordering, the ServerSideApply=true sync option and whether a full manifest re-apply is needed. The upgrade notes for Argo CD's upgrade documentation are the natural starting point for the 3.2 to 3.3 change. Do not run a rollback against a cluster you have not tested in a non-production environment, and keep the Git revert and the direct apply in agreement so the next automated sync does not pull the failed version back in.
How to test the upgrade and decide on rollback
Start with a copy of the instance that deploys the same Git layout into a separate cluster or namespace, with the Application that manages Argo CD pointed at the target version. This is where you find out whether the ServerSideApply=true sync option is in place, whether the CRD changes apply in the order you expect, and whether your own RBAC and SSO settings survive the move. Use a copy that holds realistic configuration, not a bare install, because most upgrade surprises come from local settings.
- Sync status: Confirm every Application reports Synced and Healthy after the upgrade, and that the Argo CD Application for itself does not show an unexpected diff.
- RBAC for teams: Log in as a representative user from each team and confirm update, delete and logs actions behave as the 2.14 to 3.0 notes describe.
- SSO login: Test each identity path, including the bundled Dex or direct OIDC connection and the group-to-role mapping.
- Repository access: Confirm repositories still resolve from Kubernetes Secrets and that private Git pulls succeed.
- Cluster connections: Check that every registered destination cluster is reachable and reports its expected version.
Record the results. A copy that passes all five checks is the evidence you need to move to the production window.
In production, the rollback decision is made against a written checklist agreed before the window opens. Apply the change in stages rather than all at once, and pause after each stage to compare results with the pre-upgrade baseline you captured. Keep a current backup of the Argo CD namespace, its Secrets and the Git state it deploys from, so that a restore is possible even if the self-managing Application cannot run.
- Baseline first: Export the Application list, sync status and RBAC policy before the first change so you have something to compare against.
- Staged rollout: Upgrade the control plane, then check the Application controller and repo-server before accepting traffic from teams.
- Access checks: Verify at least one administrator and one standard user can sign in through SSO within the window.
- Cluster and repository checks: Confirm sync against a sample of applications on each destination cluster and the repository Secrets.
- Rollback trigger: Agree in advance which failures (for example, a broken SSO path or a controller stuck in a restart loop) trigger a rollback, and who has authority to call it.
If any trigger is met and the fix is not clear within the window agreed for the change, roll back rather than debug live.
A failed start is the case where the new controller will not run, so Argo CD cannot repair itself from Git. The safe path is to restore the last known good state directly with the cluster tools you already have, not through the Argo CD interface, which may be unavailable. Confirm first whether the problem is the new version, a CRD ordering issue, or a configuration key the new release no longer accepts, because the fix differs for each.
- Find the failing component: Check the pod status and logs for the application controller and API server to see whether the failure is in the image, the CRDs or the configuration.
- Check CRDs: Confirm the ApplicationSet and Application CRDs match the version you are reverting to before applying anything else.
- Restore from backup: Re-apply the manifests from the version you were running, using the backup taken before the change.
- Verify after restore: Re-run the sync status, RBAC, SSO, repository and cluster checks before declaring the instance healthy.
- Record the cause: Write down the failing setting or version so the next attempt starts with a corrected plan.
Ask your team whether it can reach the cluster without Argo CD during an incident. If the answer is no, that gap should be closed before the next upgrade.
What makes a self-managed Argo CD upgrade take longer
This table lists the factors that expand the work of upgrading an Argo CD instance that deploys its own manifests from Git. Read each row as a question to answer about your environment before estimating effort, since the same version jump can be routine for one team and lengthy for another. The main takeaway is that the number of versions crossed matters less than what depends on the controller and whether a tested rollback exists.
| Driver | Why it matters | Effect on effort |
|---|---|---|
| Minor versions crossed | Each minor release can carry its own upgrade notes, and a jump from an older line means reading several sets of breaking changes in order. | Increases reading, testing and sign-off work with each minor version added. |
| Customizations in the Kustomize base | Patches, image overrides and extra resources in the self-management base must be reconciled with the new upstream manifests before sync. | Raises effort when local patches touch CRDs, RBAC or the controller Deployment. |
| SSO and Dex configuration | Dex connectors, OIDC client settings and redirect URIs live in the same managed manifests and can break login if changed incorrectly. | Adds validation steps that need an identity provider test account and a rollback login path. |
| RBAC rewrites | Policy changes in a major release can alter what users and automation may do, so existing roles need review against the new rules. | Adds policy review and access testing for each team and service account. |
| Applications and clusters depending on the controller | A controller outage stops reconciliation for every Application it manages, and a failed upgrade can affect every destination cluster at once. | Increases the maintenance window planning, communication and staged verification needed. |
| Tested rollback path | Self-managed upgrades can leave the controller unable to start, so recovery depends on backups and a known way to restore the previous version. | Without a tested rollback, effort rises sharply because recovery steps are designed under pressure. |
| Server-side apply handling | The sync option must be set in the Application before the upgrade, and CRD changes must be ordered so the new controller can start. | Adds a rehearsal on a non-production instance to confirm sync behavior and CRD ordering. |
| Non-production instance available | A separate instance lets the team rehearse the exact manifests, SSO settings and RBAC policy before touching production. | Shortens production cutover work when rehearsals already found the problems. |
Common questions about upgrading a self-managed Argo CD
Does upgrading a self-managed Argo CD cost more than doing it in-house?
Not necessarily, but the cost depends on what you are buying. An in-house upgrade costs your platform engineers' time, while a fixed-scope engagement costs the agreed fee for defined deliverables. Argo CD itself is licensed under Apache-2.0 with no paid edition from the project, so the spend is labor and environment work, not software licensing. Ask any partner for a quote that itemizes the upgrade-note review, the test instance run, the manifest changes, the cutover window, the rollback rehearsal and the handover documentation. Also ask which items recur, such as a retainer for later patch releases, and which are one-time. Your own cost should include the same items, plus the time your team spends learning the breaking changes.
How long does a self-managed Argo CD upgrade take?
The duration is driven by how far you are moving, how many clusters and Applications Argo CD manages, and how much of your configuration lives outside Git. A single minor step with clean manifests is usually a shorter task than a multi-version jump with custom RBAC, SSO and plugin changes. Testing on a non-production instance and the number of upgrade notes you must act on add time. Ask for a schedule in the written scope that separates review, staging, production cutover and post-upgrade checks, and confirm which parts depend on your change approval windows. DeployOpen does not publish durations, so the timeline comes from the scope agreed in writing.
What does our team have to provide during a self-managed upgrade?
Your team needs to provide access and decisions that only your organization can make. Expect to supply read access to the Git repository that holds the Argo CD base manifests and overlays, a non-production instance or cluster for rehearsal, and a named owner for change approval. You will also need to confirm which Applications are business-critical, the maintenance window, and the backup location for Argo CD's Kubernetes objects. Plan for someone who knows your SSO and RBAC setup to review the changes that the upgrade notes affect. Confirm these responsibilities in the scope before work begins.
Can one platform engineer upgrade a self-managed Argo CD alone?
A single experienced platform engineer can often carry out the technical steps, but the upgrade is safer with a second person who can review changes and approve the cutover. The work touches the Argo CD Application that manages itself, so a mistake can stop reconciliation for every workload it deploys. Pairing the operator with a reviewer, keeping a documented rollback path, and running the change on a non-production instance first reduces that risk. Whether one person is enough depends on your change control rules and on how much of the configuration is documented. Ask any partner to state which roles it expects from your side.
Do Helm users face the same ServerSideApply change?
Helm users usually do not hit the same change in the same way. The 3.3 upgrade notes require ServerSideApply=true in the sync options of an Argo CD Application that manages Argo CD itself, because the ApplicationSet CRD exceeds the client-side apply size limit. If you install Argo CD with the community Helm chart, you upgrade through the chart and its release notes, and you should read both the chart documentation and the Argo CD upgrade notes before you change anything. Confirm how your chart version maps to your Argo CD version, and check your CRD handling with a dry run on a test cluster.
Is it safe to skip Argo CD versions during an upgrade?
Skipping versions raises risk because each minor release can contain breaking changes that the upgrade notes describe, and you must handle each one before moving. Argo CD's release process states that only the three most recent minor versions receive patch releases, so an older line may already be out of patch support. Read every upgrade note between your current version and the target, back up the Kubernetes objects, and test the full path on a non-production instance. Ask for the intermediate steps in the written plan, and confirm the target version against the official release notes at the time of the change.
How do you protect the rollback path if the new controller fails to start?
Protection starts before the change. Back up the Argo CD namespace objects, the Application definitions, the repository and cluster Secrets, and the Git revision that is currently deployed, so you know the last known good state. During the cutover, the rollback is a revert of the Git commit that bumped the version, followed by a sync with the previous manifests. Because Argo CD keeps its data in Kubernetes objects and treats Redis as a disposable cache, the recovery plan focuses on the manifests and Secrets. A rehearsal on a non-production instance confirms the steps work before production. Ask your partner to document the rollback steps in the scope and to name who can execute them during the window.
How DeployOpen scopes and delivers a self-managed Argo CD upgrade
DeployOpen approaches a self-managed Argo CD upgrade as a scoped change to the Git repository that holds Argo CD's own manifests, not as a one-off cluster command. We agree the target version, the upgrade notes that apply, and the rollback path in writing before any change is made to your environment.
How we scope
- Confirm the current and target Argo CD versions, and which upgrade notes between them apply to your instance.
- Inventory the Kustomize base, the Application that manages Argo CD, and any CRDs or sync options that live in Git.
- Record the written scope, deliverables and timeline before work starts, since most engagements are fixed-scope.
How we build
- Prepare the version bump and the ServerSideApply sync option in a branch, reviewed like any other change.
- Rehearse the upgrade on a non-production instance and check that the new controller starts and reconciles.
- Write the CRD ordering steps and the recovery procedure for a controller that fails to start, then test that recovery.
How we hand over
- Deliver the changed manifests, a runbook for the production cutover, and the rollback steps in your repository.
- Document the verification checks, including application sync status, controller health and SSO login, that confirm success.
- Walk your platform and security teams through the change record so they can repeat the upgrade for the next minor release.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer if you want DeployOpen to handle future minor releases.
- Track the patch and minor releases your team needs to plan for, and confirm the support window with the project's release process.
- Ask for a quote built from the written scope, covering one-time upgrade work and any recurring retainer separately.
