What ArgoCD is and why teams adopt it
ArgoCD is a Kubernetes controller that implements GitOps. You describe what should run in a git repository as Helm charts, Kustomize overlays or plain manifests. ArgoCD compares that desired state with the live cluster and reports the difference as an Application, which is either in sync or out of sync. It can apply the change automatically or wait for a human.
Teams adopt it for four reasons: every change has a commit and an author, rollback is a revert, cluster credentials stay inside the cluster rather than in CI, and the web UI makes the state of every application visible to developers who do not live in kubectl. As ArgoCD consulting specialists, we see it succeed when the surrounding design is right, and stall when it is installed and left alone. For the definition, see our ArgoCD glossary entry.
How we run ArgoCD in production
Repository model first
We settle structure before installing anything. The usual choice is a separate configuration repository from application source, with a directory per environment and a clear promotion path. Our guidance is detailed in GitOps repository structure design and multi-environment promotion with Kustomize.
ApplicationSets for scale
Writing one Application per service per cluster does not scale. An ApplicationSet generates Applications from a template, driven by a list, a git directory structure or the clusters you have registered.
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: platform-addons
namespace: argocd
spec:
generators:
- clusters:
selector:
matchLabels:
env: production
template:
metadata:
name: "ingress-{{name}}"
spec:
project: platform
source:
repoURL: https://github.com/your-org/platform-config.git
targetRevision: main
path: addons/ingress
destination:
server: "{{server}}"
namespace: ingress
syncPolicy:
syncOptions: [CreateNamespace=true]
New clusters labelled env: production receive the ingress add-on automatically. See ApplicationSets for multi-cluster for the full pattern.
Sync policy by environment
Automated sync with self-heal suits development and staging. In production we often keep sync manual or use sync windows, and enable pruning deliberately, because auto-pruning a mistaken deletion removes real resources. See drift detection and sync policies.
Rendering, health and ignored differences
ArgoCD renders Helm charts and Kustomize overlays in its repository server, then compares the result with live objects. Some fields are legitimately changed by other controllers, such as replica counts managed by an autoscaler or annotations injected by a service mesh. Left alone, these show as permanently out of sync and teach people to ignore the dashboard. We add targeted ignore rules for those fields only, and use resource health checks so an application is not reported healthy until its rollout has actually completed. The aim is a status colour that engineers trust.
Security and access
- SSO, not the admin account. Connect your identity provider and disable the built-in admin once SSO works.
- Projects as boundaries. An AppProject restricts which repositories, clusters and namespaces a team can use, and which resource kinds they may create.
- RBAC mapped to groups. Developers can view and sync their applications, platform engineers manage the rest. Details in GitOps RBAC and access control.
- Scoped cluster access. Avoid giving ArgoCD cluster-admin on every cluster when namespace-scoped permissions will do.
- Secrets. Use External Secrets Operator or Sealed Secrets rather than committing credentials. See Sealed Secrets and External Secrets Operator.
- Repository credentials. Use read-only deploy keys or app tokens per repository.
Cost and capacity
ArgoCD is open source, so cost is the cluster resources and the people time. Its main components are the API server, repository server, application controller and Redis. The repository server renders Helm and Kustomize and is often the first to need more memory; the application controller scales with the number of resources it watches. For large fleets we shard the controller, tune refresh intervals and avoid watching resources that churn constantly. A central ArgoCD managing many clusters is convenient but makes it a high-value target and a single point of coordination, so some organisations run one instance per environment tier.
Day-2 operations
- Upgrade through git, one minor version at a time, in a lower environment first, reading the release notes for changes.
- Monitor controller health, sync failures and reconciliation latency through Prometheus and Grafana.
- Notify teams on sync failures and deployments. See GitOps deployment notifications.
- Back up by keeping all ArgoCD configuration in git; recovery is a reinstall.
- Progressive delivery with Argo Rollouts adds canary and blue-green releases, covered in progressive delivery.
Failure modes we avoid
| Problem | Cause | Fix |
|---|---|---|
| Perpetual OutOfSync | Controllers mutating fields | Ignore differences for those fields |
| Accidental mass deletion | Auto-prune with a bad commit | Manual prune in production, sync windows |
| Slow syncs | Overloaded repository server | More resources, manifest caching |
| Team escalation | Broad default project | Dedicated AppProjects |
| Plaintext secrets in git | No secrets strategy | External or sealed secrets |
When not to use ArgoCD, and how it compares
For a single small cluster with one team, a pipeline running helm upgrade may be enough for now. If you want lean controllers, tight Helm and OCI integration, and no UI, look at Flux. We compare them directly in our installation guide for both. ArgoCD pairs naturally with Helm, and CI tools such as GitHub Actions build the images it deploys. A worked example is in our GitOps with ArgoCD on EKS tutorial.
Ready to move to GitOps? See the GitOps service or talk to us.
Official documentation: argo-cd.readthedocs.io