Upgrade

1. Overview

This page documents the in-place upgrade procedure for ArgoCD. The upgrade is performed on the current rancher-idealogic cluster using Helm.

2. Upgrade History

Date From To Notes

2026-02-23

v2.9.5 (chart 5.53.8)

v3.3.2 (chart 9.4.4)

3-step upgrade: v2.14.11 → v3.0.12 → v3.3.2. Fixed valuesObject refresh loop bug. Migrated from Rancher marketplace to direct Helm management.

2024-02-28

Unknown

v2.9.5 (chart 5.53.8)

Installed via Rancher marketplace.

3. Pre-Upgrade Steps

3.1. 1. Check Current Version

helm list -n argocd
kubectl get pods -n argocd -o jsonpath='{.items[0].spec.containers[0].image}'

3.2. 2. Check Available Versions

helm repo update argo
helm search repo argo/argo-cd --versions | head -20

3.3. 3. Review Breaking Changes

Before upgrading, review the upgrade notes for each version you are crossing:

3.4. 4. Back Up Current State

mkdir -p .argocd-backup

# Back up application definitions
kubectl get applications -n argocd -o yaml > .argocd-backup/applications.yaml
kubectl get appprojects -n argocd -o yaml > .argocd-backup/appprojects.yaml

# Back up configuration
kubectl get configmap argocd-cm -n argocd -o yaml > .argocd-backup/argocd-cm.yaml
kubectl get configmap argocd-rbac-cm -n argocd -o yaml > .argocd-backup/argocd-rbac-cm.yaml
kubectl get secret argocd-secret -n argocd -o yaml > .argocd-backup/argocd-secret.yaml

# Back up Helm values
helm get values idealogic -n argocd -o yaml > .argocd-backup/helm-values.yaml

4. Upgrade Procedure

4.1. Step-by-Step for Each Version Hop

For each target version, repeat this sequence:

4.1.1. Apply CRDs First

Helm does not upgrade CRDs automatically. Apply them before each Helm upgrade:

kubectl apply -k "https://github.com/argoproj/argo-cd/manifests/crds?ref=<target-version>" \
  --server-side --force-conflicts

4.1.2. Helm Upgrade

helm upgrade idealogic argo/argo-cd \
  --version <chart-version> \
  -n argocd \
  -f argocd-values.yaml \
  --wait --timeout 5m

4.1.3. Verify

# Check pods are running with correct version
kubectl get pods -n argocd -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[0].image}{"\n"}{end}'

# Check application statuses
kubectl get applications -n argocd

4.2. Recommended Version Hops

When upgrading across multiple minor versions, use these milestone versions:

App Version Chart Version Notes

v2.14.11

7.9.1

Last v2.x release

v3.0.12

8.2.7

First v3.x (major RBAC changes)

v3.3.2

9.4.4

Latest stable (as of Feb 2026)

For example, upgrading from v2.9 to v3.3:

# Step 1: v2.9 -> v2.14
kubectl apply -k "https://github.com/argoproj/argo-cd/manifests/crds?ref=v2.14.11" \
  --server-side --force-conflicts
helm upgrade idealogic argo/argo-cd --version 7.9.1 -n argocd \
  -f argocd-values.yaml --wait --timeout 5m

# Step 2: v2.14 -> v3.0
kubectl apply -k "https://github.com/argoproj/argo-cd/manifests/crds?ref=v3.0.12" \
  --server-side --force-conflicts
helm upgrade idealogic argo/argo-cd --version 8.2.7 -n argocd \
  -f argocd-values.yaml --wait --timeout 5m

# Step 3: v3.0 -> v3.3
kubectl apply -k "https://github.com/argoproj/argo-cd/manifests/crds?ref=v3.3.2" \
  --server-side --force-conflicts
helm upgrade idealogic argo/argo-cd --version 9.4.4 -n argocd \
  -f argocd-values.yaml --wait --timeout 5m

5. Key Breaking Changes Reference

5.1. v2.x to v3.0

  • Fine-grained RBAC: update and delete policies no longer apply to sub-resources automatically. Add explicit update/ and delete/ if needed.

  • Logs RBAC enforcement: Enabled by default. Add explicit logs, get policies to custom RBAC.

  • Annotation-based resource tracking: Default changed from label-based to annotation-based.

  • Deprecated metrics removed: argocd_app_sync_status, argocd_app_health_status, argocd_app_created_time replaced by argocd_app_info.

  • Legacy repository config: Repository configuration in argocd-cm ConfigMap no longer supported. Use Secrets-based config.

  • Helm upgraded to v3.17.1: Rejects null values in values.yaml.

5.2. v3.2 to v3.3

  • Server-Side Apply required: ApplicationSet CRD exceeds annotation size limits. Use --server-side --force-conflicts when applying CRDs.

  • Source Hydrator: Uses git notes instead of commits.

6. Post-Upgrade Verification

After completing all upgrade steps:

# 1. Verify all pods running correct version
kubectl get pods -n argocd -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[0].image}{"\n"}{end}'

# 2. Verify Helm release
helm list -n argocd

# 3. Check all applications
kubectl get applications -n argocd

# 4. Check controller logs for errors
kubectl logs -n argocd statefulset/idealogic-argocd-application-controller --tail=100

# 5. Verify UI is accessible
curl -sI https://argocd.idealogic.co.za | head -5

# 6. Verify OIDC login works (manual step)

7. Rollback

If an upgrade fails, use Helm rollback:

# Check upgrade history
helm history idealogic -n argocd

# Rollback to previous revision
helm rollback idealogic <revision-number> -n argocd
CRD changes are NOT rolled back by Helm. CRDs are generally forward-compatible, so this is usually not an issue.

8. Support Matrix

ArgoCD supports only the three most recent minor versions. Check endoflife.date/argo-cd for current support status.

A minor release occurs every three months, with patch releases as needed for supported versions.