Where Argo CD fits in delivery
Argo CD is a declarative GitOps continuous delivery tool for Kubernetes, licensed under Apache 2.0 and part of the Argo project, a CNCF graduated project since December 2022. Its application controller compares live state with the desired state in Git, marks drift as OutOfSync and can correct it automatically or wait for an operator.
Argo CD does not build images or run tests. A CI system produces artifacts and updates manifests, Helm values or Kustomize overlays in Git, and Argo CD applies what Git describes. Once it is in place, permission to merge into a deployment repository is permission to change a cluster, so branch protection and path ownership become production change controls.
What runs inside an Argo CD installation
Most state lives in Kubernetes objects, which shapes scaling and recovery.
API server
Serves the UI, CLI and API, manages repository and cluster credentials, enforces RBAC and receives Git webhooks.
Repository server
Caches Git repositories and renders manifests with Helm, Kustomize or plain YAML. It holds no Kubernetes privileges, but large repositories drive its memory use.
Application controller
Compares live and desired state, runs syncs and hooks, and needs cluster-wide read access to every managed cluster. It is the component sharded at scale.
ApplicationSet controller
Generates Applications from templates using list, cluster, Git and matrix generators. Bundled since version 2.3.
Redis
A cache for rendered manifests and state that can be rebuilt without service disruption.
Dex and notifications
Dex is an optional identity broker for providers without OIDC. Notifications sends sync and health events to services such as Slack or email.
Choose a control topology
One instance manages many clusters, each registered as a cluster secret. Operators get one place for visibility and policy, but that instance holds credentials for every cluster, so its namespace and administrators need the strictest controls in the estate.
Each cluster runs its own Argo CD and deploys only to itself. A misconfiguration stays local, and air-gapped sites need no inbound path from a central controller. The cost is more instances to upgrade and keep consistent.
A common pattern is one instance for non-production clusters and a separate one for production. Production credentials stay out of the instance that development teams use daily.
Load grows with the number of Applications, clusters, resources per cluster and how often manifests render. Monorepos and heavily templated Helm charts stress the repository server. Measure reconciliation time and memory during a pilot before choosing replica counts.
Define project boundaries before onboarding teams
AppProjects decide what each team may deploy, from where and to where. The built-in default project permits any repository, any cluster and all resource kinds.
| Control | What it restricts | Practice |
|---|---|---|
| Source repositories | Which repositories a project's Applications may use. | List specific repositories per team, and scope repository credentials to projects. Limit push access to admin-level project repositories. |
| Destinations | Which clusters and namespaces Applications may target. | Give each team its own namespaces. Never let a team project deploy into the Argo CD namespace, which grants admin access. |
| Resource kinds | Which cluster-scoped and namespaced kinds may be created. | Deny cluster-scoped kinds by default and allow only what a team needs. |
| Project roles | Permissions for groups and automation tokens. | Give CI an expiring JWT token that can sync one application without changing its source or destination. |
Connect SSO and limit what Argo CD can change
Connect Argo CD directly to an OIDC provider such as Keycloak, Entra ID or Okta, or use the bundled Dex when you need to broker SAML, LDAP or GitHub organizations. Map group claims to roles in argocd-rbac-cm, set policy.default to the most restrictive workable role, and disable the built-in admin account once SSO works.
By default, the application controller and API server use a cluster-admin level role. Argo CD needs cluster-wide read access, but write access can be narrowed to specific namespaces and resource kinds through its ClusterRoles. Disable configuration management tools you do not use.
Keep secrets out of rendered manifests. Argo CD's documentation strongly recommends populating secrets on the destination cluster, for example with an external secrets operator, and cautions against injecting them during manifest generation. Set a minimum TLS version on the API server, and configure TLS for Redis explicitly, because Redis traffic is unencrypted by default.
Run it highly available and scale the controllers
Argo CD's HA manifests run more replicas and Redis in a sentinel topology, and need at least three nodes because of pod anti-affinity. Run three or more API server replicas for zero-downtime upgrades. Dex keeps data in memory, so multiple Dex replicas can disagree, which favors direct OIDC in larger installations.
Scale the repository server horizontally and cap concurrent rendering with its parallelism limit. For many clusters, shard the application controller by raising its replicas and setting ARGOCD_CONTROLLER_REPLICAS to match. In large monorepos, the manifest-generate-paths annotation limits which Applications a commit refreshes.
Plan recovery and upgrades
Projects, cluster secrets, repository credentials, RBAC and settings live as Kubernetes objects. Export them on a schedule with argocd admin export at the running version, pass the namespace explicitly, and protect the output as a secret. The export does not fail in the wrong namespace, so check it.
Install the same version, run argocd admin import, then confirm clusters connect and Applications reconcile without unexpected syncs. Redis needs no backup. Rehearse on a spare cluster.
A minor release ships every three months, and only the three most recent minors receive patches. Read the notes for every minor version crossed, back up before major versions, and apply the full manifests with server-side apply.
Argo CD can manage its own installation from Git with ServerSideApply enabled. Keep a manual recovery path, since a broken self-managing instance cannot repair itself.
Argo CD operating ownership
The platform team runs Argo CD. Application teams own what their repositories declare. Security owns the boundaries between them.
Platform team
- Monitor sync failures, reconciliation time and repository server memory.
- Stay within the three supported minor versions.
- Run scheduled exports and restore rehearsals.
Application teams
- Own manifests, values and sync policies.
- Resolve drift and failed hooks.
- Request project changes through review.
Security
- Review AppProject destinations, kinds and roles.
- Rotate cluster and repository credentials.
- Approve changes to Argo CD RBAC and ClusterRoles.
Change record
- Keep Argo CD configuration in Git.
- Record registered clusters and owners.
- Log upgrades and the checks run.
Argo CD deployment questions
Should we enable automated sync everywhere?
Automated sync with self-heal suits environments where Git is the only accepted change path. For production, consider starting with manual sync or automated sync without pruning, then tighten as teams gain confidence.
Dex or direct OIDC?
Use direct OIDC when your provider returns group claims. Use Dex to broker SAML, LDAP or GitHub organizations. Test group mapping and logout with ordinary accounts either way.
How do CI pipelines trigger deployments?
Usually by committing a new image tag or values change to Git. If a pipeline must call Argo CD directly, give it a project role token limited to one application.
Scope and handover
DeployOpen designs the control topology with your platform team, installs Argo CD in HA form inside your clusters, integrates SSO and RBAC, defines AppProjects for the first teams, narrows cluster privileges and sets up a secrets pattern that keeps plaintext out of Git. We set up export-based backups, rehearse a restore, plan upgrades within the supported window, document the platform and can provide ongoing support.
Handover includes the topology decision, configuration in Git, the RBAC and group mapping, an AppProject template for new teams, the cluster inventory with credential rotation plan, the latest restore result and the current version with its support status.
