> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading Argo CD

> Version upgrade procedures, breaking changes, and migration guides

This guide covers best practices for upgrading Argo CD between versions, including breaking changes and migration procedures.

## Versioning and Compatibility

Argo CD follows semantic versioning with these guarantees:

<CardGroup cols={3}>
  <Card title="Patch Releases" icon="bug">
    **v1.5.1 → v1.5.3**

    No breaking changes or special instructions required. Safe to upgrade directly.
  </Card>

  <Card title="Minor Releases" icon="arrow-up">
    **v1.3.0 → v1.5.2**

    May introduce changes with workarounds. Check upgrade notes for each minor version.
  </Card>

  <Card title="Major Releases" icon="triangle-exclamation">
    **v2.14 → v3.0**

    Introduces backward incompatible changes. Take backup and review migration guide carefully.
  </Card>
</CardGroup>

<Warning>
  For major version upgrades, it is strongly recommended to take a backup using the [disaster recovery guide](/operations/disaster-recovery) before upgrading.
</Warning>

## Standard Upgrade Procedure

### Pre-Upgrade Checklist

<Steps>
  <Step title="Review release notes">
    Check the release notes for breaking changes and new features:

    * [v3.3 to v3.4](https://argo-cd.readthedocs.io/en/stable/operator-manual/upgrading/3.3-3.4/)
    * [v3.0 to v3.1](https://argo-cd.readthedocs.io/en/stable/operator-manual/upgrading/3.0-3.1/)
    * [v2.14 to v3.0](https://argo-cd.readthedocs.io/en/stable/operator-manual/upgrading/2.14-3.0/)
  </Step>

  <Step title="Backup Argo CD data">
    Create a backup of all Argo CD resources:

    ```bash theme={null}
    export VERSION=$(argocd version | grep server | awk '{print $2}')
    docker run -v ~/.kube:/home/argocd/.kube --rm \
      quay.io/argoproj/argocd:$VERSION \
      argocd admin export > backup-$(date +%Y%m%d).yaml
    ```
  </Step>

  <Step title="Test in non-production">
    Always test upgrades in a development or staging environment first.
  </Step>

  <Step title="Check current version">
    ```bash theme={null}
    argocd version
    ```
  </Step>
</Steps>

### Upgrade Commands

<Tabs>
  <Tab title="Non-HA Installation">
    For standard installations:

    ```bash theme={null}
    kubectl apply -n argocd --server-side --force-conflicts \
      -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.4.0/manifests/install.yaml
    ```
  </Tab>

  <Tab title="HA Installation">
    For high availability installations:

    ```bash theme={null}
    kubectl apply -n argocd --server-side --force-conflicts \
      -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.4.0/manifests/ha/install.yaml
    ```
  </Tab>
</Tabs>

<Note>
  The `--server-side --force-conflicts` flags are required because some Argo CD CRDs exceed the size limit for client-side apply operations.
</Note>

<Warning>
  Even for patch releases that only require image changes, it is recommended to apply the complete manifest set. Manifest changes might include important parameter modifications.
</Warning>

### Post-Upgrade Verification

```bash theme={null}
# Verify version
argocd version

# Check pod status
kubectl get pods -n argocd

# Verify applications are healthy
argocd app list

# Check for any stuck applications
argocd app list --output json | jq '.[] | select(.status.health.status != "Healthy")'
```

## Major Version Upgrades

### Upgrading to v3.0

Argo CD 3.0 introduces several important changes. Below are the most impactful breaking changes:

<AccordionGroup>
  <Accordion title="Annotation-Based Tracking (Default)">
    **Change**: Default resource tracking changed from labels to annotations.

    **Detection**:

    ```bash theme={null}
    kubectl get cm argocd-cm -n argocd -o jsonpath='{.data.application\.resourceTrackingMethod}'
    # If empty or "label", you're using label-based tracking
    ```

    **Impact**: Labels will be replaced with annotations on next sync. Applications won't be marked as out-of-sync if labels are missing.

    **Action Required**:

    * Most users can upgrade safely
    * Applications with `ApplyOutOfSyncOnly=true` need manual sync after upgrade
    * Perform a sync operation on applications to apply annotations

    **Opt-out** (if needed):

    ```yaml theme={null}
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: argocd-cm
      namespace: argocd
    data:
      application.resourceTrackingMethod: label
    ```
  </Accordion>

  <Accordion title="Fine-Grained RBAC Changes">
    **Change**: Policies granting `update` or `delete` no longer automatically apply to sub-resources.

    **Impact**: Users with `applications, update` permission can no longer automatically update/delete managed resources.

    **Action Required**: Update RBAC policies to explicitly grant sub-resource permissions:

    ```yaml theme={null}
    # Old (v2.x) - implied sub-resource access
    p, role:developer, applications, update, myproject/*, allow

    # New (v3.0) - explicit sub-resource access required
    p, role:developer, applications, update, myproject/*, allow
    p, role:developer, applications, update/*, myproject/*, allow
    ```

    **Restore v2 behavior**:

    ```yaml theme={null}
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: argocd-cm
      namespace: argocd
    data:
      server.rbac.disableApplicationFineGrainedRBACInheritance: "false"
    ```
  </Accordion>

  <Accordion title="Logs RBAC Enforcement">
    **Change**: Logs RBAC is now enforced by default (previously optional).

    **Detection**:

    ```bash theme={null}
    # Check if already enforced
    kubectl get cm argocd-cm -n argocd -o jsonpath='{.data.server\.rbac\.log\.enforce\.enable}'
    ```

    **Impact**: Users need explicit `logs, get` permission to view pod logs in UI.

    **Quick fix** (global access):

    ```yaml theme={null}
    # In argocd-rbac-cm ConfigMap
    policy.csv: |
      p, role:readonly, logs, get, */*, allow
      g, <user>, role:readonly
    ```

    **Recommended fix** (per-policy):

    ```yaml theme={null}
    policy.csv: |
      p, role:developer, applications, get, myproject/*, allow
      p, role:developer, logs, get, myproject/*, allow
    ```
  </Accordion>

  <Accordion title="Default Resource Exclusions">
    **Change**: High-volume Kubernetes resources are now excluded by default.

    **Excluded resources**:

    * Kubernetes: `Endpoints`, `EndpointSlice`, `Lease`, `TokenReview`, `CertificateSigningRequest`
    * Cert Manager: `CertificateRequest`
    * Kyverno: `EphemeralReport`, `AdmissionReport`, `BackgroundScanReport`
    * Cilium: `CiliumIdentity`, `CiliumEndpoint`

    **Impact**: Reduces API load on large clusters, improves performance.

    **Override** (if needed):

    ```yaml theme={null}
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: argocd-cm
      namespace: argocd
    data:
      resource.exclusions: |
        # Override with your custom exclusions
        - apiGroups:
          - ""
          kinds:
          - Endpoints
          clusters:
          - "*"
    ```
  </Accordion>

  <Accordion title="Helm 3.17.1 Upgrade">
    **Change**: Helm upgraded to 3.17.1 with stricter `null` handling.

    **Issue**: `values.yaml` files with `null` object values will override subcharts.

    **Example problem**:

    ```yaml theme={null}
    # This will now override the subchart value
    postgresql:
      enabled: null  # ❌ Will cause issues
    ```

    **Solution**: Remove `null` values:

    ```yaml theme={null}
    # Comment out or remove instead
    postgresql:
      enabled: false  # ✅ Use explicit false
    ```
  </Accordion>

  <Accordion title="Dex SSO RBAC Changes">
    **Change**: RBAC subject now uses `federated_claims.user_id` instead of `sub` claim.

    **Detection**: If using Dex SSO, check existing RBAC policies.

    **Action Required**: Decode existing `sub` claims and update policies:

    ```bash theme={null}
    # Decode sub claim to get user_id
    echo "ChdleGFtcGxlQGFyZ29wcm9qLmlvEgJkZXhfY29ubl9pZA" | base64 -d
    # Output: example@argoproj.io
    ```

    Update RBAC policies:

    ```yaml theme={null}
    # Old (incorrect)
    - g, ChdleGFtcGxlQGFyZ29wcm9qLmlvEgJkZXhfY29ubl9pZA, role:admin

    # New (correct)
    - g, example@argoproj.io, role:admin
    ```
  </Accordion>
</AccordionGroup>

### Upgrading to v3.4

<AccordionGroup>
  <Accordion title="Application 'Missing' Health Status Change">
    **Change**: Applications now show `Missing` health only when ALL resources are missing.

    **New behavior**:

    * Individual missing resources don't affect overall health
    * Health reflects existing resources (Healthy, Progressing, Degraded)
    * Use `OutOfSync` status to detect missing resources

    **Impact**: Automation relying on `Missing` health status should check `OutOfSync` instead.

    ```bash theme={null}
    # Old way - check health for missing resources
    argocd app list --health-status Missing

    # New way - check sync status
    argocd app list --sync-status OutOfSync
    ```
  </Accordion>

  <Accordion title="gRPC DNS TXT Lookups Disabled">
    **Change**: gRPC service config DNS lookups disabled by default.

    **Reason**: Prevents excessive DNS queries in dual-stack (IPv4+IPv6) environments.

    **Impact**: Minimal for most users. Only affects those using DNS TXT records for gRPC config.

    **Re-enable** (if needed):

    ```yaml theme={null}
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: argocd-cmd-params-cm
      namespace: argocd
    data:
      controller.grpc.enable.txt.service.config: "true"
    ```
  </Accordion>

  <Accordion title="Dex 2.45.0 Upgrade">
    **Changes**:

    * Gomplate now used internally
    * `ContinueOnConnectorFailure` enabled by default

    **Disable if needed**:

    ```yaml theme={null}
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: argocd-cmd-params-cm
      namespace: argocd
    data:
      dexserver.connector.failure.continue: "false"
    ```
  </Accordion>
</AccordionGroup>

## Upgrade Strategies

### Rolling Upgrade (Zero Downtime)

For production environments:

<Steps>
  <Step title="Scale API server">
    Ensure multiple replicas before upgrade:

    ```bash theme={null}
    kubectl scale deployment argocd-server -n argocd --replicas=3
    ```
  </Step>

  <Step title="Apply manifests">
    ```bash theme={null}
    kubectl apply -n argocd --server-side --force-conflicts \
      -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.4.0/manifests/ha/install.yaml
    ```
  </Step>

  <Step title="Monitor rollout">
    ```bash theme={null}
    kubectl rollout status deployment argocd-server -n argocd
    kubectl rollout status deployment argocd-repo-server -n argocd
    kubectl rollout status statefulset argocd-application-controller -n argocd
    ```
  </Step>
</Steps>

### Blue-Green Upgrade

For critical environments:

1. **Deploy new Argo CD instance**: Install new version in parallel namespace
2. **Import configuration**: Restore from backup to new instance
3. **Validate functionality**: Test applications in new instance
4. **Switch traffic**: Update ingress/LoadBalancer to new instance
5. **Decommission old instance**: After validation period

## Rollback Procedure

If issues occur after upgrade:

```bash theme={null}
# Rollback to previous version
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/v2.14.0/manifests/install.yaml

# Or restore from backup
docker run -i -v ~/.kube:/home/argocd/.kube --rm \
  quay.io/argoproj/argocd:v2.14.0 \
  argocd admin import - < backup-20260301.yaml
```

## Version-Specific Upgrade Guides

<CardGroup cols={3}>
  <Card title="v3.3 to v3.4" icon="arrow-up" href="https://argo-cd.readthedocs.io/en/stable/operator-manual/upgrading/3.3-3.4/">
    Latest minor version upgrade
  </Card>

  <Card title="v3.0 to v3.1" icon="arrow-up" href="https://argo-cd.readthedocs.io/en/stable/operator-manual/upgrading/3.0-3.1/">
    Minor version with new features
  </Card>

  <Card title="v2.14 to v3.0" icon="triangle-exclamation" href="https://argo-cd.readthedocs.io/en/stable/operator-manual/upgrading/2.14-3.0/">
    Major version upgrade guide
  </Card>
</CardGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Backup First" icon="database">
    Always create a backup before major version upgrades using `argocd admin export`.
  </Card>

  <Card title="Test Upgrades" icon="flask">
    Test upgrade procedures in non-production environments before applying to production.
  </Card>

  <Card title="Read Release Notes" icon="book">
    Carefully review release notes for breaking changes and required actions.
  </Card>

  <Card title="Monitor After Upgrade" icon="chart-line">
    Watch metrics and logs closely after upgrade to catch issues early.
  </Card>

  <Card title="Staged Rollout" icon="layer-group">
    Upgrade development → staging → production in stages with validation between.
  </Card>

  <Card title="Maintain Version Parity" icon="equals">
    Keep CLI version matched with server version to avoid compatibility issues.
  </Card>
</CardGroup>

## Related Resources

* [Disaster Recovery](/operations/disaster-recovery)
* [High Availability Setup](/operations/high-availability)
* [Monitoring](/operations/monitoring)