Argo CD
Argo CD is a declarative GitOps continuous delivery controller for Kubernetes. It compares the live state of applications in one or many clusters with the manifests in Git, reports any difference, and brings the cluster back to the declared state. It is a CNCF graduated project.
What it gives you
Section titled “What it gives you”| Capability | Detail |
|---|---|
| One unit per application | An Application groups the Deployments, Services, and other objects of a workload, so it is deployed, versioned, and managed as a whole |
| Multi-cluster delivery | One control plane deploys to many Kubernetes clusters |
| Drift detection | Live state is compared continuously, and differences are shown in the UI and API |
| Sync control | Manual approval, or automated sync with pruning and self-healing |
| Manifest tooling | Plain YAML, Helm, Kustomize, Jsonnet, and custom plugins |
| Access control | RBAC, local accounts, and single sign-on through OIDC providers or the bundled Dex server |
| Interfaces | Web UI, CLI, and a REST and gRPC API |
| Rollback and recovery | A rollback is a revert in Git. A lost cluster is rebuilt by installing Argo CD and pointing it at the same repository |
How it works
Section titled “How it works”- Raw manifests first. Argo CD works on Kubernetes YAML and behaves as much like
kubectlas it can. - Render, then apply. Helm and Kustomize output is rendered to plain manifests before it is applied. For Helm this uses
helm template, sohelm lsshows no releases for charts that Argo CD manages. In exchange, Argo CD can diff a Helm application against live state like any other. - Continuous reconciliation. Controllers pull declarations from Git on a timer or on a webhook and align running state with them.
- Declarative all the way down. Applications, projects, and Argo CD’s own settings are Kubernetes objects, so the installation can live in Git too.
flowchart LR
Git["Git or Helm repository"] --> Repo["Repo server<br/>renders manifests"]
Repo --> Ctrl["Application controller<br/>compares and syncs"]
Ctrl --> Cluster["Target clusters"]
User["UI, CLI, API"] --> API["API server"]
API --> Ctrl
Argo CD and Flux
Section titled “Argo CD and Flux”Flux and Argo CD are the two leading open-source GitOps controllers. They solve the same problem with different designs.
| Aspect | Argo CD | Flux |
|---|---|---|
| Design | A complete product with a UI, API, and RBAC | Composable controllers (the GitOps Toolkit), each doing one job |
| Helm | Renders with helm template, applies raw YAML | Installs charts through the Helm SDK as Helm releases |
helm ls | Shows nothing for Argo CD-managed charts | Lists the releases |
| Interface | Built-in web UI, RBAC, and multi-tenancy | Primarily CLI and API driven, with UIs added by other projects |
Neither is strictly better. Argo CD suits teams that want a visual application view and built-in access control. Flux suits teams that prefer to assemble their own tooling from smaller parts.
The Argo project
Section titled “The Argo project”Argo CD is one of four related projects. They work together or on their own.
| Project | Role |
|---|---|
| Argo Workflows | Workflow engine for parallel jobs and pipelines on Kubernetes, used for data pipelines and CI |
| Argo CD | GitOps continuous delivery |
| Argo Rollouts | Progressive delivery with canary and blue-green strategies, automated analysis, and rollback |
| Argo Events | Event-driven triggers for Kubernetes objects, workflows, and functions |
Before you start
Section titled “Before you start”You should be comfortable with:
- Kubernetes objects, namespaces, and
kubectl. See Kubernetes. - Git branching and pull requests.
- Helm charts or Kustomize overlays. See Application organisation and GitOps for a short introduction.
- The GitOps idea itself. See the GitOps overview.
Learning path
Section titled “Learning path”The pages are written to be read in this order. Each stage builds on the one before it.
| Stage | Read | You will be able to |
|---|---|---|
| 1. Get started | Architecture, Installation and access, Web UI and CLI, Declarative configuration and API | Explain the components, install Argo CD, log in, and manage its settings as code |
| 2. Deploy applications | Applications, Rendering tools | Deploy a workload from Git, Helm, or Kustomize and delete it safely |
| 3. Control how changes roll out | Sync policies and options, Phases, hooks, and waves, Diffing and ignore rules, Application health, Database schema walkthrough | Automate sync, order resources, silence false drift, and judge health |
| 4. Scale to many clusters and teams | Cluster management, Multi-tenancy and projects, App-of-apps and ApplicationSets | Register clusters, isolate teams, and generate applications at scale |
| 5. Secure it | Accounts and RBAC, Single sign-on, TLS and repository credentials, Commit signing and sync impersonation | Lock down access, connect an identity provider, and protect Git credentials |
| 6. Run it in production | CI integration and webhooks, Monitoring and notifications, High availability and scaling, Extending Argo CD | Connect pipelines, watch the system, size it, and extend it |
| 7. Put it together | Walkthrough: from commit to production | Run a full pipeline from a merge to a reviewed production release |
| Reference | Troubleshooting, Cheatsheet | Diagnose problems by symptom, and look up commands, annotations, and configuration keys |