Originally published on kuryzhev.cloud
The Argo CD 3.6 upgrade lands on your desk the same week the release notes do. A Slack message says "3.6 is out, can we bump it?" Meanwhile, the production instance is deploying a few hundred Applications to a dozen clusters. Argo CD 3.6 was released in November 2026 (the cycle shipped 2026-11-04, and 3.6.1 is the current patch); see the official releases page. It matters now because the control plane that deploys everything else is the one component you cannot afford to upgrade casually, and a patch-level release is already out.
Short answer: do not jump to the first patch blindly. First, read the 3.5-to-3.6 section of the upgrade guide. Then back up the Argo CD state and upgrade a staging instance with auto-sync paused. Finally, promote the same pinned manifests to production.
This applies to anyone running 3.5 or earlier. If you are on an older 3.x, read every intermediate upgrade page, not just the last one. Follow whatever the docs say about skipping minor versions.
What changed and who is affected
This article deliberately does not reproduce a list of 3.6 breaking changes from memory. The authoritative list lives in the operator manual under "Upgrading" (Argo CD upgrade overview), with one page per minor version. Read the 3.5 to 3.6 page and the GitHub release notes for 3.6.0 and 3.6.1 before anything else.
Argo CD minor upgrades typically touch the same few areas, so scan the notes for these:
- Default behavior changes in diffing, resource tracking, or health checks. These change what "Synced" and "Healthy" mean for existing Applications without any Git change.
-
Removed or renamed config keys in
argocd-cm,argocd-cmd-params-cmandargocd-rbac-cm. - CRD changes to Application, AppProject and ApplicationSet.
- Sidecar plugins, custom health scripts and notification templates that depend on internals.
- Kubernetes compatibility: if you also run Kubernetes 1.37, check the supported-version statement in the docs rather than assuming.
You are most affected if you use any of the following:
- ApplicationSets with generators
- Config management plugins
- Custom Lua health checks
- SSO with RBAC policies
- Helm-managed Argo CD with heavily overridden values
A vanilla install with plain Git-to-cluster Applications has the smallest exposure.
Before/after config
The safest change is a single pinned version bump, with all your local patches kept in the same overlay. If you install with Kustomize, the file should change like this. Verify the tag exists, and compare against the upstream manifest for your install mode.
# argocd/kustomization.yaml (BEFORE)
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: argocd
resources:
- https://raw.githubusercontent.com/argoproj/argo-cd/v3.5.x/manifests/install.yaml # replace x with your exact current patch
- appproject-defaults.yaml
patches:
- path: patch-cmd-params.yaml
# argocd/kustomization.yaml (AFTER) - only the tag changes
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: argocd
resources:
- https://raw.githubusercontent.com/argoproj/argo-cd/v3.6.1/manifests/install.yaml # pin the patch, never "stable" or "latest"
- appproject-defaults.yaml
patches:
- path: patch-cmd-params.yaml
If you use the Helm chart from argo-helm, the chart version is not the same number as the Argo CD version. Check the chart's changelog for which chart release ships Argo CD 3.6.1. Then diff the rendered output with helm template before applying.
Watch out for floating references. A manifest URL pointing at stable means your next reconcile of the Argo CD Application itself can upgrade you without a review.
Step-by-step migration
Run this on staging first. The commands assume the argocd namespace and a logged-in argocd CLI.
Upgrade your local argocd CLI to the target 3.6.1 release before step 3. The validation step should check your config with the new version's rules, and a mismatched client can also produce confusing diffs.
# 1. Record the current state
argocd version # note client AND server versions
argocd app list -o name | wc -l # number of Applications
argocd app list -o json > apps-before.json # baseline of sync/health status
# 2. Back up Argo CD configuration and resources
argocd admin export -n argocd > argocd-backup-$(date +%F).yaml
# store it somewhere that is NOT the cluster being upgraded
# 3. Validate your config with the upgraded (3.6.1) CLI before applying
argocd admin settings validate --argocd-cm-path ./argocd-cm.yaml
# 4. Apply with server-side apply (CRDs are large; client-side apply can exceed annotation limits)
kubectl apply -n argocd --server-side --force-conflicts -k argocd/
# 5. Wait for every component
kubectl -n argocd rollout status deploy/argocd-server
kubectl -n argocd rollout status deploy/argocd-repo-server
kubectl -n argocd rollout status deploy/argocd-applicationset-controller
kubectl -n argocd rollout status sts/argocd-application-controller
Before step 4, pause automated sync on anything sensitive. There are two common approaches:
- Disable
syncPolicy.automatedon production Applications through Git. - Schedule the upgrade in a window where nobody is merging.
Only promote to production after staging has run a full reconcile cycle with no unexpected out-of-sync Applications. Repeat the same steps there with the same pinned manifests. For related tooling choices, see the other runbooks on kuryzhev.cloud.
Verify and roll back
Verification should compare against the baseline you saved, not against your intuition. Healthy looks like this:
- The same Application count
- The same sync and health distribution
- No growth in errors
argocd version | grep -i server # expect the 3.6.x version you pinned
argocd app list -o json > apps-after.json
diff <(jq -r '.[] | [.metadata.name,.status.sync.status,.status.health.status] | @tsv' apps-before.json | sort) \
<(jq -r '.[] | [.metadata.name,.status.sync.status,.status.health.status] | @tsv' apps-after.json | sort)
# an empty diff is the goal; every changed line needs an explanation
kubectl -n argocd logs deploy/argocd-repo-server --since=15m | grep -i -E 'error|panic' | head
kubectl -n argocd logs sts/argocd-application-controller --since=15m | grep -i -E 'error|panic' | head
If you scrape Argo CD metrics with Prometheus, watch argocd_app_info grouped by sync_status and health_status before and after. Alert on a rising count of OutOfSync or Degraded. Check the metric and label names against your running version at /metrics.
Rollback is not just re-applying the old tag. If the new version changed CRD schemas or stored data, a downgrade may not be supported. Confirm what the 3.6 upgrade notes say about downgrades before you rely on one.
Practical rollback order:
- Stop auto-sync.
- Re-apply the previous pinned manifests.
- If components crash or state looks wrong, reinstall the previous pinned version. Then restore the backup into the same namespace with
argocd admin import -n argocd - < argocd-backup-YYYY-MM-DD.yaml.
Argo CD sits outside your workloads' runtime path. A failed control-plane upgrade therefore usually does not take down running workloads; it stops reconciliation and deployments. That is the real blast radius.
Gotchas after the switch
-
Surprise OutOfSync after upgrade. If diffing or normalization behavior changed, Applications may show drift with no Git change. Do not mass-sync. Inspect with
argocd app diff <name>. Add a scopedignoreDifferencesentry only when the diff is a known false positive. -
Self-heal can act on that drift. Apps with
selfHeal: truewill rewrite live resources as soon as the controller comes up. This is why pausing automation before the upgrade matters. -
Custom health checks and plugins. Lua health scripts in
argocd-cmand sidecar plugins are the usual silent breakers. Test one Application per plugin type. -
ApplicationSet fan-out. A generator behavior change can create or prune many Applications at once. Before upgrading, check that
preserveResourcesOnDeletionand your sync policy are what you intend. - SSO and RBAC. Log in through your identity provider after the upgrade. Test a non-admin role, not just the admin account.
- Do not stay on 3.6.0. The cycle already has 3.6.1; take the latest patch of the minor you choose.
There are three good reasons not to upgrade right away:
- You are mid-migration of clusters or repositories.
- You have no staging Argo CD.
- Your plugins are unmaintained.
A one-minor delay usually costs little, while a broken control plane during an incident costs a lot. Keep the pinned version, the backup, and the baseline JSON together in the change ticket, so the next upgrade starts from a known state.
Always cross-check this runbook with the official Argo CD documentation, since version-specific details change between releases.
Top comments (0)