Why plan the Argo CD 3.1 to 3.2 upgrade before touching production
Moving from Argo CD 3.1 to 3.2 is a single minor-version step, but it changes behavior that can affect running applications, so treat it as a planned change rather than a routine image bump. The breaking changes to handle first are the non-root path requirement for Source Hydrator applications, the CronJob health change that can turn applications Degraded, the Kustomize version set in .argocd-source.yaml, and deprecated repo-server gRPC fields. Argo CD ships a minor release four times a year, about once every three months, and only the three most recent minor versions receive patch releases, according to the Argo CD release process. The October 12, 2026 patch releases covered v3.5.5, v3.4.11 and v3.3.16, so a 3.1 instance was already outside the patch window. Confirm the current list on that page before you pick a target, because the window moves with each new minor release.
The supported path is to read the 3.1 to 3.2 upgrade notes in full before changing anything, then map each item to your own environment. Start with an inventory. Identify every Source Hydrator application and check whether its output path is at the repository root, since stale root-level output from earlier versions is not cleaned up automatically. Then list every CronJob that Argo CD manages, because jobs that run for a while can flip between Healthy and Degraded unless you set resource.customizations.health.batch_CronJob or the argocd.argoproj.io/ignore-healthcheck annotation. The 3.1 to 3.2 upgrade notes are the reference for exact behavior, so record which items apply to you and who owns each fix.
Make the go or no-go decision on evidence from a non-production instance. Run the upgrade against a copy that mirrors your Git layout, Kustomize sources and cluster list, then compare application health and sync status before and after. Confirm which Kustomize version each source pins and whether your repo-server configuration uses any of the deprecated gRPC fields. Plan a rollback path, including a backup of the Argo CD configuration and the Kubernetes objects it manages, before the production change is scheduled.
Which 3.2 changes can break applications and how to handle each
This table lists the Argo CD 3.2 changes that can affect running applications, the impact of each, and the action to take before cutover. Read each row against your own Source Hydrator, CronJob and repo-server configuration, since only some changes will apply to your installation. Where the supplied notes do not give exact behavior, confirm it in the official 3.1 to 3.2 upgrade notes and the release page before you plan the window.
| Change | Impact | Action needed |
|---|---|---|
| Source Hydrator applications need a non-root path | From 3.2 each Source Hydrator application needs a non-root path, and stale root-level output from earlier versions is not cleaned up automatically | Find every Source Hydrator application that writes to the repository root, move output to a dedicated path, and remove leftover root-level files by hand |
| CronJob health changes | Applications may turn Degraded, or flip between Healthy and Degraded, while CronJob jobs run | Decide per application whether to set resource.customizations.health.batch_CronJob or add the argocd.argoproj.io/ignore-healthcheck annotation, then test with a scheduled job |
| Kustomize version in .argocd-source.yaml | The Kustomize version pinned in .argocd-source.yaml may change how manifests render for affected applications | Confirm the exact behavior in the 3.1 to 3.2 upgrade notes and the release page, then render affected applications on a non-production instance and compare output |
| Deprecated repo-server gRPC fields | Fields flagged as deprecated may stop working or change behavior in a later release | Confirm which fields are deprecated and their replacements in the 3.1 to 3.2 upgrade notes, then update repo-server configuration before cutover |
How the non-root Source Hydrator path requirement affects existing repositories
From Argo CD 3.2, each Source Hydrator application needs a non-root path, and output that earlier versions left at the repository root is not removed automatically. That makes the upgrade a repository task as well as a control plane task. Before you change the version, list every application that uses the Source Hydrator, record the repository, branch and path each one writes to, and mark the ones that currently hydrate to the root. Confirm the exact field layout against the 3.1 to 3.2 upgrade notes for your release, since the path settings and hydration output may differ between configurations you have built.
Once the inventory exists, identify the root-level output those applications produced. Look at the hydrated branch or directory each application targets and compare it with the path the application will use after the upgrade. Files that sit at the root and belong to a previous hydration run are the ones that will linger in Git, because Argo CD will not delete them when the new path takes over. Review these files with the owners of each application, since some may be shared with other tooling or hand-maintained manifests that should stay where they are.
Plan the cleanup as its own change, separate from the version bump. Move each application to its non-root path in a test environment first, confirm that the new output is generated and synced, and then remove the stale root-level manifests in a reviewed commit so they do not reappear in later hydration runs. Keep the Git history as your rollback record, and make sure the cleanup is traceable to the change ticket. Ask your vendor or internal Argo CD owner to confirm how the repository should be cleaned for your setup before the production window, rather than relying on the upgrade to do it.
What to prepare before the Argo CD 3.2 upgrade
Most of the risk in the Argo CD 3.1 to 3.2 move sits in configuration that Argo CD reads at sync time, not in the controller binary itself. The cards below cover what to capture, inventory and test before the cutover, so that you can roll back cleanly and recognize a 3.2 side effect quickly.
Back up Argo CD resources
Export Applications, AppProjects, repository Secrets, and the RBAC and settings ConfigMaps from the argocd namespace before you change anything. Store the export outside the cluster so it survives a failed upgrade. Confirm that the export includes the repository credentials, because a restore without them leaves every application unable to fetch Git content. Treat the backup as a rollback path, not a formality.
Inventory Source Hydrator applications
List every application that uses the Source Hydrator and note its current output path. From 3.2 each Source Hydrator application needs a non-root path, and stale root-level output from earlier versions is not removed automatically. Plan a cleanup step for those paths so that old manifests do not sit beside new ones in the repository.
Find CronJobs that will change health
Identify every CronJob that Argo CD tracks, since 3.2 changes CronJob health so that applications can turn Degraded or flip between Healthy and Degraded while jobs run. Decide per workload whether to keep the new behavior, override the health check with resource.customizations.health.batch_CronJob, or add the argocd.argoproj.io/ignore-healthcheck annotation. Write that decision down before the upgrade.
List .argocd-source.yaml files
Search every repository that Argo CD renders for .argocd-source.yaml files and record the Kustomize settings each one sets. The upgrade notes call out the Kustomize version that these files can pin, so a version that your manifests depend on must be tested explicitly against the new release. Keep the list tied to the application that owns each file.
Scan for deprecated repo-server fields
Review the Argo CD configuration in your Git repository and your Helm values or Kustomize overlays for repo-server gRPC fields that the upgrade notes mark as deprecated. Remove or replace each one in a branch before the cutover, and record the changes so that reviewers can tie them to the upgrade. Ask your platform team to confirm that no custom tooling outside Git sets these fields.
Rehearse on a non-production instance
Stand up a non-production Argo CD seeded with representative applications, including Source Hydrator apps, CronJobs and a repo with .argocd-source.yaml. Run the upgrade there first and compare sync status, health and rendered manifests before and after. Confirm SSO sign-in, the admin.enabled setting and project RBAC on the test instance, since the admin account is only meant for setup and disabling it is a check you should verify afterwards.
How to sequence the 3.1 to 3.2 upgrade with checks and rollback points
This sequence moves an Argo CD 3.1 installation to 3.2 in an order that proves each change on a non-production instance first, keeps a restore point before production changes, and confirms application health before the upgrade is treated as finished.
Back up the current installation
Your platform team exports the Argo CD namespace objects, including Applications, AppProjects, ApplicationSets, repository and cluster Secrets, the argocd-cm and argocd-rbac-cm ConfigMaps, and the installed manifests or Helm values, and stores them outside the cluster. Confirm the export can be read back and that someone outside the upgrade team can restore it. Rollback point: the backup is the only path back to the 3.1 state if the new version cannot start, so do not continue until it is verified.
Upgrade a non-production instance
Apply the 3.2 manifests or chart version to a staging instance that manages a copy of your production applications and clusters, using the same SSO and RBAC settings. Watch the application controller and repo-server logs during startup and confirm that every component reports ready. Rollback point: restore the staging backup and reapply 3.1 manifests. Do not promote the change until staging completes a full sync cycle without errors.
Fix Source Hydrator paths and CronJob health settings
Before the production change, review every Source Hydrator application and confirm it uses a non-root path, since Argo CD 3.2 requires one. Remove stale root-level output from earlier versions manually, because it is not cleaned up automatically. Decide how CronJob health should be handled by setting resource.customizations.health.batch_CronJob or annotating affected CronJobs with argocd.argoproj.io/ignore-healthcheck. Check: staging shows these applications as Healthy or expected, with no unexpected Degraded state while jobs run.
Apply the upgrade to production
Schedule the production change in a window agreed with the application owners, applying the same manifests or chart values that passed staging. Keep the staging backup procedure ready and record the exact version and configuration applied. Rollback point: if the controller or API server does not become ready, reapply the 3.1 manifests from your backup and confirm reconciliation resumes before investigating further.
Verify replicas after rollout
If you run the high availability installation, confirm the pods for each component are running on separate nodes. The HA documentation requires at least three nodes for the pod anti-affinity rules, so a smaller cluster will leave replicas unscheduled. Check that the application controller shards and Redis replicas report ready. Rollback point: if replicas cannot schedule, correct node capacity before accepting the upgrade, since a single-node set undermines the availability the HA install provides.
Verify application health and sync status
Compare application health and sync status against the baseline you recorded before the upgrade. Pay particular attention to CronJob-based applications and Source Hydrator applications. Confirm that SSO login, project permissions and cluster connections still work for a test user. Done when counts of Healthy, Synced and Degraded applications match the baseline or every difference is explained and accepted by its owner.
Monitor and keep the rollback path open
Watch controller logs, reconciliation errors and application health for a period your change process defines, and keep the 3.1 backup available until that period closes. Track patch releases for the 3.2 minor line, because only the three most recent minor versions receive patch releases according to the release process. Confirm with your change owner when the backup can be retired and the upgrade is recorded as complete.
Which upgrade path fits your installation type
Teams that install Argo CD by applying the project's standard manifests have the most direct upgrade path. The work is a version change to the manifests you hold, followed by a rollout of the Argo CD components. Because no other tool manages those objects, you control the order of apply and the rollback. The 3.1 to 3.2 changes still reach you, but they land mainly in your applications and configuration rather than in the install itself.
- Backups first: export the Argo CD custom resources, the
argocd-cmandargocd-rbac-cmConfigMaps, and the repository and cluster Secrets before applying anything. - Source Hydrator review: list every application that uses the Source Hydrator, since each one needs a non-root path from 3.2 onward.
- CronJob health: identify applications that contain CronJobs and decide whether to set the health customization or the ignore annotation before cutover.
- Kustomize version: check every
.argocd-source.yamlfile and the Kustomize version it requests. - Repo-server settings: search your configuration for deprecated repo-server gRPC fields and replace or remove them as the upgrade notes direct.
Confirm each item against the Argo CD 3.1 to 3.2 upgrade notes and test on a non-production instance before cutover.
When the release is managed by the argo-helm chart, the chart version and the Argo CD version are separate numbers. Confirm which chart version carries Argo CD 3.2 in the chart's own release notes before you change anything, because this guide does not provide that mapping. The values file you keep under version control is where most of the 3.1 to 3.2 decisions take effect, so review it as carefully as the manifests in the plain path.
- Chart and image versions: pin the chart version and the Argo CD image tag together, and confirm the pairing in the chart release notes.
- Values overrides: review repo-server and Kustomize-related values, and move any deprecated gRPC fields out of the values file.
- CRD handling: check whether the chart version updates CRDs and how your pipeline handles that change.
- Behavior changes: the CronJob health and Source Hydrator changes come from Argo CD, not the chart, so audit applications the same way as plain installs.
- Diff before upgrade: render the chart with the new values and review the output before running the Helm upgrade.
Check that the rendered output shows the expected image version and no deprecated fields before the release is upgraded. For CRD details, read the sibling guide *Upgrading Argo CD installed with the community Helm chart*.
An instance that deploys its own manifests from Git makes the upgrade a change to the system that performs the change. The new version reaches the cluster through Argo CD itself, so a controller that fails to start can block the rollout that would fix it. Plan the version bump in the Kustomize base, the order of CRD and controller changes, and a recovery route that does not depend on the controller running.
- Out-of-band recovery: before starting, confirm you can apply manifests directly or restore the previous image without going through Argo CD.
- Sync options: read the sibling guide for self-managing installs to confirm which sync options the newer release expects, and verify them against the upgrade notes.
- Ordering: apply CRD changes before controller changes, and confirm that order in the sibling guide.
- Automated sync and prune: decide whether automated sync and pruning could revert a partial rollout, and pause them for the upgrade window if so.
- Test copy: run the same version bump on a non-production instance that deploys from a separate repository.
Confirm the rollback path works on the test copy before the production bump is merged. Relevant guide: *Upgrading an Argo CD instance that manages itself*.
High availability manifests run several replicas of the Argo CD components, with Redis in an HA configuration for caching and the application controller optionally sharded. The upgrade has to roll those replicas without a long gap in reconciliation. The CronJob health change matters most here, because applications that flip between Healthy and Degraded can generate noisy alerts across a large fleet. Check placement and capacity before and after the rollout.
- Replica rollout: confirm how each component rolls and whether controller shards keep reconciling during the update.
- Redis behavior: Redis is a disposable cache, so expect a cache rebuild, and confirm the HA behavior in the sibling guide for high availability upgrades.
- Node capacity: the HA manifests need at least three nodes because of pod anti-affinity, so confirm capacity before the rollout starts.
- Alert tuning: if CronJob health changes cause Degraded states, set the health customization or annotation before the rollout so alerts do not fire mid-upgrade.
- Backups: back up the Argo CD resources and repository and cluster Secrets first, as you would for any installation.
After the rollout, compare replica counts, shard assignments and pod placement with your pre-upgrade baseline. The relevant sibling guide is *Upgrading a high availability Argo CD installation*.
How to test the 3.2 upgrade and roll back if applications turn Degraded
Test the CronJob health change first, because it is the upgrade item most likely to alter what your dashboards and promotion gates report. Before the upgrade, record the health status of every Application, then compare the same list on a non-production instance running 3.2. Pay particular attention to Applications that contain CronJobs and to any gate that waits for Healthy. Confirm whether each flagged Application is genuinely unhealthy or is only reporting a job that is still running. You then choose between two fixes. Excluding a specific resource with the argocd.argoproj.io/ignore-healthcheck annotation is narrow and suits a few known jobs. Overriding resource.customizations.health.batch_CronJob in argocd-cm changes the rule for every CronJob the instance manages, so test it against each job type you run before applying it cluster-wide. Confirm the exact key and syntax against the Argo CD 3.1 to 3.2 upgrade notes for your build.
Next, test the Source Hydrator and rendering paths. For each hydrated Application, confirm it uses a non-root path and that a sync produces the expected manifests there. Check that stale root-level output from earlier versions is not left behind, because the upgrade notes say it is not cleaned up automatically. Render every Kustomize overlay with the Kustomize version that 3.2 bundles and diff the output against your pre-upgrade render, especially where .argocd-source.yaml pins a Kustomize version. Also check repo-server behavior under real repository load, since the repo-server runs Helm and Kustomize on repository content, and confirm that any deprecated repo-server gRPC fields you set are removed or replaced in your manifests.
For rollback, the state to protect is in Kubernetes objects. Argo CD keeps Applications, AppProjects, ApplicationSets, and repository and cluster Secrets as Kubernetes resources, while Redis is a disposable cache that rebuilds after a restart. Back up those objects in the argocd namespace (and any other namespaces holding Argo CD resources) before the upgrade, and confirm the backup restores in a test cluster. If you need to roll back, reapply the previous manifests or chart version, restore the saved objects, and let the controller resync. Confirm with your own runbook that the previous minor version is still receiving patch releases, since the release process limits patches to the three most recent minor versions.
What makes the Argo CD 3.2 upgrade take longer
This table lists the factors that expand the work of moving from Argo CD 3.1 to 3.2 and what to do about each one. Read it before estimating a plan, because the rows that multiply the most are usually the number of Source Hydrator applications, CronJobs and environments that need testing. Each driver can be scoped on paper before the upgrade window is set.
| Driver | Why it matters | How to reduce it |
|---|---|---|
| Source Hydrator applications and root-level output | Each Source Hydrator application needs a non-root path in 3.2, and stale root-level output from earlier versions is not cleaned up automatically. | Inventory every hydrator application and its output path, then plan path moves and manual cleanup as separate changes. |
| CronJobs managed by Argo CD | The 3.2 CronJob health change can mark applications Degraded or flip them between Healthy and Degraded while jobs run. | Count CronJobs per application, then decide per group whether to set a health override or the ignore-healthcheck annotation. |
| Repositories and Kustomize versions in use | Repositories that pin Kustomize versions in .argocd-source.yaml may render differently once the bundled version changes. | List repositories with version pins, render manifests before and after the upgrade, and diff the output. |
| Custom health checks and Lua overrides | Existing resource health overrides may conflict with the new CronJob behavior or with changed defaults. | Export current resource customizations, review each one against the 3.2 upgrade notes, and test them on a copy of the instance. |
| SSO and RBAC complexity | Group mappings and project roles are the hardest part to verify, and a broken login path blocks every operator during rollout. | Keep a documented list of role bindings and test one admin, one project user and one read-only user after the upgrade. |
| Deprecated repo-server gRPC fields | Configuration that still uses deprecated repo-server gRPC fields needs to be found and changed before those fields are removed. | Search manifests, Helm values and ConfigMaps for the deprecated fields and confirm the replacement in the upgrade notes. |
| Number of clusters and high availability | HA installs with several replicas and controller shards need a rollout order, and each managed cluster adds reconciliation to verify. | Confirm the HA layout with the HA documentation, upgrade a non-production instance first, then check replicas and node anti-affinity afterwards. |
| Environments that need testing | Every environment that runs a different set of applications, repositories or overrides needs its own test pass before production. | Define a test matrix per environment, record which applications and overrides it covers, and agree sign-off owners before the window. |
Questions teams ask before the Argo CD 3.2 upgrade
How much does the Argo CD 3.1 to 3.2 upgrade cost?
The cost depends on the scope written for your environment, not on a published figure. No public price applies to Argo CD itself, since the Apache-2.0 licensed project has no paid edition. The cost is labor: your internal engineers' time, and any partner fees if you engage outside help. Cost rises with the number of Argo CD instances, applications using Source Hydrator, custom CronJob health rules, Kustomize or Helm plugins, and how much pre-production testing you require. Costs that recur are staff time for patch releases, since the project supports only the three most recent minor versions. Ask any partner for a fixed-scope quote that lists each breaking change in your estate, the testing environment, the rollback plan and the handover deliverables.
How long does an Argo CD 3.2 upgrade take?
Duration depends on how many instances you run and how many breaking changes they touch. A single instance with no Source Hydrator applications and no CronJob resources is far simpler than a fleet with many of each. The work includes reading the 3.1 to 3.2 upgrade notes, inventorying affected applications, testing on a non-production instance, scheduling a change window and checking health after cutover. The main delays come from finding applications whose health status changes, agreeing on a CronJob health approach with application owners, and getting change approval. Ask for a timeline in the written scope that separates inventory, testing and production cutover.
What does the upgrade need from our internal team?
The work needs people who know your Argo CD configuration and the applications it deploys. Typically that means a platform engineer who owns the Argo CD install, an application owner for each affected workload, and someone who can approve the change. Engineers must be able to read Application manifests, Kustomize files and the repo-server settings in use. Plan time for application owners to confirm which CronJobs should keep their current health behavior and which should be ignored, and for security or change managers to review evidence. Ask your partner or internal lead to list these roles in the scope so no step depends on one person.
Can our in-house team upgrade Argo CD 3.1 to 3.2 alone?
Yes, many teams can, provided they have a working non-production copy and engineers who understand the affected settings. The upgrade notes are specific: Source Hydrator paths must be non-root, stale root-level output is not cleaned up automatically, CronJob health can change application status, and the Kustomize version in .argocd-source.yaml and deprecated repo-server gRPC fields need review. An in-house team should check each of these against its own repositories before touching production. If no one has run Argo CD upgrades before, or the fleet is large, a partner can share the work, but the internal team still needs to own the decisions.
Should a partner handle only the breaking-change fixes?
A partner can be scoped to remediate only the breaking changes, leaving the version bump and routine operations with your team. This suits teams that have upgrade experience but lack time to audit Source Hydrator paths, CronJob health and deprecated settings across many repositories. The written scope should name each breaking change, the repositories and applications in view, the fix to be applied, who approves it and how it is tested. Confirm who owns rollback if a fix causes a regression, and whether the partner's work is delivered as version-controlled changes your team can review.
What should we confirm with the vendor and the upgrade notes?
Confirm the details against the official 3.1 to 3.2 upgrade notes and the release notes for the exact patch level you will run, since patch releases change. Check whether each Source Hydrator application already uses a non-root path, and whether old root-level output must be removed by hand. Confirm the exact configuration keys for CronJob health, including resource.customizations.health.batch_CronJob and the argocd.argoproj.io/ignore-healthcheck annotation, and how your Kustomize version is pinned. Verify the deprecated repo-server gRPC fields you use. Ask your team to record each answer in the change ticket before cutover.
How does the 3.1 to 3.2 step relate to later upgrades?
The 3.1 to 3.2 step is one minor-version move in a series. The project releases a minor version four times a year and supports only the three most recent minor versions with patch releases, so staying on 3.1 means falling behind on fixes. Each later step, such as the 3.2 to 3.3 move, has its own upgrade notes, and changes made now, like pinning Kustomize or moving Source Hydrator paths, affect what the next upgrade must handle. Ask for the plan to cover the path to the current supported line, not only this step, and confirm the target version before scheduling work.
How DeployOpen scopes and delivers the Argo CD 3.2 upgrade
DeployOpen plans the Argo CD 3.1 to 3.2 upgrade as a fixed-scope piece of work inside your own infrastructure. We start from your Source Hydrator applications, health checks and Kustomize usage, then test each change on a non-production instance before any cutover.
How we scope
- Inventory every Source Hydrator application and confirm which ones need a non-root path before 3.2.
- Identify CronJob resources whose health status may change, and agree whether to customize health or annotate them.
- Record Kustomize versions used in .argocd-source.yaml files and repo-server settings that touch deprecated gRPC fields.
- Agree the written scope, deliverables and timeline with you before any work starts.
How we build
- Move Source Hydrator output to non-root paths and plan removal of stale root-level output from earlier versions.
- Apply the CronJob health customization or ignore-healthcheck annotation chosen for each affected application.
- Test the upgrade on a non-production instance and compare application health and sync status before and after.
- Document each configuration change so reviewers can trace it back to the upgrade notes.
How we hand over
- Deliver a written change record listing every modified application, manifest and configuration key.
- Provide a rollback procedure and backup checkpoints agreed with your operations team before cutover.
- Walk your platform engineers through the verification checks they will repeat on future minor upgrades.
- Confirm with you which open items remain, such as Kustomize version alignment across repositories.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Use the retainer to plan the next minor release, which the Argo CD project ships four times a year.
- Ask for a quote based on the written scope, since DeployOpen does not publish a price list.
- Confirm patch-release coverage for your running minor version with the project's current release policy.
