What upgrades and support involve for Argo CD
Argo CD is licensed under Apache-2.0, and the project itself offers no paid edition. Your organization therefore owns every upgrade, patch and security response for the control plane that deploys into your clusters. The first thing to track is which minor version each Argo CD instance runs and whether that minor version is still one of the three most recent, because only those three receive patch releases.
Four events should trigger upgrade work. The first is a patch release, such as the v3.5.5, v3.4.11 and v3.3.16 releases published on October 12, 2026, which were issued across three minor lines at once. The second is a minor version falling out of the supported window. The third is a planned move from 2.x to 3.x. The fourth is a new cluster or an identity change, such as a new SSO connector, which can alter RBAC behavior. Each trigger needs a named owner and a non-production instance to test against.
Routine patching usually stays in-house. A platform team with an on-call rotation can read the release notes, update a staging instance, sync a representative application and then promote the change. The breaking-change upgrade is where outside help pays off. The 2.14 to 3.0 notes change update and delete RBAC so it applies only to the application itself, require an explicit logs, get permission, make annotation-based tracking the default, and move repository definitions from argocd-cm into Kubernetes Secrets.
Ongoing coverage is a separate decision. If your team cannot absorb patch triage and advisory response on short notice, ask a partner for a retainer and get the response commitments in writing before signing. Confirm who watches release announcements, how security advisories are assessed, and which Argo CD versions the agreement covers. Several of these answers depend on your own environment, so verify them rather than assuming them.
What the work includes and what you receive
Each component below is fixed in writing before work starts, with its exact scope, named deliverables and acceptance checks. Each card states what you keep when that component closes: a runbook, test results, a change record or updated configuration in Git.
Version inventory and support-window check
We record every Argo CD component version in your clusters, including the API server, repo-server, application controller and any bundled Dex, and compare each against the three most recent minor versions that receive patch releases. We also review the compatibility notes for the tools your repositories depend on. You receive an inventory sheet, the support dates to confirm with the release notes, and a list of gaps to close before the upgrade window.
Upgrade plan and non-production rehearsal
We write the upgrade plan around your release cadence, sequencing control plane, repo-server and cluster changes, and rollback points. The rehearsal runs the same steps in a non-production environment built from your Git repositories and cluster list, so sync behavior and health checks are observed before production. You receive the runbook, the rehearsal results and a record of the decisions made with your team.
2.x to 3.x migration checks
Before a 2.x instance moves to 3.x, we review the breaking changes that touch your setup: RBAC for update and delete now applying to the application itself, explicit logs permissions, annotation-based resource tracking as the default, repository definitions moving from argocd-cm into Kubernetes Secrets, and Dex RBAC using the federated_claims.user_id claim. Each item is checked against your configuration. You receive a migration checklist and the Git changes it produced.
Post-upgrade verification
After cutover we verify that applications still sync to their intended state, that projects and RBAC grant the same access as before, that SSO logins behave as designed, and that the built-in admin user remains disabled where you set admin.enabled to false. Checks run against a list agreed before work starts. You receive test results with timestamps, the evidence for each check, and a rollback decision record.
Patch and minor-release handling
Under a support agreement, we track patch releases for the three most recent minor versions and assess each one against your environment before scheduling it. Minor releases arrive four times a year, so the agreement sets how far behind your instance may run before an upgrade becomes urgent. Each change follows the same rehearsal and verification steps. You receive a release assessment for each patch and a dated change record for each applied update.
Documentation handover
At the end of the engagement, your team receives the runbook, the version inventory, the rollback procedure and the configuration as it now lives in Git. Each upgrade step is assigned to a named role, so that no single engineer holds the upgrade knowledge. We confirm the handover in a walkthrough that your operators attend. You receive the documentation set, the handover record and a list of open items.
What drives upgrade effort and support scope
This table lists the Argo CD factors that set how much work each upgrade and support engagement involves, why each one matters, and how to keep it manageable.
| Driver | Why it changes the work | How to keep it down |
|---|---|---|
| Instances and clusters managed | Each instance and each registered cluster adds upgrade checks and cluster-side testing against the release notes. | Consolidate onto fewer instances where your boundaries allow, and keep one staging instance that mirrors production configuration. |
| Applications and ApplicationSets | A large set of Applications and generated ApplicationSets widens the regression set and slows pre-upgrade diffing. | Generate Applications from a small set of templates, and keep a representative sample for pre-upgrade sync tests. |
| Projects and custom RBAC policies | After 3.0, update and delete permissions apply only to the Application itself, and logs need an explicit logs, get permission. Each custom policy needs retesting. | Keep RBAC policies in version control, use a small set of roles, and test each role's access before and after the upgrade. |
| Repository definitions | Argo CD 3.0 removed repository configuration from argocd-cm, so every repository must move to a Kubernetes Secret. | Script Secret creation from one source of truth, then confirm each repository still syncs in staging. |
| SSO path (bundled Dex or direct OIDC) | Dex-based RBAC uses the federated_claims.user_id claim after 3.0. Direct OIDC setups need their own claim and group mapping checks. | Choose Dex or direct OIDC before go-live, and record which claim each RBAC rule depends on. |
| Resource tracking method | Annotation-based tracking is the default from 2.14 to 3.0. Clusters on another tracking method need a tested change path. | Confirm the tracking setting in each instance before upgrading, then sync representative Applications to verify behavior. |
| Config management tools in repo-server | The repo-server runs Helm and Kustomize on repository content, so each tool version and any added tooling becomes part of the upgrade surface. | Pin tool versions, keep an inventory of any added plugins, and limit repositories to approved sources. |
| HA topology | HA manifests need at least three nodes because of pod anti-affinity, and sharded application controllers change how replicas roll during upgrades. | Confirm node count before scheduling, and rehearse a rolling upgrade on a non-production HA install. |
| Compliance evidence needs | Assessors may ask for change records, RBAC reviews and test results for each upgrade, so the evidence set grows with every managed instance. | Agree the evidence list with your assessor early, and generate it from version control and test runs where possible. |
Upgrade and support phases and their outputs
This sequence moves an Argo CD instance from one supported minor version to another with evidence at each stage, then keeps it inside the supported window.
Inventory the current version and configuration
The platform owner records the running Argo CD version, the install method, every Application and AppProject, the RBAC policy, repository definitions, SSO settings and the resource tracking method in use. The output is a version and configuration inventory, signed off by the platform owner and checked against what each cluster actually runs.
Build the gap list from release notes
The team reads the release notes for every minor version between the current release and the target, then lists each change that touches the inventory. Illustratively, a move from 2.14 to 3.0 would flag the narrower update and delete RBAC scope, the new logs permission, repository definitions moving to Secrets and the Dex claim change. The output is a gap list with an owner and a fix for each item.
Rehearse the upgrade in staging
The team restores a staging instance from a copy of production configuration, applies the target version and runs RBAC tests for each role, including logs access and sync permissions. They also test how the tracking method treats existing resources. The output is test evidence: recorded results, logs and a defect list with fixes. The rehearsal closes when every high-severity defect is resolved.
Approve the change window and rollback plan
The change record names the target version, the window, the approvers, the backup of Argo CD state and the rollback steps, such as reverting the image or chart version. The team also confirms the break-glass access path before the window opens. The output is a signed change record and a runbook, approved before the window starts.
Run the production upgrade and verify
The team executes the runbook in the approved window and watches the API server, application controller and repo-server health. They sync representative Applications to confirm they reconcile without unexpected drift, then test SSO login, sample user permissions, tracking behavior and HA pod placement. The output is a post-upgrade verification record filed in the change log.
Run the recurring support cycle
Minor releases ship four times a year, and only the three most recent minor versions receive patch releases, so the team reviews each quarterly release and patch against the deployed version. Each cycle produces an updated inventory, a gap list for the next target and a revised runbook. The output is a dated support record. The cycle is complete when the deployed version is still one of the three supported minors.
What goes wrong in Argo CD upgrades and how to prevent it
Each card names one upgrade risk specific to Argo CD, the prevention step and what to verify before cutover. Test these in a staging instance that mirrors your production SSO, repositories and cluster topology.
Application-scoped RBAC after 2.14
From 2.14 to 3.0, update and delete RBAC rules apply only to the application itself, and reading pod logs requires an explicit logs, get permission. Roles that relied on broader matching can stop working without an obvious error. Before cutover, export every project and global role, replay the actions your operators and pipelines perform in staging, and confirm that log viewing and sync operations behave as expected.
Repositories left in argocd-cm
Argo CD 3.0 removed repository configuration from the argocd-cm ConfigMap, so repositories must be defined as Kubernetes Secrets. Entries left in the old ConfigMap stop working after the upgrade, and applications that depend on them fail to sync. Inventory every repository and credential reference, recreate each as a labeled Secret, and confirm that each application syncs from the new definition in staging.
SSO role mapping after claim change
Dex-based RBAC in 3.0 uses the federated_claims.user_id claim, so group and user mappings written against earlier claims may no longer match signed-in users. Access can change without an error message. Decode a test login from each identity connector in staging, confirm which claim carries the identity, and check that each role mapping still grants the intended project access.
Resource tracking method change
Annotation-based resource tracking is the default in 3.0. If an application uses a different tracking method, a change in tracking can make Argo CD treat existing resources as unowned or out of sync, which risks unexpected pruning. Before cutover, confirm the tracking method each application uses, review the diff of a dry run, and disable automated pruning on critical applications until the first full sync has been reviewed.
HA on too few nodes
HA manifests need at least three nodes because pod anti-affinity rules place replicas on separate nodes. Clusters with fewer nodes can leave HA components unschedulable or running without redundancy. IPv6-only clusters are not supported. Before upgrading, confirm the node count, scheduling capacity and IP family of the target cluster, and rehearse a controller failover in staging.
Untrusted Helm and Kustomize content
The repo-server runs Helm and Kustomize against repository content, so a repository your organization does not control can influence what gets read and rendered. Out-of-tree file access is a related risk. Before cutover, restrict source repositories in each project, review whether Helm or Kustomize options allow reads outside the repository, and confirm that repo-server network exposure matches your hardening plan.
Which upgrade and support tasks stay in-house and which go to a partner
Each row names a recurring Argo CD upgrade or support task, the skills it needs, and whether teams usually keep it internal, split it, or outsource it, based on team size and on-call coverage.
| Task | Skills needed | Usually kept | Why |
|---|---|---|---|
| Watching the release feed and support window | Kubernetes operations, GitOps practice | In-house | Low effort but needs a named owner. Only the three most recent minor versions receive patches, so the window moves each quarter. |
| Applying routine patch releases in a test environment | Kubernetes operations, GitOps practice | Split | The internal team applies patches in its own pipeline. A partner can script the process, but rollback decisions stay with the on-call team. |
| Reviewing breaking-change notes for each minor version | GitOps practice, security review | Split | Internal owners judge impact on their repositories and projects. A partner can trace upgrade-note changes, such as RBAC and tracking defaults, to specific configuration. |
| Rehearsing upgrades in staging | Kubernetes operations, GitOps practice | Outsource first, then in-house | Teams often outsource the first major move, such as 2.x to 3.x. Once a repeatable runbook exists, a small team can rehearse each minor upgrade itself. |
| Updating RBAC and SSO group mappings | Identity administration, security review | In-house | Access decisions belong to the organization. The identity team changes mappings through its normal change approval, and a partner can review the diff. |
| Handling incidents during or after an upgrade | Kubernetes operations, GitOps practice, security review | Split | Teams with thin on-call rotations often need a partner for after-hours cover on the upgrade window. Confirm response hours in writing before go-live. |
| Producing audit evidence for changes and upgrades | Security review, identity administration | Split | The organization keeps approvals and records. A partner can prepare change logs and test results, but independent auditors issue any assessment outcome. |
How upgrade and support work differs by starting point
Teams on 3.x mostly run a steady cycle of picking up patches and new minors inside the support window. The scope is smaller, but the work recurs.
- Patch releases: Only the three most recent minor versions receive patch releases, so the line you run must stay among them.
- Minor upgrades: Plan a minor upgrade for each quarterly release you intend to adopt, and read its release notes before scheduling it.
- Test set: Keep a staging instance with representative applications, projects and RBAC so each upgrade is checked before production.
- Recurring effort: Expect this work to repeat every cycle, so ask whether a quote covers one upgrade or an ongoing retainer.
Moving from 2.14 to 3.0 is a breaking-change migration that touches access control, configuration storage and identity, so it needs its own plan and test cycle.
- RBAC: Update and delete permissions now apply only to the application itself, and viewing logs requires an explicit logs, get permission. Review every role built on the old behavior.
- Resource tracking: Annotation-based tracking is the default, so confirm how existing applications are tracked before cutover.
- Repositories: Repository definitions in the argocd-cm ConfigMap were removed in 3.0 and must be Kubernetes Secrets, so each repository needs to be rebuilt.
- Dex claims: Dex-based RBAC uses the federated_claims.user_id claim, so test group mapping against your identity provider.
- Patch status: Confirm with the project which 2.x line, if any, still receives patches before you set the schedule.
A cluster running a minor older than the three most recent receives no patch releases. The work starts with an inventory and a path back into the supported window.
- Inventory: Record the running version on each control plane and each managed cluster, since fleets often drift apart over time.
- Upgrade path: Step through each intermediate minor that the upgrade notes require, and verify each step in staging before moving on.
- Residual risk: Until upgraded, the instance carries known defects without vendor patches. Document the exposure and any compensating controls with your security owner.
- Quote scope: Ask whether the fixed-scope quote covers every intermediate step or only the final target version.
Upgrading the control plane is one piece of work, but its effect reaches every cluster it manages. Fleet size changes the rollout and verification plan more than the upgrade itself.
- Blast radius: A control plane upgrade affects every application it reconciles, so the maintenance window must cover all managed clusters.
- High availability: HA manifests need at least three nodes because of pod anti-affinity rules. If the application controller is sharded, confirm the shard settings after the upgrade.
- Cluster checks: Verify cluster credentials, project boundaries and sync status on each target cluster once the upgrade completes.
- Rollout method: Confirm whether a separate test instance or a staged rollout is possible in your architecture, and what the partner will verify per cluster.
Air-gapped networks cannot pull patches from the internet, and regulated teams must show evidence for each change. Both shift part of the work toward internal mirrors and records.
- Internal mirror: Copy the release artifacts, container images and Helm charts you depend on into internal registries, and test them before promotion.
- Render inputs: The repo-server runs Helm and Kustomize on repository content, so list every external source it reaches during rendering.
- Change evidence: Tie upgrade records, staging results, approvals and rollback steps to each change request. DeployOpen prepares this evidence, and independent auditors assess it.
- Patch intake: Agree on how quickly the mirror receives each patch release and who approves its promotion into production.
What you need to provide before an upgrade or support start
Start by collecting the facts about your current Argo CD installation. Record the exact running version, the install method (plain manifests, Kustomize, Helm chart or an operator), and the namespaces it runs in. Export every Application, AppProject and ApplicationSet, and the current argocd-cm and argocd-rbac-cm ConfigMaps. Include the repository configuration as well. Because Argo CD 3.0 removed repository definitions from argocd-cm and moved them to Kubernetes Secrets, the team must confirm where each repository is actually defined before any upgrade plan is written.
Provide the identity provider details for the Argo CD login path: whether users sign in through bundled Dex or directly through an OIDC provider, the connector or client settings, and the group claims used for RBAC. Also confirm whether the built-in admin user is still enabled. Named owners must approve changes and carry the on-call role for the control plane. Confirm who signs off on the target version, who can accept a rollback, and who receives alerts during a change window.
Decide the target minor version and the support tier before the work starts. The target should be one of the three most recent minor versions, since only those receive patch releases according to the Argo CD release process. Decide the acceptable downtime for the control plane and the change windows in which upgrades may run. Decide whether a non-production cluster will be used for rehearsal, and confirm that it runs comparable Application workloads and access patterns.
Grant access to the Git repositories and the cluster contexts the testing needs. This includes read access to every repository that Applications reference and the Kubernetes contexts for the management cluster and the target clusters. Ask for a list of Applications that must not be touched during rehearsal and for any Application that relies on resource tracking behavior, since annotation-based tracking is the default in the newer releases. Gaps in access found during rehearsal usually delay the production window.
Common questions about Argo CD upgrades and support
Can our own team upgrade Argo CD without a partner?
Yes, if your team can run a controlled change to the control plane and test its own applications. Start with the upgrade notes for each minor version you cross, because they list breaking changes. The 2.14 to 3.0 notes, for example, limit update and delete RBAC to the application itself, require an explicit logs, get permission for log access, and make annotation-based resource tracking the default. Repositories defined in the argocd-cm ConfigMap must move to Kubernetes Secrets, and Dex RBAC rules now use the federated_claims.user_id claim. Test each change in a non-production instance first.
How often do we need to upgrade Argo CD in practice?
Plan for a new minor release about every three months, because the project ships four minor releases a year. Only the three most recent minor versions receive patch releases, so a version leaves the patch window once the project has shipped three newer minor versions. Patch releases can arrive between minor versions, so set up a routine for applying them as well as for planned minor upgrades. Confirm the current cadence and support window on the Argo CD release process page before you set your change calendar, since the project may update its process.
What does an Argo CD support agreement cover and what does it leave out?
A support agreement covers the services written into its scope, and that scope decides everything else. Common scope items include planned upgrades to the minor versions you choose, review of upgrade notes against your repositories, RBAC and tracking settings, and a test plan with rollback steps. Ongoing retainers can add response to issues during agreed hours. Agreements usually exclude changes to your application manifests, cluster lifecycle work, and fixes in your own Git or identity systems. Confirm response times and any service levels in writing before you sign.
What does our team have to provide during an Argo CD upgrade?
Your team provides the people and access the work depends on. Name an owner who can approve changes and a platform engineer who knows your clusters. Provide access to a non-production Argo CD instance and the clusters it manages, read access to Git repositories and SSO configuration, and a change window agreed in advance. You also need current backups of Argo CD configuration, a list of the applications, projects and repositories in use, and someone who can confirm each application behaves as expected after the change. Decisions about the production rollout stay with your team.
Is there a paid enterprise edition of Argo CD?
No. Argo CD is released under the Apache License 2.0 (Apache-2.0), and the project itself does not offer a paid edition. Your costs come from the infrastructure that runs it, the people who operate it, and any external services you buy, such as implementation, upgrades or support. Some vendors sell Argo-based products, so check whether a product is the upstream project or a distribution with added features, and which licenses apply to it. Ask any vendor to state the license of each component in writing.
How do we compare partner quotes for an Argo CD upgrade?
Compare the written scope first, because quotes built on different scopes cannot be ranked fairly by price. Check which versions are covered, whether upgrade notes are reviewed against your repositories, RBAC, SSO and tracking settings, and which environments are tested. Ask whether the quote includes a rollback plan, verification steps, handover documentation and post-upgrade support, and for how long. Cost usually rises with the number of clusters, applications, repositories, SSO integrations and custom plugins. Ask each partner to list what is excluded.
How DeployOpen scopes, delivers and supports Argo CD upgrades
DeployOpen agrees the upgrade scope in writing, tests the change against your Argo CD configuration before production, and hands over the record with the changes. Ongoing support is available as a retainer.
How we scope
- The written scope lists the Argo CD versions in and out of the upgrade, and the clusters it touches.
- Scope covers a review of RBAC, logs access and resource tracking settings against the target release notes.
- Fixed-scope engagements are agreed in writing before work starts, and quotes follow from that written scope.
How we build
- Upgrades are rehearsed in a copy of your environment, with the 2.x to 3.x changes applied and checked first.
- Repository secrets, Dex claim mapping and application tracking changes are converted and tested before cutover.
- Test cases cover application sync, project permissions, SSO sign-in and rollback before any production change.
How we hand over
- Each change is documented with the release notes it followed, the settings changed and the tests run.
- Rollback steps and the Git state to restore are written down and walked through with your operators.
- Your team receives the change record, so later upgrades start from a known configuration baseline.
How we support
- Ongoing support is available as a retainer covering upgrades to patch releases in supported minor versions.
- Argo CD ships four minor releases a year, so the agreement should define how each one is assessed.
- Confirm with us which Argo CD versions and cluster counts the support terms cover before signing.
