Skip to content

Argo CD

Summary

Argo CD is a declarative GitOps continuous-delivery controller for Kubernetes and part of the CNCF-graduated Argo project (graduated 2022-12-06). It continuously reconciles clusters against manifests in Git, Helm or OCI sources, and adds a web UI with live diffs, SSO/RBAC multi-tenancy (AppProjects), sync waves and hooks, and ApplicationSets for fleet templating. The current stable line is 3.5 (3.5.3, 2026-09-14). 3.6 is in release candidate with GA planned for 2026-11-03. Only the three newest minors get fixes, so upgrade on a roughly quarterly rhythm.

Overview

Argo CD runs as a set of controllers in a management cluster. The application-controller compares rendered manifests from the repo-server with the live state it watches in every target cluster. It reports Synced/OutOfSync plus health, and optionally auto-syncs and self-heals. The classic model is hub-and-spoke push: one instance holds credentials for many clusters. The newer Argo CD Agent (argoproj-labs, pre-GA) inverts this into a pull model, where spokes dial into a central principal. The Source Hydrator (beta in 3.5) adds the rendered-manifest pattern by committing fully rendered YAML to Git before deploying it.

Key Facts

Attribute Detail
Latest Version 3.5.3 (2026-09-14); 3.6.0-rc1 in testing (GA planned 2026-11-03)
Supported minors 3.5, 3.4 (3.4.9), 3.3 (3.3.14); 3.2 and older are EOL
Release cadence Quarterly minors (Feb/May/Aug/Nov) after a 7-week RC period; 4.0 planned for 2027-11-02
Repository github.com/argoproj/argo-cd
Language Go (module github.com/argoproj/argo-cd/v3)
License Apache 2.0
Governance CNCF Graduated (Argo project: accepted 2020-03-26, graduated 2022-12-06)
Kubernetes tested (3.5) 1.33 to 1.36
Bundled renderers (3.5) Helm 4.2.1, Kustomize 5.8.1, Jsonnet, Config Management Plugins
Commercial distributions Akuity Platform, Codefresh GitOps, Red Hat OpenShift GitOps, and others

Evaluation

Pros Cons
Rich web UI with live diff, resource tree and logs Central hub concentrates credentials and is a high-value target (several critical CVEs in 2025-2026)
Multi-cluster from one pane of glass; the Agent adds pull-based spokes Classic hub needs network reach into every cluster API; the Agent is not yet GA
ApplicationSets (9 generators, Progressive Syncs beta) for fleets and preview environments Heavier footprint than Flux (Redis, repo-server, API server, Dex)
Helm (4.x since 3.5), Kustomize, Jsonnet, OCI sources, CMP plugins No built-in image automation (use Argo CD Image Updater or CI)
Sync phases, waves, PreSync/PostSync/SyncFail/PreDelete/PostDelete hooks RBAC plus AppProjects get complex at scale; 3.0 tightened defaults that need migration
Drift detection, self-heal, Server-Side Diff/Apply Monorepos need tuning (webhooks, manifest-generate-paths, shallow clone)
Large community, predictable quarterly releases, CNCF graduated Short support window: only 3 minors (about 9 months) get fixes

When It Fits

  • A platform team runs many clusters and wants visual status, self-service for app teams, and centralised policy.
  • You need ordered, hook-driven syncs (DB migrations, smoke tests, pre-delete data export).
  • You want the rendered-manifest pattern (Source Hydrator) or PR-driven environment promotion (GitOps Promoter).

Consider Flux instead for lightweight per-cluster controllers, built-in image automation, or when no inbound access to clusters is allowed and the Argo CD Agent is too immature for you. See the GitOps comparison.

Architecture at a Glance

The hub runs the Argo CD components. The controller renders desired state through the repo-server and reconciles it into each target cluster.

flowchart LR
    subgraph Hub["argocd namespace (management cluster)"]
        API["argocd-server<br/>(UI, API, SSO, RBAC)"]
        Ctrl["application-controller<br/>(diff, sync, health)"]
        Repo["repo-server<br/>(Helm 4, Kustomize, CMP)"]
        AS["applicationset-controller"]
        Redis[("Redis cache")]
    end
    Git["Git / Helm / OCI sources"]
    C1["Cluster A"]
    C2["Cluster B"]
    Repo -->|"fetch + render"| Git
    Ctrl -->|"desired state"| Repo
    Ctrl --- Redis
    API --- Redis
    AS -->|"generates Applications"| Ctrl
    Ctrl -->|"watch + apply"| C1
    Ctrl -->|"watch + apply"| C2

The detailed component, reconciliation, HA, Agent and Source Hydrator diagrams are in Explanation.

Recent Developments (3.x)

Release Highlights
3.0 (2025-05) Safer defaults: annotation-based tracking, fine-grained RBAC without inheritance, logs RBAC always enforced, default resource.exclusions, legacy repo config removed
3.1 (2025-08) OIDC PKCE handled server-side; v1 Actions API deprecated; Helm 3.18 / Kustomize 5.7
3.2 (2025-11) Kustomize version from .argocd-source.yaml respected; hydrator path rules tightened
3.3 (2026-02) PreDelete hooks, background OIDC token refresh, shallow clone, Progressive Syncs beta; manifests now need server-side apply
3.4 (2026-05) Per-cluster reconciliation pause (skip-reconcile on cluster Secret), Microsoft Teams Workflows notifications, annotation and operation-status filters in the app list
3.5 (2026-08) Helm 4, repo-server mTLS, Source Integrity (commit signature verification), ApplicationSet UI, impersonation and Source Hydrator promoted to beta
3.6 (RC, GA planned 2026-11-03) ServerSideApply=true implies Server-Side Diff (Structured-Merge diff removed), OTLP env var rename

The full breaking-change tables, feature-maturity list and CVE table are in Reference.

Security advisories

CVE-2026-42880 (CVSS 9.6) let read-only users extract Secret data through ServerSideDiff in 3.2.0 to 3.2.10 and 3.3.0 to 3.3.8 (fixed in 3.2.11 and 3.3.9). CVE-2025-55190 (critical) exposed repository credentials to project API tokens (fixed in 2.13.9, 2.14.16, 3.0.14, 3.1.2). Details: Reference.

Topic Map

  • How-to Guides: install, SSO, AppProjects, ApplicationSets, HA and sharding, mTLS, Source Hydrator, tuning, monitoring, upgrade, troubleshooting (Commands & Recipes).
  • Reference: support matrix, per-minor breaking changes, feature maturity, CVEs, ports, config keys, RBAC matrix, generators, hooks, metrics, sizing, hardening checklist.
  • Explanation: components, reconciliation and diff model, sync phases, ApplicationSets, HA, classic vs Agent multi-cluster, Source Hydrator, security model.

Sources

Questions

Open

  • When will argocd-agent reach GA, and will it move from argoproj-labs into the core project? The README (2026-09) says it is "working toward GA". Track the repository and Explanation: Argo CD Agent.
  • Will the Source Hydrator become enabled by default (and the install-with-hydrator.yaml variant be dropped)? Its docs say this will be announced in an upgrade note.
  • What does 4.0 (planned 2027-11-02) break? No upgrade notes exist yet.

Answered

  • Q: When were 3.4.9 and 3.3.14 released? 3.4.9 on 2026-09-14 and 3.3.14 on 2026-08-12, taken from the commit dates of the v3.4.9 and v3.3.14 tags (see Reference).
  • Q: What is the performance impact at 1,000+ Applications? Argo CD handles 1,000+ applications with tuning. The main bottlenecks are: (1) argocd-repo-server CPU during manifest rendering: scale to 2+ replicas and bound reposerver.parallelism.limit. (2) argocd-application-controller memory and queue depth: raise controller.status.processors (default 20) and controller.operation.processors (default 10) in argocd-cmd-params-cm. (3) Redis cache pressure: use the redis-ha topology. When the controller is saturated, shard it by cluster (StatefulSet replicas plus ARGOCD_CONTROLLER_REPLICAS). Use webhooks and manifest-generate-paths for monorepos, and watch argocd_app_reconcile and argocd_kubectl_exec_pending. See How-to: Tune Performance and the HA docs.
  • Q: Best practice for Argo CD plus Vault/SOPS secret management? Use External Secrets Operator. Argo CD deploys ExternalSecret/SecretStore and ESO fetches values from Vault, AWS SM, GCP SM or Azure KV, so secrets never pass through Argo CD. Alternatives are SOPS with KSOPS, Sealed Secrets, or Argo CD Vault Plugin (render-time injection, which the Argo CD docs discourage because values land in the repo-server cache). See Explanation: Encryption and Secrets and the ESO Vault provider docs.
  • Q: Does Argo CD support Helm v4? Yes, since 3.5 (Helm 4.2.x). spec.source.helm.version: v3 is ignored, and plain-HTTP OCI registries must be flagged with --insecure-oci-force-http (3.4 to 3.5 notes). This supersedes the earlier "not yet as of 3.3" answer.
  • Q: Which Argo CD versions are supported right now? 3.5, 3.4 and 3.3, the three newest minors (SECURITY.md). 3.3 drops out when 3.6 reaches GA.