Argo CD 3.5 upgrade guide targets shared clusters under audit pressure

A guide published on dev.to by Oleksandr Kuryzhev sets out how operations teams should move shared-cluster Argo CD installations to version 3.5, and its central claim is that the move warrants a rehearsed rollout rather than a version bump in a manifest.

The scenario is familiar: a platform team on Argo CD 3.2 or 3.3 in a shared cluster with a few hundred Applications, and a ticket demanding 3.5 before the next audit. According to the article, Argo CD 3.5 shipped in August 2026 and patch releases have followed up to 3.5.6, while the upstream support policy covers only the newest minor lines, so the gap to cross grows the longer a team waits. The author frames the piece as a process guide rather than a changelog reproduction, pointing to the operator manual's upgrading section and the release notes as the authoritative record of behavior changes.

Preparation before anything moves

Prerequisites start with Kubernetes permissions: admin rights in the Argo CD namespace plus cluster-scoped rights to apply CRDs and cluster roles. The argocd CLI must match the target server, since a client several minors behind can behave oddly against a newer API server. Staging should carry a representative slice of Applications, ApplicationSets and the real argocd-cm and argocd-rbac-cm settings — a vanilla install reveals little, the author notes. Teams also need their install method written down, because raw manifests, Kustomize overlays and the community Helm chart pin versions differently, and a chart version is not the same number as the application version.

One external dependency gets special attention: ingress-nginx. The guide states the controller was retired in March 2026 and receives no further security fixes, so an Argo CD server sitting behind it should move to Gateway API or another maintained controller — as a separate change, since combining the two in one window makes any login or gRPC failure ambiguous to diagnose.

Snapshot first, then read every minor's notes

Step one captures a restorable backup and a baseline. The backup, produced with argocd admin export, holds Applications, AppProjects, settings and secrets, and should be stored encrypted because it can contain repository credentials and cluster secrets. The baseline is a listing of every Application's name, sync status and health, taken with argocd app list, for comparison after the upgrade. The guide also advises recording which Applications are already OutOfSync or Degraded, so pre-existing drift is not blamed on the new version.

Step two is reading: every upgrade note between the current minor and 3.5, in order, because skipped notes are where defaults change unnoticed. The author sorts items into breaking changes that need a config edit, changed defaults that alter runtime behavior, and deprecations with removal dates, then checks them against argocd-cm, argocd-cmd-params-cm, argocd-rbac-cm and any config management plugins.

Two areas get extra scrutiny. Changes to resource tracking or ignore-difference settings can flip hundreds of Applications to OutOfSync after an otherwise clean upgrade, so they should be tested with argocd app diff against real Applications on staging. And the Helm and Kustomize versions bundled in the repo-server image can change between minors, altering rendered output for the same chart.

Rehearse on staging, then promote

The rehearsal pins an exact patch release — v3.5.6 at the time of writing, never a moving tag — and applies the upstream manifest with server-side apply and --force-conflicts, the documented way to handle Argo CD's large CRDs without annotation-size errors. The manifest must match the topology: applying the standard install.yaml over an HA installation replaces the HA components. One documented gotcha with --force-conflicts is that the apply takes ownership of every field the upstream manifest sets, resetting hand edits made through kubectl edit or kubectl patch unless they live in an overlay.

Promotion to production belongs in a quiet window, away from a large release that is mid-sync. The application controller restarts and re-reconciles everything, and the resulting burst of repo-server and API-server load is, per the author, the dominant cost of the upgrade for large installs. Rollback is concrete — re-apply the previous pinned manifest, then restore from the export with argocd admin import if state looks damaged — but CRD schema changes are not always cleanly reversible, so the rehearsal, not the rollback, is what actually de-risks the move. Teams running many clusters from one instance are advised to upgrade a secondary instance first. Verification closes the loop: confirm the server version, regenerate the app listing and diff it against the baseline.

Why it matters

Argo CD's support policy and audit deadlines create real pressure to move, but shared clusters concentrate the risk: a single changed default in resource tracking can surface as mass OutOfSync status across hundreds of Applications and turn an upgrade into an incident. The guide's value is converting a version jump into a diffable, rehearsed procedure with a baseline to compare against, and its warnings — a retired ingress controller, CLI version mismatches, chart-versus-app version confusion, not-always-reversible CRD changes — name the specific failure modes that bite teams treating upgrades as routine. The official Argo CD upgrade documentation remains the source of truth for behavior changes; the dev.to piece supplies the process that makes those changes survivable.