How to plan an Argo CD 3.2 to 3.3 upgrade without interrupting deployments
If your Argo CD 3.2 instance deploys production workloads, plan the move to 3.3 as a single minor-version step, test it on a non-production instance first, and schedule the cutover around the changes that touch how manifests are applied and how the API answers anonymous callers. The supported path is minor by minor, so there is no skipping from 3.2 directly to a later line. The project's release process ships a minor release four times a year and patches only the three most recent minor versions, so staying on 3.2 means it will eventually fall out of patch support. Read the current patch list on the Argo CD releases page before you pick a window, and do not let the move drift until 3.2 is no longer patched.
The 3.3 changes are mostly about mechanics, not a rewrite of your Git flow or your applications. The one that can block a rollout is the ApplicationSet CRD, which exceeds the client-side apply annotation limit in 3.3, so the upgrade has to use server-side apply with --force-conflicts. If Argo CD manages itself, set ServerSideApply=true in its own sync options before the new version reaches the cluster. Helm-managed installs are not affected by that step. Confirm how your instance was installed, because that single fact determines which of these checks apply to you.
Before the window, back up the Argo CD resources and export the current state of every Application and ApplicationSet, then record which teams depend on anonymous access to the API, since 3.3 stops returning resourceOverrides to anonymous callers. Also list any automation that uses the deprecated --self-heal-backoff-cooldown-seconds flag. Use the 3.2 to 3.3 upgrade notes as the checklist, and confirm each item in your own environment rather than assuming the default behavior matches your cluster.
Which 3.3 changes affect your installation and what to do about each
This table lists the four Argo CD 3.3 changes that touch upgrades, with the installation type each one affects and the action to take before cutover. Read each row against how you installed Argo CD, then confirm the exact behavior in the 3.2 to 3.3 upgrade notes before you change anything.
| Change in 3.3 | Who it affects | Action needed |
|---|---|---|
| ApplicationSet CRD exceeds the client-side apply annotation limit | Self-managed Argo CD and manifest installs. Helm upgrades are not affected. | Apply the ApplicationSet CRD with kubectl apply --server-side --force-conflicts and set ServerSideApply=true for self-managed deployments. Confirm the exact steps in the notes. |
| Source Hydrator commits only when manifest files change | Teams using the Source Hydrator to write rendered manifests to Git. | Expect a git note instead of a commit when nothing changed. Update any tooling that expects a commit on every hydration run. |
| Source Hydrator no longer cleans application paths before writing | Teams whose hydrated paths hold files Argo CD did not write. | Check target paths for stale files that were previously removed on write. Remove or move them deliberately before the first hydration on 3.3. |
| Anonymous callers no longer receive resourceOverrides | Dashboards, scripts or external tools that read settings without logging in. | Find unauthenticated consumers of the settings endpoint. Move them to authenticated access or a token before cutover. |
| New ARGOCD_K8S_SERVER_SIDE_TIMEOUT variable | Installations with slow Kubernetes API responses or large resource sets. | Review whether the default timeout suits your clusters. Set the variable in the API server or repo-server config only if you need a different value. |
| Deprecated --self-heal-backoff-cooldown-seconds flag | Anyone who passes this flag in manifests, Helm values or startup scripts. | Search your configs for the flag and plan its removal. Confirm the replacement setting in the 3.2 to 3.3 notes. |
What to back up and inventory before touching the ApplicationSet CRD
The 3.3 upgrade changes how the ApplicationSet CRD is applied, and it changes how Source Hydrator and anonymous API callers behave. Each card below covers one thing to capture or review before the first apply, so that a rollback or a surprise in the new version has something concrete to fall back on.
Back up core Argo CD objects
Export the Application, AppProject, ApplicationSet and Secret objects from the Argo CD namespace before changing anything. Repository credentials, cluster secrets and SSO settings live in Kubernetes objects, so a dated export of each kind is your restore point if the new controller misbehaves. Store the export outside the cluster and confirm you can read it back. Ask your team which backup tool or procedure is the approved one for this environment.
List self-managed sync options
If Argo CD deploys its own manifests from Git, find the Application that manages it and record its syncOptions. The 3.3 notes require ServerSideApply=true for self-managed installs, so you need to know whether that option already exists. Also note any prune or selfHeal settings, because a sync during the upgrade could remove or revert resources you did not intend to change.
Find Kustomize bases pinning the version
Search your repositories for Kustomize bases, overlays and pinned image tags that reference the current Argo CD release. Each pin is a place where a version bump can drift from the Helm or manifest source of truth. Record the path, the pinned version and the owning team, so the change lands in one commit instead of being discovered during a failed sync.
Inventory Source Hydrator repositories
List every Application that uses the Source Hydrator, along with its repository, target branch and paths. From 3.3 the hydrator commits only when manifest files change and otherwise updates a git note, and it no longer cleans application paths before writing. Note which paths may hold stale files that the new behavior will leave in place, and confirm who reads those git notes downstream.
Review scripts that call anonymous settings
Search dashboards, CI jobs, monitoring checks and internal portals for calls to the settings API made without a token. In 3.3 anonymous callers no longer receive resourceOverrides, so any tool that reads them will see a change. Identify each caller, decide whether it should authenticate, and update the ones that depend on those fields before the upgrade reaches production.
Build a non-production copy
Create a non-production Argo CD instance seeded with a copy of production configuration, repositories, projects and sample Applications. Run the ApplicationSet CRD apply, a self-managed sync and a Source Hydrator run there first. Record what changed and what failed, and keep the test instance separate from production clusters so test syncs cannot touch live workloads.
Upgrade steps, checks and rollback points for 3.2 to 3.3
This sequence moves an Argo CD 3.2 installation to 3.3 in an order that protects reconciliation, with a check and a rollback point at each stage so the team knows when it can move on.
Freeze changes and confirm backups
Pause manual edits to Argo CD objects and announce a change window to the teams that own applications. Export the Application, AppProject and ApplicationSet objects, the argocd-cm, argocd-rbac-cm and argocd-cmd-params-cm ConfigMaps, and the repository and cluster Secrets, then store the export outside the cluster. Confirm you can restore from it. Done when the export is complete, stored off-cluster, and a second engineer has checked it. Rollback point: this export is the baseline you restore from if later steps fail.
Upgrade the non-production instance first
Run the 3.3 upgrade on a non-production Argo CD that manages representative applications, ApplicationSets and Source Hydrator sources. Read the 3.2 to 3.3 upgrade notes against your own configuration before changing anything. Done when the non-production instance reconciles its applications with no unexpected OutOfSync or Degraded states. Rollback point: production is untouched, so a failed rehearsal costs only the time spent on it.
Apply the ApplicationSet CRD with server-side apply
Because the ApplicationSet CRD exceeds the client-side apply annotation limit in 3.3, apply the CRD with kubectl apply --server-side --force-conflicts before rolling out the new controller. Helm-managed installs are not affected by this change. Self-managed installs that deploy their own manifests from Git need ServerSideApply=true in their sync options instead. Done when kubectl reports the CRD as configured and the ApplicationSet resources are still listed. Rollback point: the previous CRD version is recorded in the exported baseline, so you can reapply it if the new controller cannot start.
Roll the controller, API server and repo-server
Update the application controller, API server and repo-server to 3.3 in the same change, following the manifests or chart version you use. Watch the rollout until each deployment reports its pods ready, and check the controller logs for startup errors. If you run HA manifests, check replica counts and node anti-affinity afterward. Done when all three components are running 3.3, reconciliation resumes, and a test application syncs successfully. Rollback point: reapply the 3.2 manifests and the baseline CRD, then confirm the test application syncs again.
Verify Source Hydrator behavior
From 3.3, the Source Hydrator commits only when manifest files change, updates a git note otherwise, and no longer cleans application paths before writing. Review a hydrated source in the non-production instance and in production, and confirm that unchanged manifests produce notes rather than new commits. Check any downstream tooling, such as pipelines or branch protection rules, that expected a commit on every hydration. Done when hydrated output matches what you expect and no stale files remain in application paths. Rollback point: the 3.2 controller can be restored from the baseline if hydration output diverges.
Check anonymous API responses
Argo CD 3.3 stops returning resourceOverrides to anonymous callers. Identify any dashboards, scripts or external services that call the API without authentication and read this field. Then authenticate those callers or move them to a token that has the needed permission. Done when those callers return the data they need under an authenticated request, and no anonymous request returns resourceOverrides. Rollback point: this is a read-path change, so reverting the controller to 3.2 restores the earlier behavior if an unidentified consumer breaks.
Set the new timeout and retire the self-heal cooldown flag
Set ARGOCD_K8S_SERVER_SIDE_TIMEOUT to a value that suits your largest server-side apply operations, and remove --self-heal-backoff-cooldown-seconds from your startup arguments because it is deprecated in 3.3. Confirm the chosen timeout value against your own cluster sizes before rollout, since the upgrade notes do not set a default for you to copy. Done when the controller starts without warnings about the deprecated flag and a large sync completes within the timeout. Rollback point: both settings are environment and argument changes, so you can revert them without rolling back the binary.
Confirm the upgrade and record the result
Check that all applications reconcile, that RBAC still grants the access your teams need, and that the Argo CD version reported by the API matches 3.3. Record the final manifests, CRD version and settings in your change record. Keep the 3.2 baseline until your normal review period ends. Done when the change record shows the verified state and the owners of each application have confirmed their workloads are healthy. Rollback point: the baseline export and 3.2 manifests stay available until you close the change.
What changes in Source Hydrator commits and anonymous API responses
In Argo CD 3.3, the Source Hydrator changes how it records a run whose rendered manifests have not changed. Instead of creating a commit, it updates a git note attached to the existing commit. Only runs that change manifest files still produce a commit. For engineers, this means git log on the hydrated branch shows fewer entries than before, and the record of 'nothing changed on this run' lives somewhere most tools do not display by default. Audit reviewers who build evidence from commit history should confirm whether their tooling reads git notes, and whether their change records depend on seeing one commit per sync. Confirm the exact behavior against the 3.2 to 3.3 upgrade notes before you change any pipeline that parses hydrated branch history.
The Source Hydrator also no longer cleans application paths before it writes. Before 3.3, each hydration cleared the target path first, so files removed from the source were removed from the hydrated output. Without that cleanup, a deleted template or renamed manifest can leave a stale file in the application path, and that file keeps being applied. Before cutting over, compare the hydrated output for a few applications against the source, look for leftover files, and decide whether to remove them manually or add a pipeline step that clears the path. Treat this as a check to run on a staging instance, not an assumption to make in production.
Anonymous callers can no longer read resourceOverrides from the API in 3.3. Any dashboard, script or status page that fetched these settings without a token will receive less data after the upgrade. Find these callers by reviewing access logs or proxy records for unauthenticated requests to the settings endpoints during a normal week, then give each one a dedicated service account with the minimum read permission it needs. Confirm the exact list of fields that stop being returned in the 3.2 to 3.3 upgrade notes, because the set of anonymous fields may differ from what your scripts use.
What makes a 3.2 to 3.3 upgrade longer or riskier
The 3.2 to 3.3 change set is small on paper, but the time it takes depends on how Argo CD is installed and how much it manages. The cards below cover the factors that most often stretch the work or add risk before cutover.
Number of instances and clusters
Each Argo CD instance needs its own upgrade, verification and rollback plan, and each one that manages several clusters carries more sync activity to watch afterward. Count instances, the clusters each one reconciles, and whether any run in separate network zones. Multiply the test effort by the number of distinct installation patterns, not by the number of instances.
Installation method
Self-managed installs need a different sequence. An instance that deploys its own manifests from Git needs ServerSideApply=true set before the new manifests sync, while Helm upgrades are not affected by the ApplicationSet change. Identify which path each instance uses, and read the matching upgrade guide before changing anything.
ApplicationSet size and count
The ApplicationSet CRD now exceeds the client-side apply annotation limit, so the upgrade command must be kubectl apply --server-side --force-conflicts. Larger and more numerous ApplicationSets make that step slower to review and easier to get wrong. List every ApplicationSet CRD manifest in use and confirm who owns the apply command in each pipeline.
Source Hydrator usage
Teams using the Source Hydrator change how their rendered Git history looks. From 3.3 the hydrator commits only when manifest files change, updates a git note otherwise, and no longer cleans application paths before writing. Any tooling that reads hydrated branches, expects a commit per sync, or relies on the old path cleanup needs a review before the upgrade.
Custom plugins and scripts
Scripts that call Argo CD without credentials may break because 3.3 stops returning resourceOverrides to anonymous callers. Review internal dashboards, status checks and CI jobs that read settings unauthenticated, and move them to authenticated tokens. Also check any scripts that depend on the deprecated --self-heal-backoff-cooldown-seconds flag, which still works but should be replaced.
Test environment and approvals
A test instance that mirrors production's ApplicationSets, plugins and cluster count gives the most useful signal, while a small lab mostly confirms that the pods start. Change control may also require a documented rollback path and sign-off from more than one team. Ask your change board early which evidence it expects, because approval time is often the longest part of the schedule.
Questions teams ask before upgrading Argo CD 3.2 to 3.3
Does upgrading Argo CD 3.2 to 3.3 cost anything from the project?
No license fee applies from the project itself. Argo CD is released under the Apache License 2.0 (SPDX: Apache-2.0), and the project does not offer a paid edition. Your costs come from the work around the upgrade: staff time to read the upgrade notes, review your manifests and sources, back up state, run a test instance and schedule the cutover. Cluster capacity for a temporary second instance or extra test clusters may also add cost, depending on how you run it. Confirm with your procurement team whether any commercial support contract you hold for your Kubernetes platform or Git host changes as part of the rollout.
How long does an Argo CD 3.2 to 3.3 upgrade take?
Duration depends mostly on how Argo CD is installed and how many things the upgrade touches. A standalone install with few applications and no Source Hydrator use is a small change. The main drivers are whether you use the Source Hydrator, whether you set ARGOCD_K8S_SERVER_SIDE_TIMEOUT or the deprecated self-heal cooldown flag, how many clusters and ApplicationSets you run, whether Argo CD manages its own manifests, and how much testing your change process requires. No duration figure is supplied for this upgrade, so ask any partner or your own team for a plan that lists each step and its exit check before agreeing a schedule.
Do Helm users need the server-side apply step for Argo CD 3.3?
No. The server-side apply requirement applies to manifest-based installs. In 3.3 the ApplicationSet CRD exceeds the client-side apply annotation limit, so the upgrade must use kubectl apply --server-side --force-conflicts, and self-managed Argo CD needs ServerSideApply=true. Helm upgrades are not affected by this change according to the upgrade notes. You should still read the Helm chart's own release notes, check how the chart version maps to the Argo CD version, and confirm CRD handling in your chart values before you upgrade.
What does the upgrade need from our internal team?
Your team needs people who own the Argo CD configuration, the Git repositories it reads, the target clusters and the change approval process. The engineers who run the upgrade should be able to inspect Application and ApplicationSet resources, check Source Hydrator paths and git notes, and roll back to a saved backup. Someone must also decide who approves the change and what evidence is kept. Plan time for each cluster owner to confirm that their workloads do not depend on the anonymous settings calls or the timeout behavior that changes in this release.
Do we need a partner to upgrade Argo CD 3.2 to 3.3?
Not necessarily. Teams with experienced Kubernetes and GitOps staff, a non-production Argo CD instance and a tested backup routine can often complete the upgrade alone. A partner is more useful when the team lacks capacity, runs many clusters or ApplicationSets, operates a self-managed Argo CD instance, or needs evidence for an audit. Decide based on the skills in your team and the risk of a failed cutover. Ask any provider to name the people who will do the work and how they will hand it back to your staff.
What does a fixed-scope quote for this upgrade cover?
Most DeployOpen engagements are fixed-scope, so the quote follows a written scope agreed before work starts. For an upgrade like this, the scope should list the Argo CD installs in scope, the upgrade notes reviewed, the checks run against your Applications, ApplicationSets and Source Hydrator usage, the test instance, the backup and rollback steps, the cutover window, the deliverables such as a change record and runbook, and what is excluded. Ask for each item to be priced separately so you can see which parts you may choose to keep in-house. DeployOpen does not publish a price list.
How DeployOpen scopes, delivers and supports an Argo CD 3.2 to 3.3 upgrade
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, so the Argo CD 3.2 to 3.3 upgrade is handled as a written, fixed-scope change in your environment. The work starts with an inventory of how your instance is installed and what it manages, then moves through a tested rehearsal to a documented cutover.
How we scope
- Confirm whether Argo CD runs from plain manifests, Kustomize, the community Helm chart or a self-managed Git source, since that decides the apply method.
- Inventory the ApplicationSets, Source Hydrator usage, anonymous API consumers and any scripts that read resourceOverrides or the self-heal backoff flag.
- Record the agreed scope, deliverables and timelines in writing before work starts, including what is out of scope such as unrelated minor versions.
How we build
- Back up Argo CD resources and the ApplicationSet CRD state, then rehearse the upgrade on a non-production instance that mirrors your configuration.
- Apply the ApplicationSet CRD with server-side apply and force conflicts, and set ServerSideApply=true where Argo CD manages itself.
- Review Source Hydrator paths and git note behavior, and set ARGOCD_K8S_SERVER_SIDE_TIMEOUT and self-heal flags to values your teams have agreed.
How we hand over
- Deliver a runbook covering the apply sequence, rollback steps, verification commands and the owners for each cutover action.
- Document every configuration change made for 3.3, including deprecated flags and the changed anonymous settings call behavior.
- Walk your platform and security engineers through the rehearsal results and the post-upgrade checks before the production window.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer if your team wants DeployOpen to keep the instance current.
- Plan the next upgrade against the Argo CD patch and minor release cadence, confirming which versions are receiving patches at the time.
- Confirm with your team the support window, escalation contacts and change approval steps you need before engaging a retainer.
